doc/ns-ca.doc

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.