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 .
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.