doc/ns-ca.doc

   1 The following documentation was supplied by Jeff Barber, who provided the
   2 patch to the CA program to add this functionality.
   3
   4 eric
   5 --
   6 Jeff Barber                                Email: jeffb@issl.atl.hp.com
   7
   8 Hewlett Packard                            Phone: (404) 648-9503
   9 Internet and System Security Lab           Fax:   (404) 648-9516
  10
  11                          oo
  12 ---------------------cut /\ here for ns-ca.doc ------------------------------
  13
  14 This document briefly describes how to use SSLeay to implement a
  15 certificate authority capable of dynamically serving up client
  16 certificates for version 3.0 beta 5 (and presumably later) versions of
  17 the Netscape Navigator.  Before describing how this is done, it's
  18 important to understand a little about how the browser implements its
  19 client certificate support.  This is documented in some detail in the
  20 URLs based at <URL:http://home.netscape.com/eng/security/certs.html>.
  21 Here's a brief overview:
  22
  23 -       The Navigator supports a new HTML tag "KEYGEN" which will cause
  24         the browser to generate an RSA key pair when you submit a form
  25         containing the tag.  The public key, along with an optional
  26         challenge (supposedly provided for use in certificate revocation
  27         but I don't use it) is signed, DER-encoded, base-64 encoded
  28         and sent to the web server as the value of the variable
  29         whose NAME is provided in the KEYGEN tag.  The private key is
  30         stored by the browser in a local key database.
  31
  32         This "Signed Public Key And Challenge" (SPKAC) arrives formatted
  33         into 64 character lines (which are of course URL-encoded when
  34         sent via HTTP -- i.e. spaces, newlines and most punctuatation are
  35         encoded as "%HH" where HH is the hex equivalent of the ASCII code).
  36         Note that the SPKAC does not contain the other usual attributes
  37         of a certificate request, especially the subject name fields.
  38         These must be otherwise encoded in the form for submission along
  39         with the SPKAC.
  40
  41 -       Either immediately (in response to this form submission), or at
  42         some later date (a real CA will probably verify your identity in
  43         some way before issuing the certificate), a web server can send a
  44         certificate based on the public key and other attributes back to
  45         the browser by encoding it in DER (the binary form) and sending it
  46         to the browser as MIME type:
  47         "Content-type: application/x-x509-user-cert"
  48
  49         The browser uses the public key encoded in the certificate to
  50         associate the certificate with the appropriate private key in
  51         its local key database.  Now, the certificate is "installed".
  52
  53 -       When a server wants to require authentication based on client
  54         certificates, it uses the right signals via the SSL protocol to
  55         trigger the Navigator to ask you which certificate you want to
  56         send.  Whether the certificate is accepted is dependent on CA
  57         certificates and so forth installed in the server and is beyond
  58         the scope of this document.
  59
  60
  61 Now, here's how the SSLeay package can be used to provide client
  62 certficates:
  63
  64 -       You prepare a file for input to the SSLeay ca application.
  65         The file contains a number of "name = value" pairs that identify
  66         the subject.  The names here are the same subject name component
  67         identifiers used in the CA section of the lib/ssleay.conf file,
  68         such as "emailAddress", "commonName" "organizationName" and so
  69         forth.  Both the long version and the short version (e.g. "Email",
  70         "CN", "O") can be used.
  71
  72         One more name is supported: this one is "SPKAC".  Its value
  73         is simply the value of the base-64 encoded SPKAC sent by the
  74         browser (with all the newlines and other space charaters
  75         removed -- and newline escapes are NOT supported).
  76
  77         [ As of SSLeay 0.6.4, multiple lines are supported.
  78           Put a \ at the end of each line and it will be joined with the
  79           previous line with the '\n' removed - eay ]
  80
  81         Here's a sample input file:
  82
  83 C = US
  84 SP = Georgia
  85 O = Some Organization, Inc.
  86 OU = Netscape Compatibility Group
  87 CN = John X. Doe
  88 Email = jxdoe@someorg.com
  89 SPKAC = MIG0MGAwXDANBgkqhkiG9w0BAQEFAANLADBIAkEAwmk6FMJ4uAVIYbcvIOx5+bDGTfvL8X5gE+R67ccMk6rCSGbVQz2cetyQtnI+VIs0NwdD6wjuSuVtVFbLoHonowIDAQABFgAwDQYJKoZIhvcNAQEEBQADQQBFZDUWFl6BJdomtN1Bi53mwijy1rRgJ4YirF15yBEDM3DjAQkKXHYOIX+qpz4KXKnl6EYxTnGSFL5wWt8X2iyx
  90
  91 -       You execute the ca command (either from a CGI program run out of
  92         the web server, or as a later manual task) giving it the above
  93         file as input.  For example, if the file were named /tmp/cert.req,
  94         you'd run:
  95         $SSLDIR/bin/ca -spkac /tmp/cert.req -out /tmp/cert
  96
  97         The output is in DER format (binary) if a -out argument is
  98         provided, as above; otherwise, it's in the PEM format (base-64
  99         encoded DER).  Also, the "-batch" switch is implied by the
 100         "-spkac" so you don't get asked whether to complete the signing
 101         (probably it shouldn't work this way but I was only interested
 102         in hacking together an online CA that could be used for issuing
 103         test certificates).
 104
 105         The "-spkac" capability doesn't support multiple files (I think).
 106
 107         Any CHALLENGE provided in the SPKAC is simply ignored.
 108
 109         The interactions between the identification fields you provide
 110         and those identified in your lib/ssleay.conf are the same as if
 111         you did an ordinary "ca -in infile -out outfile" -- that is, if
 112         something is marked as required in the ssleay.conf file and it
 113         isn't found in the -spkac file, the certificate won't be issued.
 114
 115 -       Now, you pick up the output from /tmp/cert and pass it back to
 116         the Navigator prepending the Content-type string described earlier.
 117
 118 -       In order to run the ca command out of a CGI program, you must
 119         provide a password to decrypt the CA's private key.  You can
 120         do this by using "echo MyKeyPassword | $SSLDIR/bin/ca ..."
 121         I think there's a way to not encrypt the key file in the first
 122         place, but I didn't see how to do that, so I made a small change
 123         to the library that allows the password to be accepted from a pipe.
 124         Either way is UTTERLY INSECURE and a real CA would never do that.
 125
 126         [ You can use the 'ssleay rsa' command to remove the password
 127           from the private key, or you can use the '-key' option to the
 128           ca command to specify the decryption key on the command line
 129           or use the -nodes option when generating the key.
 130           ca will try to clear the command line version of the password
 131           but for quite a few operating systems, this is not possible.
 132           - eric ]
 133
 134 So, what do you have to do to make use of this stuff to create an online
 135 demo CA capability with SSLeay?
 136
 137 1       Create an HTML form for your users.  The form should contain
 138         fields for all of the required or optional fields in ssleay.conf.
 139         The form must contain a KEYGEN tag somewhere with at least a NAME
 140         attribute.
 141
 142 2       Create a CGI program to process the form input submitted by the
 143         browser.  The CGI program must URL-decode the variables and create
 144         the file described above, containing subject identification info
 145         as well as the SPKAC block.  It should then run the the ca program
 146         with the -spkac option.  If it works (check the exit status),
 147         return the new certificate with the appropriate MIME type.  If not,
 148         return the output of the ca command with MIME type "text/plain".
 149
 150 3       Set up your web server to accept connections signed by your demo
 151         CA.  This probably involves obtaining the PEM-encoded CA certificate
 152         (ordinarily in $SSLDIR/CA/cacert.pem) and installing it into a
 153         server database.  See your server manual for instructions.
 154