Software dependencies
Webcert is a web-based 'C' application using CGI technology. It relies on Thomas Boutell's CGIC library and OpenSSL, the leading OpenSource security layer software. To compile it from source, you'll need a working 'C' compiler environment such as gcc.
Preparations - creating a OpenSSL CA
You just downloaded the software package https://github.com/fm4dd/webcert/archive/master.zip, extracted it to /tmp and looked into the README. You want to install webcert into "/var/www/html" instead of my chosen "/srv/www/std-root/frank4dd.com/sw" path and you would like to change the the CA directory structure from my "/srv/app/webCA" to "/var/myCA". Here is what you should do in order to make it all work.
First, before we start unpacking the software package, we create the CA directory structure with OpenSSL. We need to locate the script CA.pl, which is normally located in [openssl-home]/misc. Depending on your distributions OpenSSL deployment, this could be similar to OpenSuse and SLES, where it is found in /usr/share/ssl/misc/CA.pl. We need to edit this script and change the line to match our new CA directory: [line numbers are in brackets]
susie112:~ # vi /usr/share/ssl/misc/CA.pl
[47] $CATOP="/var/myCA";Then we run it as root:
susie112:~ # /usr/share/ssl/misc/CA.pl -newca
CA certificate filename (or enter to create)
Making CA certificate ...
Generating a 1024 bit RSA private key
......++++++
...................++++++
writing new private key to '/var/myCA/private/cakey.pem'
Enter PEM pass phrase: <-- please remember this password!
Verifying - Enter PEM pass phrase:
-----
You are about to be asked to enter information that will be incorporated
into your certificate request.
What you are about to enter is what is called a Distinguished Name or a DN.
There are quite a few fields but you can leave some blank
For some fields there will be a default value,
If you enter '.', the field will be left blank.
-----
Country Name (2 letter code) [US]:
State or Province Name (full name) [CA]:
Locality Name (eg, city) [Rocklin]:
Organization Name (eg, company) [Frank4DD]:
Organizational Unit Name (eg, section) []:
Common Name (eg, YOUR name) []:WebCert CA
Email Address []:
susie112:/home/openssl/misc # Now lets check the created file structures:
susie112:~ # ls -lR /var/myCA
/var/myCA:
total 4
drwxr-xr-x 5 root root 184 2005-06-28 13:10 .
drwxr-xr-x 16 root root 408 2005-06-28 13:10 ..
-rw-r--r-- 1 root root 1034 2005-06-28 13:10 cacert.pem
drwxr-xr-x 2 root root 48 2005-06-28 13:10 certs
drwxr-xr-x 2 root root 48 2005-06-28 13:10 crl
-rw-r--r-- 1 root root 0 2005-06-28 13:10 index.txt
drwxr-xr-x 2 root root 80 2005-06-28 13:10 private
/var/myCA/certs:
total 0
drwxr-xr-x 2 root root 48 2005-06-28 13:10 .
drwxr-xr-x 5 root root 184 2005-06-28 13:10 ..
/var/myCA/crl:
total 0
drwxr-xr-x 2 root root 48 2005-06-28 13:10 .
drwxr-xr-x 5 root root 184 2005-06-28 13:10 ..
/var/myCA/private:
total 4
drwxr-xr-x 2 root root 80 2005-06-28 13:10 .
drwxr-xr-x 5 root root 184 2005-06-28 13:10 ..
-rw-r--r-- 1 root root 951 2005-06-28 13:10 cakey.pemIf not already created, we need to create theCA's serial number file. We also need to make this file writeable to the webserver, and the same goes for the certs directory.
susie112:/var/myCA # echo 01 > serial
susie112:/var/myCA # chown wwwrun:www serial
susie112:/var/myCA # chmod 664 serial
susie112:/var/myCA # chown wwwrun:www certs
susie112:/var/myCA # chmod 775 certs
susie112:/var/myCA # ls -l
total 8
drwxr-xr-x 5 root root 208 2005-06-28 13:25 .
drwxr-xr-x 16 root root 408 2005-06-28 13:10 ..
-rw-r--r-- 1 root root 1034 2005-06-28 13:10 cacert.pem
drwxrwxr-x 2 wwwrun www 48 2005-06-28 13:10 certs
drwxr-xr-x 2 root root 48 2005-06-28 13:10 crl
-rw-r--r-- 1 root root 0 2005-06-28 13:10 index.txt
drwxr-xr-x 2 root root 80 2005-06-28 13:10 private
-rw-rw-r-- 1 wwwrun www 3 2005-06-28 13:25 serialInstall The WebCert software package
Now we can un-tar the software package and change the software source package config files to match your setup [line numbers are in brackets]. Edit one line in webcert-[version]/Makefile:
susie112:~ # vi Makefile
[3] BASEDIR=/var/www/htmlEdit one line in webcert-[version]/src/Makefile:
susie112:~ # vi src/Makefile
[6] CGIDIR=/var/www/html/webcert/cgi-binEdit the following lines in webcert-[version]/src/webcert.h:
susie112:~ # vi src/webcert.h
[11] #define HOMELINK /webcert/
[13] #define REQLINK /webcert/cgi-bin/certrequest.cgi
[15] #define CACERT /var/myCA/cacert.pem
[17] #define CAKEY /var/myCA/private/cakey.pem
[19] #define PASS (password entered during the run of CA.pl above)
[21] #define CACERTSTORE /var/myCA/certs
[23] #define CERTEXPORTDIR /var/www/html/webcert/export
[25] #define CERTEXPORTURL /webcert/export
[27] #define SERIALFILE /var/myCA/serial
[29] #define DAYS_VALID 1095 (set the default expiration, = 3 years)
...
[34] #define FORCE_SOURCE_IP_INCLUSION TRUEComment [34] out to remove the automatic inclusion of the client IP address in the certificate subject. This function is meant as a security measure on the public demo I am running to prevent abuse.
Next, we create "/var/www/html/webcert" and the sub-directories "images", "cgi-bin", "etc", "results" and "style".
susie112:/home # mkdir -p /var/www/html/webcert
susie112:~ # mkdir /var/www/html/webcert/images
susie112:~ # mkdir /var/www/html/webcert/cgi-bin
susie112:~ # mkdir /var/www/html/webcert/style
susie112:~ # mkdir /var/www/html/webcert/exportThe export directory must be writeable by the webserver. It will be used to cache the exported certificates in pem, der or pkcs12 format for download.
susie112:~ # chown wwwrun:www /var/www/html/webcert/exportNow we can compile and install the software as root with "make" and "make install".
susie112:/tmp/webcert-v1.7.3 # make
cd src && make
make[1]: Entering directory `/tmp/webcert-v1.7.3/src'
gcc -O3 -Wall -g -c -o buildrequest.o buildrequest.c
gcc -O3 -Wall -g -c -o pagehead.o pagehead.c
gcc -O3 -Wall -g -c -o handle_error.o handle_error.c
gcc -L/home/lib -lcgic -lm -lssl -lcrypto buildrequest.o pagehead.o -o buildrequest.cgi
...
gcc -O3 -Wall -g -c -o certexport.o certexport.c
gcc -L/home/lib -lcgic -lm -lssl -lcrypto certexport.o pagehead.o handle_error.o -o certexport.cgi
make[1]: Leaving directory `/tmp/webcert-v1.7.3/src'
susie112:/tmp/webcert-v1.7.3 # make install
cp html/index.htm /var/www/html/webcert
cp style/style.css /var/www/html/webcert/style
cp images/webcert-icon.gif images/webcert-logo.gif images/cert.gif /var/www/html/webcert/images
cp doc/help.txt doc/capolicy.txt /var/www/html/webcert/cgi-bin
cd src && make install
make[1]: Entering directory `/tmp/webcert-v1.7.3/src'
strip buildrequest.cgi genrequest.cgi certsign.cgi certrequest.cgi certverify.cgi showhtml.cgi getcert.cgi certstore.cgi certsearch.cgi certexport.cgi
cp buildrequest.cgi genrequest.cgi certsign.cgi certrequest.cgi certverify.cgi showhtml.cgi getcert.cgi certstore.cgi certsearch.cgi certexport.cgi /var/www/html/webcert/cgi-bin
buildrequest.cgi genrequest.cgi certsign.cgi certrequest.cgi certverify.cgi showhtml.cgi getcert.cgi certstore.cgi certsearch.cgi certexport.cgi installed in /var/www/html/webcert/cgi-bin.
Checking for new export dir needed by certexport.cgi:
...OK. /var/www/html/webcert/cgi-bin/../export exists.
make[1]: Leaving directory `/tmp/webcert-v1.7.3/src'After the compilation and installation, the file structure should look like this (please compare carefully):
susie112:~ # ls -lR /var/www/html/webcert
/var/www/html/webcert:
total 112
-rwxr-xr-x 1 root root 7457 Feb 28 10:21 about.htm
drwxr-xr-x 2 root root 4096 Feb 28 10:49 cgi-bin
-rwxr-xr-x 1 root root 13239 Feb 28 10:48 changelog.htm
drwxr-xr-x 2 wwwrun www 4096 Feb 28 10:45 export
-rwxr-xr-x 1 root root 683 Feb 28 10:48 footer.htm
-rwxr-xr-x 1 root root 11634 Feb 28 10:45 help.htm
drwxr-xr-x 2 root root 4096 Feb 28 10:15 images
-rwxr-xr-x 1 root root 1611 Feb 28 10:33 index.htm
-rwxr-xr-x 1 root root 15417 Feb 28 10:14 install.htm
-rwxr-xr-x 1 root root 4920 Feb 28 10:50 policy.htm
-rwxr-xr-x 1 root root 3273 Feb 28 10:46 roadmap.htm
-rwxr-xr-x 1 root root 1015 Feb 28 10:53 sidebar.htm
drwxr-xr-x 2 root root 4096 Feb 28 10:19 style
-rw-r--r-- 1 root root 831 Feb 28 10:34 webcert.js
/var/www/html/webcert/cgi-bin:
total 600
-rwxr-xr-x 1 root root 42752 Feb 28 10:34 buildrequest.cgi
-rwxr-xr-x 1 root root 46944 Feb 28 10:34 certexport.cgi
-rwxr-xr-x 1 root root 72936 Feb 28 10:34 certrenew.cgi
-rwxr-xr-x 1 root root 34560 Feb 28 10:34 certrequest.cgi
-rwxr-xr-x 1 root root 63388 Feb 28 10:34 certsearch.cgi
-rwxr-xr-x 1 root root 55316 Feb 28 10:34 certsign.cgi
-rwxr-xr-x 1 root root 46976 Feb 28 10:34 certstore.cgi
-rwxr-xr-x 1 root root 71808 Feb 28 10:34 certvalidate.cgi
-rwxr-xr-x 1 root root 46960 Feb 28 10:34 certverify.cgi
-rwxr-xr-x 1 root root 51160 Feb 28 10:34 genrequest.cgi
-rwxr-xr-x 1 root root 42784 Feb 28 10:34 getcert.cgi
-rwxr-xr-x 1 root root 85384 Feb 28 10:34 p12convert.cgi
-rwxr-xr-x 1 root root 39592 Feb 28 10:34 showhtml.cgi
/var/www/html/webcert/images:
total 472
-rw-r--r-- 1 root root 1081 Feb 28 10:58 bgplastic-button.gif
-rw-r--r-- 1 root root 351 Feb 28 10:58 bgplastic.gif
-rw-r--r-- 1 root root 1112 Feb 28 10:58 bgplastic-red.gif
-rw-r--r-- 1 root root 46493 Feb 28 10:58 cert.gif
-rw-r--r-- 1 root root 4924 Feb 28 10:58 logo.gif
-rw-r--r-- 1 root root 10958 Feb 28 10:58 new-certificate-data-entry-icon.png
-rw-r--r-- 1 root root 50737 Feb 28 10:58 new-certificate-data-entry.png
-rw-r--r-- 1 root root 9414 Feb 28 10:58 new-certificate-generated-icon.png
-rw-r--r-- 1 root root 28718 Feb 28 10:58 new-certificate-generated.png
-rw-r--r-- 1 root root 8178 Feb 28 10:58 new-certificate-key-and_extensions-icon.png
-rw-r--r-- 1 root root 50005 Feb 28 10:58 new-certificate-key-and_extensions.png
-rw-r--r-- 1 root root 3069 Feb 28 10:58 openssl_button.gif
-rw-r--r-- 1 root root 8414 Feb 28 10:58 webcert-certificate-p12convert-icon.png
-rw-r--r-- 1 root root 12046 Feb 28 10:58 webcert-certificate-rootca-icon.png
-rw-r--r-- 1 root root 16028 Feb 28 10:58 webcert-certificate-search-icon.png
-rw-r--r-- 1 root root 36021 Feb 28 10:58 webcert-certificate-search.png
-rw-r--r-- 1 root root 12734 Feb 28 10:58 webcert-certificate-store-icon.png
-rw-r--r-- 1 root root 42062 Feb 28 10:58 webcert-certificate-store.png
-rw-r--r-- 1 root root 12034 Feb 28 10:58 webcert-certificate-validation-icon.png
-rw-r--r-- 1 root root 42863 Feb 28 10:58 webcert-certificate-validation.png
-rw-r--r-- 1 root root 2880 Feb 28 10:58 webcert-icon.gif
-rw-r--r-- 1 root root 4737 Feb 28 10:58 webcert-logo.gif
-rw-r--r-- 1 root root 10251 Feb 28 10:58 webcert-request-paste-icon.png
-rw-r--r-- 1 root root 29994 Feb 28 10:58 webcert-request-paste.png
/var/www/html/webcert/style:
total 8
-rwxr-xr-x 1 root root 7324 Feb 28 10:22 style.css
/var/www/html/webcert/export:
drwxr-xr-x 2 wwwrun www 80 2005-06-28 13:45 .
drwxr-xr-x 5 root root 152 2005-06-28 13:45 ..Remaining Tasks - Webserver Configuration
After the installation, check the webserver configuration and declare the alias for /webcert/cgi-bin/ to match /var/www/html/webcert/cgi-bin/. Restart the webserver and check if the buildrequest.cgi page comes up properly. Assuming the webservers document root is in /var/www/html, we point the browser to http(s)://[your-ip-or-name]/webcert/ and we'll be forwarded to the buildrequest.cgi screen. Your apache configuration could look like this:
susie112:~ # vi /etc/apache/vhosts.d/vhost.conf
<VirtualHost 192.168.103.32:443>
...
# Configure the CGI directories
ScriptAlias /webcert/cgi-bin/ "/var/www/html/webcert/cgi-bin/"
<Directory "/var/www/html/webcert/cgi-bin">
Options +ExecCGI
AllowOverride None
Order allow,deny
Allow from all
</Directory>
<Directory "/var/www/html/webcert/export">
# Force cert files as download (requires mod_headers)
<Files *.der>
ForceType application/octet-stream
Header set Content-Disposition attachment
</Files>
<Files *.pem>
ForceType application/octet-stream
Header set Content-Disposition attachment
</Files>
<Files *.p12>
ForceType application/octet-stream
Header set Content-Disposition attachment
</Files>
</Directory>
...
</VirtualHost>First Test - Create a sample certificate
Please fill out the template to generate your first certificate. If all goes well, your request will be signed and a new certificate is placed in the CA store. The menu item "List Certificates" should display your first cert.
Enjoy WebCert!
Contact and Appreciation
Please let me know if these instructions are OK to follow and on which stage you run into a problem. If I learn were something isn't made clear, it will help me to improve the documentation.
Please send your comments and complaints to support[at]frank4dd.com and be patient with me for a response.
If you want to do something really nice and encouraging besides just saying "Thanks", send me a photo picture of the area you are living in, either your town, your work, local sights or of your neighborhood. I enjoy collecting pictures from all over the world, and maybe I'll start a gallery.