diff options
Diffstat (limited to 'doc/ns-ca.doc')
| -rw-r--r-- | doc/ns-ca.doc | 154 |
1 files changed, 0 insertions, 154 deletions
diff --git a/doc/ns-ca.doc b/doc/ns-ca.doc deleted file mode 100644 index 836883e1a0..0000000000 --- a/doc/ns-ca.doc +++ /dev/null @@ -1,154 +0,0 @@ -The following documentation was supplied by Jeff Barber, who provided the -patch to the CA program to add this functionality. - -eric --- -Jeff Barber Email: jeffb@issl.atl.hp.com - -Hewlett Packard Phone: (404) 648-9503 -Internet and System Security Lab Fax: (404) 648-9516 - - oo ----------------------cut /\ here for ns-ca.doc ------------------------------ - -This document briefly describes how to use SSLeay to implement a -certificate authority capable of dynamically serving up client -certificates for version 3.0 beta 5 (and presumably later) versions of -the Netscape Navigator. Before describing how this is done, it's -important to understand a little about how the browser implements its -client certificate support. This is documented in some detail in the -URLs based at <URL:http://home.netscape.com/eng/security/certs.html>. -Here's a brief overview: - -- The Navigator supports a new HTML tag "KEYGEN" which will cause - the browser to generate an RSA key pair when you submit a form - containing the tag. The public key, along with an optional - challenge (supposedly provided for use in certificate revocation - but I don't use it) is signed, DER-encoded, base-64 encoded - and sent to the web server as the value of the variable - whose NAME is provided in the KEYGEN tag. The private key is - stored by the browser in a local key database. - - This "Signed Public Key And Challenge" (SPKAC) arrives formatted - into 64 character lines (which are of course URL-encoded when - sent via HTTP -- i.e. spaces, newlines and most punctuatation are - encoded as "%HH" where HH is the hex equivalent of the ASCII code). - Note that the SPKAC does not contain the other usual attributes - of a certificate request, especially the subject name fields. - These must be otherwise encoded in the form for submission along - with the SPKAC. - -- Either immediately (in response to this form submission), or at - some later date (a real CA will probably verify your identity in - some way before issuing the certificate), a web server can send a - certificate based on the public key and other attributes back to - the browser by encoding it in DER (the binary form) and sending it - to the browser as MIME type: - "Content-type: application/x-x509-user-cert" - - The browser uses the public key encoded in the certificate to - associate the certificate with the appropriate private key in - its local key database. Now, the certificate is "installed". - -- When a server wants to require authentication based on client - certificates, it uses the right signals via the SSL protocol to - trigger the Navigator to ask you which certificate you want to - send. Whether the certificate is accepted is dependent on CA - certificates and so forth installed in the server and is beyond - the scope of this document. - - -Now, here's how the SSLeay package can be used to provide client -certficates: - -- You prepare a file for input to the SSLeay ca application. - The file contains a number of "name = value" pairs that identify - the subject. The names here are the same subject name component - identifiers used in the CA section of the lib/ssleay.conf file, - such as "emailAddress", "commonName" "organizationName" and so - forth. Both the long version and the short version (e.g. "Email", - "CN", "O") can be used. - - One more name is supported: this one is "SPKAC". Its value - is simply the value of the base-64 encoded SPKAC sent by the - browser (with all the newlines and other space charaters - removed -- and newline escapes are NOT supported). - - [ As of SSLeay 0.6.4, multiple lines are supported. - Put a \ at the end of each line and it will be joined with the - previous line with the '\n' removed - eay ] - - Here's a sample input file: - -C = US -SP = Georgia -O = Some Organization, Inc. -OU = Netscape Compatibility Group -CN = John X. Doe -Email = jxdoe@someorg.com -SPKAC = MIG0MGAwXDANBgkqhkiG9w0BAQEFAANLADBIAkEAwmk6FMJ4uAVIYbcvIOx5+bDGTfvL8X5gE+R67ccMk6rCSGbVQz2cetyQtnI+VIs0NwdD6wjuSuVtVFbLoHonowIDAQABFgAwDQYJKoZIhvcNAQEEBQADQQBFZDUWFl6BJdomtN1Bi53mwijy1rRgJ4YirF15yBEDM3DjAQkKXHYOIX+qpz4KXKnl6EYxTnGSFL5wWt8X2iyx - -- You execute the ca command (either from a CGI program run out of - the web server, or as a later manual task) giving it the above - file as input. For example, if the file were named /tmp/cert.req, - you'd run: - $SSLDIR/bin/ca -spkac /tmp/cert.req -out /tmp/cert - - The output is in DER format (binary) if a -out argument is - provided, as above; otherwise, it's in the PEM format (base-64 - encoded DER). Also, the "-batch" switch is implied by the - "-spkac" so you don't get asked whether to complete the signing - (probably it shouldn't work this way but I was only interested - in hacking together an online CA that could be used for issuing - test certificates). - - The "-spkac" capability doesn't support multiple files (I think). - - Any CHALLENGE provided in the SPKAC is simply ignored. - - The interactions between the identification fields you provide - and those identified in your lib/ssleay.conf are the same as if - you did an ordinary "ca -in infile -out outfile" -- that is, if - something is marked as required in the ssleay.conf file and it - isn't found in the -spkac file, the certificate won't be issued. - -- Now, you pick up the output from /tmp/cert and pass it back to - the Navigator prepending the Content-type string described earlier. - -- In order to run the ca command out of a CGI program, you must - provide a password to decrypt the CA's private key. You can - do this by using "echo MyKeyPassword | $SSLDIR/bin/ca ..." - I think there's a way to not encrypt the key file in the first - place, but I didn't see how to do that, so I made a small change - to the library that allows the password to be accepted from a pipe. - Either way is UTTERLY INSECURE and a real CA would never do that. - - [ You can use the 'ssleay rsa' command to remove the password - from the private key, or you can use the '-key' option to the - ca command to specify the decryption key on the command line - or use the -nodes option when generating the key. - ca will try to clear the command line version of the password - but for quite a few operating systems, this is not possible. - - eric ] - -So, what do you have to do to make use of this stuff to create an online -demo CA capability with SSLeay? - -1 Create an HTML form for your users. The form should contain - fields for all of the required or optional fields in ssleay.conf. - The form must contain a KEYGEN tag somewhere with at least a NAME - attribute. - -2 Create a CGI program to process the form input submitted by the - browser. The CGI program must URL-decode the variables and create - the file described above, containing subject identification info - as well as the SPKAC block. It should then run the the ca program - with the -spkac option. If it works (check the exit status), - return the new certificate with the appropriate MIME type. If not, - return the output of the ca command with MIME type "text/plain". - -3 Set up your web server to accept connections signed by your demo - CA. This probably involves obtaining the PEM-encoded CA certificate - (ordinarily in $SSLDIR/CA/cacert.pem) and installing it into a - server database. See your server manual for instructions. - |