security/nss/cmd/certcgi/HOWTO.txt@141e0f1194b1 (annotated)
security/nss/cmd/certcgi/HOWTO.txt
Wed, 31 Dec 2014 07:16:47 +0100
- author
- Michael Schloh von Bennewitz <michael@schloh.com>
- date
- Wed, 31 Dec 2014 07:16:47 +0100
- branch
- TOR_BUG_9701
- changeset 3
- 141e0f1194b1
- permissions
- -rw-r--r--
Revert simplistic fix pending revisit of Mozilla integration attempt.
| michael@0 | 1 | How to setup your very own Cert-O-Matic Root CA server |
| michael@0 | 2 | |
| michael@0 | 3 | This Source Code Form is subject to the terms of the Mozilla Public |
| michael@0 | 4 | # License, v. 2.0. If a copy of the MPL was not distributed with this |
| michael@0 | 5 | # file, You can obtain one at http://mozilla.org/MPL/2.0/. |
| michael@0 | 6 | |
| michael@0 | 7 | How to setup your very own Cert-O-Matic Root CA server |
| michael@0 | 8 | |
| michael@0 | 9 | The program certcgi is part of a small test CA that is used inside |
| michael@0 | 10 | Netscape by the NSS development team. That CA is affectionately known |
| michael@0 | 11 | as "Cert-O-Matic" or "Cert-O-Matic II". It presently runs on a server |
| michael@0 | 12 | named interzone.mcom.com inside Netscape's firewall. |
| michael@0 | 13 | |
| michael@0 | 14 | If you wish to setup your own Cert-O-Matic, here are directions. |
| michael@0 | 15 | |
| michael@0 | 16 | Disclaimer: This program does not follow good practices for root CAs. |
| michael@0 | 17 | It should be used only for playing/testing and never for production use. |
| michael@0 | 18 | Remember, you've been warned! |
| michael@0 | 19 | |
| michael@0 | 20 | Cert-O-Matic consists of some html files, shell scripts, one executable |
| michael@0 | 21 | program that uses NSS and NSPR, the usual set of NSS .db files, and a file |
| michael@0 | 22 | in which to remember the serial number of the last cert issued. The |
| michael@0 | 23 | html files and the source to the executable program are in this directory. |
| michael@0 | 24 | Sample shell scripts are shown below. |
| michael@0 | 25 | |
| michael@0 | 26 | The shell scripts and executable program run as CGI "scripts". The |
| michael@0 | 27 | entire thing runs on an ordinary http web server. It would also run on |
| michael@0 | 28 | an https web server. The shell scripts and html files must be |
| michael@0 | 29 | customized for the server on which they run. |
| michael@0 | 30 | |
| michael@0 | 31 | The package assumes you have a "document root" directory $DOCROOT, and a |
| michael@0 | 32 | "cgi-bin" directory $CGIBIN. In this example, the document root is |
| michael@0 | 33 | assumed to be located in /var/www/htdocs, and the cgi-bin directory in |
| michael@0 | 34 | /var/www/cgi-bin. |
| michael@0 | 35 | |
| michael@0 | 36 | The server is assumed to run all cgi scripts as the user "nobody". |
| michael@0 | 37 | The names of the cgi scripts run directly by the server all end in .cgi |
| michael@0 | 38 | because some servers like it that way. |
| michael@0 | 39 | |
| michael@0 | 40 | Instructions: |
| michael@0 | 41 | |
| michael@0 | 42 | - Create directory $DOCROOT/certomatic |
| michael@0 | 43 | - Copy the following files from nss/cmd/certcgi to $DOCROOT/certomatic |
| michael@0 | 44 | ca.html index.html main.html nscp_ext_form.html stnd_ext_form.html |
| michael@0 | 45 | - Edit the html files, substituting the name of your own server for the |
| michael@0 | 46 | server named in those files. |
| michael@0 | 47 | - In some web page (e.g. your server's home page), provide an html link to |
| michael@0 | 48 | $DOCROOT/certomatic/index.html. This is where users start to get their |
| michael@0 | 49 | own certs from certomatic. |
| michael@0 | 50 | - give these files and directories appropriate permissions. |
| michael@0 | 51 | |
| michael@0 | 52 | - Create directories $CGIBIN/certomatic and $CGIBIN/certomatic/bin |
| michael@0 | 53 | make sure that $CGIBIN/certomatic is writable by "nobody" |
| michael@0 | 54 | |
| michael@0 | 55 | - Create a new set of NSS db files there with the following command: |
| michael@0 | 56 | |
| michael@0 | 57 | certutil -N -d $CGIBIN/certomatic |
| michael@0 | 58 | |
| michael@0 | 59 | - when certutil prompts you for the password, enter the word foo |
| michael@0 | 60 | because that is compiled into the certcgi program. |
| michael@0 | 61 | |
| michael@0 | 62 | - Create the new Root CA cert with this command |
| michael@0 | 63 | |
| michael@0 | 64 | certutil -S -x -d $CGIBIN/certomatic -n "Cert-O-Matic II" \ |
| michael@0 | 65 | -s "CN=Cert-O-Matic II, O=Cert-O-Matic II" -t TCu,cu,cu -k rsa \ |
| michael@0 | 66 | -g 1024 -m 10001 -v 60 |
| michael@0 | 67 | |
| michael@0 | 68 | (adjust the -g, -m and -v parameters to taste. -s and -x must be as |
| michael@0 | 69 | shown.) |
| michael@0 | 70 | |
| michael@0 | 71 | - dump out the new root CA cert in base64 encoding: |
| michael@0 | 72 | |
| michael@0 | 73 | certutil -d $CGIBIN/certomatic -L -n "Cert-O-Matic II" -a > \ |
| michael@0 | 74 | $CGIBIN/certomatic/root.cacert |
| michael@0 | 75 | |
| michael@0 | 76 | - In $CGIBIN/certomatic/bin add two shell scripts - one to download the |
| michael@0 | 77 | root CA cert on demand, and one to run the certcgi program. |
| michael@0 | 78 | |
| michael@0 | 79 | download.cgi, the script to install the root CA cert into a browser on |
| michael@0 | 80 | demand, is this: |
| michael@0 | 81 | |
| michael@0 | 82 | #!/bin/sh |
| michael@0 | 83 | echo "Content-type: application/x-x509-ca-cert" |
| michael@0 | 84 | echo |
| michael@0 | 85 | cat $CGIBIN/certomatic/root.cacert |
| michael@0 | 86 | |
| michael@0 | 87 | You'll have to put the real path into that cat command because CGIBIN |
| michael@0 | 88 | won't be defined when this script is run by the server. |
| michael@0 | 89 | |
| michael@0 | 90 | certcgi.cgi, the script to run the certcgi program is similar to this: |
| michael@0 | 91 | |
| michael@0 | 92 | #!/bin/sh |
| michael@0 | 93 | cd $CGIBIN/certomatic/bin |
| michael@0 | 94 | LD_LIBRARY_PATH=$PLATFORM/lib |
| michael@0 | 95 | export LD_LIBRARY_PATH |
| michael@0 | 96 | $PLATFORM/bin/certcgi $* 2>&1 |
| michael@0 | 97 | |
| michael@0 | 98 | Where $PLATFORM/lib is where the NSPR nad NSS DSOs are located, and |
| michael@0 | 99 | $PLATFORM/bin is where certcgi is located. PLATFORM is not defined when |
| michael@0 | 100 | the server runs this script, so you'll have to substitute the right value |
| michael@0 | 101 | in your script. certcgi requires that the working directory be one level |
| michael@0 | 102 | below the NSS DBs, that is, the DBs are accessed in the directory "..". |
| michael@0 | 103 | |
| michael@0 | 104 | You'll want to provide an html link somewhere to the script that downloads |
| michael@0 | 105 | the root.cacert file. You'll probably want to put that next to the link |
| michael@0 | 106 | that loads the index.html page. On interzone, this is done with the |
| michael@0 | 107 | following html: |
| michael@0 | 108 | |
| michael@0 | 109 | <a href="/certomatic/index.html">Cert-O-Matic II Root CA server</a> |
| michael@0 | 110 | <p> |
| michael@0 | 111 | <a href="/cgi-bin/certomatic/bin/download.cgi">Download and trust Root CA |
| michael@0 | 112 | certificate</a> |
| michael@0 | 113 | |
| michael@0 | 114 | The index.html file in this directory invokes the certcgi.cgi script with |
| michael@0 | 115 | the form post method, so if you change the name of the certcgi.cgi script, |
| michael@0 | 116 | you'll also have to change the index.html file in $DOCROOT/certomatic |
| michael@0 | 117 | |
| michael@0 | 118 | The 4 files used by the certcgi program (the 3 NSS DBs, and the serial |
| michael@0 | 119 | number file) are not required to live in $CGIBIN/certomatic, but they are |
| michael@0 | 120 | required to live in $CWD/.. when certcgi starts. |
| michael@0 | 121 | |
| michael@0 | 122 | Known bugs: |
| michael@0 | 123 | |
| michael@0 | 124 | 1. Because multiple of these CAs exist simultaneously, it would be best if |
| michael@0 | 125 | they didn't all have to be called "Cert-O-Matic II", but that string is |
| michael@0 | 126 | presently hard coded into certcgi.c. |
| michael@0 | 127 | |
| michael@0 | 128 | 2. the html files in this directory contain numerous extraneous <FORM> tags |
| michael@0 | 129 | which appear to use the post method and have action URLS that are never |
| michael@0 | 130 | actually used. burp.cgi and echoform.cgi are never actually used. This |
| michael@0 | 131 | should be cleaned up. |
| michael@0 | 132 | |
| michael@0 | 133 | 3. The html files use <layer> tags which are supported only in Netscape |
| michael@0 | 134 | Navigator and Netscape Communication 4.x browsers. The html files do |
| michael@0 | 135 | not work as intended with Netscape 6.x, Mozilla or Microsoft IE browsers. |
| michael@0 | 136 | The html files should be fixed to work with all those named browsers. |
| michael@0 | 137 |
