michael@0: How to setup your very own Cert-O-Matic Root CA server
michael@0:
michael@0: This Source Code Form is subject to the terms of the Mozilla Public
michael@0: # License, v. 2.0. If a copy of the MPL was not distributed with this
michael@0: # file, You can obtain one at http://mozilla.org/MPL/2.0/.
michael@0:
michael@0: How to setup your very own Cert-O-Matic Root CA server
michael@0:
michael@0: The program certcgi is part of a small test CA that is used inside
michael@0: Netscape by the NSS development team. That CA is affectionately known
michael@0: as "Cert-O-Matic" or "Cert-O-Matic II". It presently runs on a server
michael@0: named interzone.mcom.com inside Netscape's firewall.
michael@0:
michael@0: If you wish to setup your own Cert-O-Matic, here are directions.
michael@0:
michael@0: Disclaimer: This program does not follow good practices for root CAs.
michael@0: It should be used only for playing/testing and never for production use.
michael@0: Remember, you've been warned!
michael@0:
michael@0: Cert-O-Matic consists of some html files, shell scripts, one executable
michael@0: program that uses NSS and NSPR, the usual set of NSS .db files, and a file
michael@0: in which to remember the serial number of the last cert issued. The
michael@0: html files and the source to the executable program are in this directory.
michael@0: Sample shell scripts are shown below.
michael@0:
michael@0: The shell scripts and executable program run as CGI "scripts". The
michael@0: entire thing runs on an ordinary http web server. It would also run on
michael@0: an https web server. The shell scripts and html files must be
michael@0: customized for the server on which they run.
michael@0:
michael@0: The package assumes you have a "document root" directory $DOCROOT, and a
michael@0: "cgi-bin" directory $CGIBIN. In this example, the document root is
michael@0: assumed to be located in /var/www/htdocs, and the cgi-bin directory in
michael@0: /var/www/cgi-bin.
michael@0:
michael@0: The server is assumed to run all cgi scripts as the user "nobody".
michael@0: The names of the cgi scripts run directly by the server all end in .cgi
michael@0: because some servers like it that way.
michael@0:
michael@0: Instructions:
michael@0:
michael@0: - Create directory $DOCROOT/certomatic
michael@0: - Copy the following files from nss/cmd/certcgi to $DOCROOT/certomatic
michael@0: ca.html index.html main.html nscp_ext_form.html stnd_ext_form.html
michael@0: - Edit the html files, substituting the name of your own server for the
michael@0: server named in those files.
michael@0: - In some web page (e.g. your server's home page), provide an html link to
michael@0: $DOCROOT/certomatic/index.html. This is where users start to get their
michael@0: own certs from certomatic.
michael@0: - give these files and directories appropriate permissions.
michael@0:
michael@0: - Create directories $CGIBIN/certomatic and $CGIBIN/certomatic/bin
michael@0: make sure that $CGIBIN/certomatic is writable by "nobody"
michael@0:
michael@0: - Create a new set of NSS db files there with the following command:
michael@0:
michael@0: certutil -N -d $CGIBIN/certomatic
michael@0:
michael@0: - when certutil prompts you for the password, enter the word foo
michael@0: because that is compiled into the certcgi program.
michael@0:
michael@0: - Create the new Root CA cert with this command
michael@0:
michael@0: certutil -S -x -d $CGIBIN/certomatic -n "Cert-O-Matic II" \
michael@0: -s "CN=Cert-O-Matic II, O=Cert-O-Matic II" -t TCu,cu,cu -k rsa \
michael@0: -g 1024 -m 10001 -v 60
michael@0:
michael@0: (adjust the -g, -m and -v parameters to taste. -s and -x must be as
michael@0: shown.)
michael@0:
michael@0: - dump out the new root CA cert in base64 encoding:
michael@0:
michael@0: certutil -d $CGIBIN/certomatic -L -n "Cert-O-Matic II" -a > \
michael@0: $CGIBIN/certomatic/root.cacert
michael@0:
michael@0: - In $CGIBIN/certomatic/bin add two shell scripts - one to download the
michael@0: root CA cert on demand, and one to run the certcgi program.
michael@0:
michael@0: download.cgi, the script to install the root CA cert into a browser on
michael@0: demand, is this:
michael@0:
michael@0: #!/bin/sh
michael@0: echo "Content-type: application/x-x509-ca-cert"
michael@0: echo
michael@0: cat $CGIBIN/certomatic/root.cacert
michael@0:
michael@0: You'll have to put the real path into that cat command because CGIBIN
michael@0: won't be defined when this script is run by the server.
michael@0:
michael@0: certcgi.cgi, the script to run the certcgi program is similar to this:
michael@0:
michael@0: #!/bin/sh
michael@0: cd $CGIBIN/certomatic/bin
michael@0: LD_LIBRARY_PATH=$PLATFORM/lib
michael@0: export LD_LIBRARY_PATH
michael@0: $PLATFORM/bin/certcgi $* 2>&1
michael@0:
michael@0: Where $PLATFORM/lib is where the NSPR nad NSS DSOs are located, and
michael@0: $PLATFORM/bin is where certcgi is located. PLATFORM is not defined when
michael@0: the server runs this script, so you'll have to substitute the right value
michael@0: in your script. certcgi requires that the working directory be one level
michael@0: below the NSS DBs, that is, the DBs are accessed in the directory "..".
michael@0:
michael@0: You'll want to provide an html link somewhere to the script that downloads
michael@0: the root.cacert file. You'll probably want to put that next to the link
michael@0: that loads the index.html page. On interzone, this is done with the
michael@0: following html:
michael@0:
michael@0: Cert-O-Matic II Root CA server
michael@0:
michael@0: Download and trust Root CA
michael@0: certificate
michael@0:
michael@0: The index.html file in this directory invokes the certcgi.cgi script with
michael@0: the form post method, so if you change the name of the certcgi.cgi script,
michael@0: you'll also have to change the index.html file in $DOCROOT/certomatic
michael@0:
michael@0: The 4 files used by the certcgi program (the 3 NSS DBs, and the serial
michael@0: number file) are not required to live in $CGIBIN/certomatic, but they are
michael@0: required to live in $CWD/.. when certcgi starts.
michael@0:
michael@0: Known bugs:
michael@0:
michael@0: 1. Because multiple of these CAs exist simultaneously, it would be best if
michael@0: they didn't all have to be called "Cert-O-Matic II", but that string is
michael@0: presently hard coded into certcgi.c.
michael@0:
michael@0: 2. the html files in this directory contain numerous extraneous