security/nss/cmd/certcgi/HOWTO.txt

   1         How to setup your very own Cert-O-Matic Root CA server
   2
   3 ***** BEGIN LICENSE BLOCK *****
   4 Version: MPL 1.1/GPL 2.0/LGPL 2.1
   5
   6 The contents of this file are subject to the Mozilla Public License Version
   7 1.1 (the "License"); you may not use this file except in compliance with
   8 the License. You may obtain a copy of the License at
   9 http://www.mozilla.org/MPL/
  10
  11 Software distributed under the License is distributed on an "AS IS" basis,
  12 WITHOUT WARRANTY OF ANY KIND, either express or implied. See the License
  13 for the specific language governing rights and limitations under the
  14 License.
  15
  16 The Original Code is Netscape security libraries.
  17
  18 The Initial Developer of the Original Code is Netscape Communications
  19 Corporation.  Portions created by the Initial Developer are
  20 Copyright (C) 2001 the Initial Developer. All Rights Reserved.
  21
  22 Contributor(s):
  23
  24 Alternatively, the contents of this file may be used under the terms of
  25 either the GNU General Public License Version 2 or later (the "GPL"), or
  26 the GNU Lesser General Public License Version 2.1 or later (the "LGPL"),
  27 in which case the provisions of the GPL or the LGPL are applicable instead
  28 of those above. If you wish to allow use of your version of this file only
  29 under the terms of either the GPL or the LGPL, and not to allow others to
  30 use your version of this file under the terms of the MPL, indicate your
  31 decision by deleting the provisions above and replace them with the notice
  32 and other provisions required by the GPL or the LGPL. If you do not delete
  33 the provisions above, a recipient may use your version of this file under
  34 the terms of any one of the MPL, the GPL or the LGPL.
  35
  36 ***** END LICENSE BLOCK *****
  37
  38         How to setup your very own Cert-O-Matic Root CA server
  39
  40 The program certcgi is part of a small test CA that is used inside
  41 Netscape by the NSS development team.  That CA is affectionately known
  42 as "Cert-O-Matic" or "Cert-O-Matic II".  It presently runs on a server
  43 named interzone.mcom.com inside Netscape's firewall.
  44
  45 If you wish to setup your own Cert-O-Matic, here are directions.
  46
  47 Disclaimer:  This program does not follow good practices for root CAs.
  48 It should be used only for playing/testing and never for production use.
  49 Remember, you've been warned!
  50
  51 Cert-O-Matic consists of some html files, shell scripts, one executable
  52 program that uses NSS and NSPR, the usual set of NSS .db files, and a file
  53 in which to remember the serial number of the last cert issued.  The
  54 html files and the source to the executable program are in this directory.
  55 Sample shell scripts are shown below.
  56
  57 The shell scripts and executable program run as CGI "scripts".  The
  58 entire thing runs on an ordinary http web server.  It would also run on
  59 an https web server.  The shell scripts and html files must be
  60 customized for the server on which they run.
  61
  62 The package assumes you have a "document root" directory $DOCROOT, and a
  63 "cgi-bin" directory $CGIBIN.  In this example, the document root is
  64 assumed to be located in /var/www/htdocs, and the cgi-bin directory in
  65 /var/www/cgi-bin.
  66
  67 The server is assumed to run all cgi scripts as the user "nobody".
  68 The names of the cgi scripts run directly by the server all end in .cgi
  69 because some servers like it that way.
  70
  71 Instructions:
  72
  73 - Create directory $DOCROOT/certomatic
  74 - Copy the following files from nss/cmd/certcgi to $DOCROOT/certomatic
  75         ca.html index.html main.html nscp_ext_form.html stnd_ext_form.html
  76 - Edit the html files, substituting the name of your own server for the
  77   server named in those files.
  78 - In some web page (e.g. your server's home page), provide an html link to
  79   $DOCROOT/certomatic/index.html. This is where users start to get their
  80   own certs from certomatic.
  81 - give these files and directories appropriate permissions.
  82
  83 - Create directories $CGIBIN/certomatic and $CGIBIN/certomatic/bin
  84   make sure that $CGIBIN/certomatic is writable by "nobody"
  85
  86 - Create a new set of NSS db files there with the following command:
  87
  88         certutil -N -d $CGIBIN/certomatic
  89
  90 - when certutil prompts you for the password, enter the word foo
  91   because that is compiled into the certcgi program.
  92
  93 - Create the new Root CA cert with this command
  94
  95         certutil -S -x -d $CGIBIN/certomatic -n "Cert-O-Matic II" \
  96         -s "CN=Cert-O-Matic II, O=Cert-O-Matic II" -t TCu,cu,cu -k rsa \
  97         -g 1024 -m 10001 -v 60
  98
  99   (adjust the -g, -m and -v parameters to taste.  -s and -x must be as
 100 shown.)
 101
 102 - dump out the new root CA cert in base64 encoding:
 103
 104         certutil -d $CGIBIN/certomatic -L -n "Cert-O-Matic II" -a > \
 105           $CGIBIN/certomatic/root.cacert
 106
 107 - In $CGIBIN/certomatic/bin add two shell scripts - one to download the
 108   root CA cert on demand, and one to run the certcgi program.
 109
 110 download.cgi, the script to install the root CA cert into a browser on
 111 demand, is this:
 112
 113 #!/bin/sh
 114 echo "Content-type: application/x-x509-ca-cert"
 115 echo
 116 cat $CGIBIN/certomatic/root.cacert
 117
 118 You'll have to put the real path into that cat command because CGIBIN
 119 won't be defined when this script is run by the server.
 120
 121 certcgi.cgi, the script to run the certcgi program is similar to this:
 122
 123 #!/bin/sh
 124 cd $CGIBIN/certomatic/bin
 125 LD_LIBRARY_PATH=$PLATFORM/lib
 126 export LD_LIBRARY_PATH
 127 $PLATFORM/bin/certcgi $* 2>&1
 128
 129 Where $PLATFORM/lib is where the NSPR nad NSS DSOs are located, and
 130 $PLATFORM/bin is where certcgi is located.  PLATFORM is not defined when
 131 the server runs this script, so you'll have to substitute the right value
 132 in your script.  certcgi requires that the working directory be one level
 133 below the NSS DBs, that is, the DBs are accessed in the directory "..".
 134
 135 You'll want to provide an html link somewhere to the script that downloads
 136 the root.cacert file.  You'll probably want to put that next to the link
 137 that loads the index.html page.  On interzone, this is done with the
 138 following html:
 139
 140 <a href="/certomatic/index.html">Cert-O-Matic II Root CA server</a>
 141 <p>
 142 <a href="/cgi-bin/certomatic/bin/download.cgi">Download and trust Root CA
 143 certificate</a>
 144
 145 The index.html file in this directory invokes the certcgi.cgi script with
 146 the form post method, so if you change the name of the certcgi.cgi script,
 147 you'll also have to change the index.html file in $DOCROOT/certomatic
 148
 149 The 4 files used by the certcgi program (the 3 NSS DBs, and the serial
 150 number file) are not required to live in $CGIBIN/certomatic, but they are
 151 required to live in $CWD/.. when certcgi starts.
 152
 153 Known bugs:
 154
 155 1. Because multiple of these CAs exist simultaneously, it would be best if
 156 they didn't all have to be called "Cert-O-Matic II", but that string is
 157 presently hard coded into certcgi.c.
 158
 159 2. the html files in this directory contain numerous extraneous <FORM> tags
 160 which appear to use the post method and have action URLS that are never
 161 actually used.  burp.cgi and echoform.cgi are never actually used.  This
 162 should be cleaned up.
 163
 164 3. The html files use <layer> tags which are supported only in Netscape
 165 Navigator and Netscape Communication 4.x browsers.  The html files do
 166 not work as intended with Netscape 6.x, Mozilla or Microsoft IE browsers.
 167 The html files should be fixed to work with all those named browsers.
 168