1.1 --- /dev/null Thu Jan 01 00:00:00 1970 +0000
1.2 +++ b/security/nss/cmd/certcgi/HOWTO.txt Wed Dec 31 06:09:35 2014 +0100
1.3 @@ -0,0 +1,137 @@
1.4 + How to setup your very own Cert-O-Matic Root CA server
1.5 +
1.6 + This Source Code Form is subject to the terms of the Mozilla Public
1.7 + # License, v. 2.0. If a copy of the MPL was not distributed with this
1.8 + # file, You can obtain one at http://mozilla.org/MPL/2.0/.
1.9 +
1.10 + How to setup your very own Cert-O-Matic Root CA server
1.11 +
1.12 +The program certcgi is part of a small test CA that is used inside
1.13 +Netscape by the NSS development team. That CA is affectionately known
1.14 +as "Cert-O-Matic" or "Cert-O-Matic II". It presently runs on a server
1.15 +named interzone.mcom.com inside Netscape's firewall.
1.16 +
1.17 +If you wish to setup your own Cert-O-Matic, here are directions.
1.18 +
1.19 +Disclaimer: This program does not follow good practices for root CAs.
1.20 +It should be used only for playing/testing and never for production use.
1.21 +Remember, you've been warned!
1.22 +
1.23 +Cert-O-Matic consists of some html files, shell scripts, one executable
1.24 +program that uses NSS and NSPR, the usual set of NSS .db files, and a file
1.25 +in which to remember the serial number of the last cert issued. The
1.26 +html files and the source to the executable program are in this directory.
1.27 +Sample shell scripts are shown below.
1.28 +
1.29 +The shell scripts and executable program run as CGI "scripts". The
1.30 +entire thing runs on an ordinary http web server. It would also run on
1.31 +an https web server. The shell scripts and html files must be
1.32 +customized for the server on which they run.
1.33 +
1.34 +The package assumes you have a "document root" directory $DOCROOT, and a
1.35 +"cgi-bin" directory $CGIBIN. In this example, the document root is
1.36 +assumed to be located in /var/www/htdocs, and the cgi-bin directory in
1.37 +/var/www/cgi-bin.
1.38 +
1.39 +The server is assumed to run all cgi scripts as the user "nobody".
1.40 +The names of the cgi scripts run directly by the server all end in .cgi
1.41 +because some servers like it that way.
1.42 +
1.43 +Instructions:
1.44 +
1.45 +- Create directory $DOCROOT/certomatic
1.46 +- Copy the following files from nss/cmd/certcgi to $DOCROOT/certomatic
1.47 + ca.html index.html main.html nscp_ext_form.html stnd_ext_form.html
1.48 +- Edit the html files, substituting the name of your own server for the
1.49 + server named in those files.
1.50 +- In some web page (e.g. your server's home page), provide an html link to
1.51 + $DOCROOT/certomatic/index.html. This is where users start to get their
1.52 + own certs from certomatic.
1.53 +- give these files and directories appropriate permissions.
1.54 +
1.55 +- Create directories $CGIBIN/certomatic and $CGIBIN/certomatic/bin
1.56 + make sure that $CGIBIN/certomatic is writable by "nobody"
1.57 +
1.58 +- Create a new set of NSS db files there with the following command:
1.59 +
1.60 + certutil -N -d $CGIBIN/certomatic
1.61 +
1.62 +- when certutil prompts you for the password, enter the word foo
1.63 + because that is compiled into the certcgi program.
1.64 +
1.65 +- Create the new Root CA cert with this command
1.66 +
1.67 + certutil -S -x -d $CGIBIN/certomatic -n "Cert-O-Matic II" \
1.68 + -s "CN=Cert-O-Matic II, O=Cert-O-Matic II" -t TCu,cu,cu -k rsa \
1.69 + -g 1024 -m 10001 -v 60
1.70 +
1.71 + (adjust the -g, -m and -v parameters to taste. -s and -x must be as
1.72 +shown.)
1.73 +
1.74 +- dump out the new root CA cert in base64 encoding:
1.75 +
1.76 + certutil -d $CGIBIN/certomatic -L -n "Cert-O-Matic II" -a > \
1.77 + $CGIBIN/certomatic/root.cacert
1.78 +
1.79 +- In $CGIBIN/certomatic/bin add two shell scripts - one to download the
1.80 + root CA cert on demand, and one to run the certcgi program.
1.81 +
1.82 +download.cgi, the script to install the root CA cert into a browser on
1.83 +demand, is this:
1.84 +
1.85 +#!/bin/sh
1.86 +echo "Content-type: application/x-x509-ca-cert"
1.87 +echo
1.88 +cat $CGIBIN/certomatic/root.cacert
1.89 +
1.90 +You'll have to put the real path into that cat command because CGIBIN
1.91 +won't be defined when this script is run by the server.
1.92 +
1.93 +certcgi.cgi, the script to run the certcgi program is similar to this:
1.94 +
1.95 +#!/bin/sh
1.96 +cd $CGIBIN/certomatic/bin
1.97 +LD_LIBRARY_PATH=$PLATFORM/lib
1.98 +export LD_LIBRARY_PATH
1.99 +$PLATFORM/bin/certcgi $* 2>&1
1.100 +
1.101 +Where $PLATFORM/lib is where the NSPR nad NSS DSOs are located, and
1.102 +$PLATFORM/bin is where certcgi is located. PLATFORM is not defined when
1.103 +the server runs this script, so you'll have to substitute the right value
1.104 +in your script. certcgi requires that the working directory be one level
1.105 +below the NSS DBs, that is, the DBs are accessed in the directory "..".
1.106 +
1.107 +You'll want to provide an html link somewhere to the script that downloads
1.108 +the root.cacert file. You'll probably want to put that next to the link
1.109 +that loads the index.html page. On interzone, this is done with the
1.110 +following html:
1.111 +
1.112 +<a href="/certomatic/index.html">Cert-O-Matic II Root CA server</a>
1.113 +<p>
1.114 +<a href="/cgi-bin/certomatic/bin/download.cgi">Download and trust Root CA
1.115 +certificate</a>
1.116 +
1.117 +The index.html file in this directory invokes the certcgi.cgi script with
1.118 +the form post method, so if you change the name of the certcgi.cgi script,
1.119 +you'll also have to change the index.html file in $DOCROOT/certomatic
1.120 +
1.121 +The 4 files used by the certcgi program (the 3 NSS DBs, and the serial
1.122 +number file) are not required to live in $CGIBIN/certomatic, but they are
1.123 +required to live in $CWD/.. when certcgi starts.
1.124 +
1.125 +Known bugs:
1.126 +
1.127 +1. Because multiple of these CAs exist simultaneously, it would be best if
1.128 +they didn't all have to be called "Cert-O-Matic II", but that string is
1.129 +presently hard coded into certcgi.c.
1.130 +
1.131 +2. the html files in this directory contain numerous extraneous <FORM> tags
1.132 +which appear to use the post method and have action URLS that are never
1.133 +actually used. burp.cgi and echoform.cgi are never actually used. This
1.134 +should be cleaned up.
1.135 +
1.136 +3. The html files use <layer> tags which are supported only in Netscape
1.137 +Navigator and Netscape Communication 4.x browsers. The html files do
1.138 +not work as intended with Netscape 6.x, Mozilla or Microsoft IE browsers.
1.139 +The html files should be fixed to work with all those named browsers.
1.140 +
