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.pem

If 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 serial

Install 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/html

Edit one line in webcert-[version]/src/Makefile:

susie112:~ # vi src/Makefile
[6]    CGIDIR=/var/www/html/webcert/cgi-bin

Edit 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       TRUE

Comment [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/export

The 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/export

Now 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.


OpenSSL Logo

Topics: