1 The following documentation was supplied by Jeff Barber, who provided the
2 patch to the CA program to add this functionality.
6 Jeff Barber Email: jeffb@issl.atl.hp.com
8 Hewlett Packard Phone: (404) 648-9503
9 Internet and System Security Lab Fax: (404) 648-9516
12 ---------------------cut /\ here for ns-ca.doc ------------------------------
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:
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.
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
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"
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".
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.
61 Now, here's how the SSLeay package can be used to provide client
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.
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).
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 ]
81 Here's a sample input file:
85 O = Some Organization, Inc.
86 OU = Netscape Compatibility Group
88 Email = jxdoe@someorg.com
89 SPKAC = MIG0MGAwXDANBgkqhkiG9w0BAQEFAANLADBIAkEAwmk6FMJ4uAVIYbcvIOx5+bDGTfvL8X5gE+R67ccMk6rCSGbVQz2cetyQtnI+VIs0NwdD6wjuSuVtVFbLoHonowIDAQABFgAwDQYJKoZIhvcNAQEEBQADQQBFZDUWFl6BJdomtN1Bi53mwijy1rRgJ4YirF15yBEDM3DjAQkKXHYOIX+qpz4KXKnl6EYxTnGSFL5wWt8X2iyx
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,
95 $SSLDIR/bin/ca -spkac /tmp/cert.req -out /tmp/cert
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
105 The "-spkac" capability doesn't support multiple files (I think).
107 Any CHALLENGE provided in the SPKAC is simply ignored.
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.
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.
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.
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.
134 So, what do you have to do to make use of this stuff to create an online
135 demo CA capability with SSLeay?
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
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".
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.