openssl/doc/ms3-ca.doc

Date: Mon, 9 Jun 97 08:00:33 +0200
From: Holger.Reif@PrakInf.TU-Ilmenau.DE (Holger Reif)
Subject: ms3-ca.doc
Organization: TU Ilmenau, Fak. IA, FG Telematik
Content-Length: 14575
Status: RO
X-Status: 

Loading client certs into MSIE 3.01
===================================

This document conatains all the information necessary to succesfully set up 
some scripts to issue client certs to Microsoft Internet Explorer. It 
includes the required knowledge about the model MSIE uses for client 
certification and includes complete sample scripts ready to play with. The 
scripts were tested against a modified ca program of SSLeay 0.6.6 and should 
work with the regular ca program that comes with version 0.8.0. I haven't 
tested against MSIE 4.0

You can use the information contained in this document in either way you 
want. However if you feel it saved you a lot of time I ask you to be as fair 
as to mention my name: Holger Reif <reif@prakinf.tu-ilmenau.de>.

1.) The model used by MSIE
--------------------------

The Internet Explorer doesn't come with a embedded engine for installing 
client certs like Netscape's Navigator. It rather uses the CryptoAPI (CAPI) 
defined by Microsoft. CAPI comes with WindowsNT 4.0 or is installed together 
with Internet Explorer since 3.01. The advantage of this approach is a higher 
flexibility because the certificates in the (per user) system open 
certificate store may be used by other applications as well. The drawback 
however is that you need to do a bit more work to get a client cert issued.

CAPI defines functions which will handle basic cryptographic work, eg. 
generating keys, encrypting some data, signing text or building a certificate 
request. The procedure is as follows: A CAPI function generates you a key 
pair and saves it into the certificate store. After that one builds a 
Distinguished Name. Together with that key pair another CAPI function forms a 
PKCS#10 request which you somehow need to submit to a CA. Finally the issued 
cert is given to a yet another CAPI function which saves it into the 
certificate store.

The certificate store with the user's keys and certs is in the registry. You 
will find it under HKEY_CURRENT_USER/Software/Microsoft/Cryptography/ (I 
leave it to you as a little exercise to figure out what all the entries mean 
;-). Note that the keys are protected only with the user's usual Windows 
login password.

2.) The practical usage
-----------------------

Unfortunatly since CAPI is a system API you can't access its functions from 
HTML code directly. For this purpose Microsoft provides a wrapper called 
certenr3.dll. This DLL accesses the CAPI functions and provides an interface 
usable from Visual Basic Script. One needs to install that library on the 
computer which wants to have client cert. The easiest way is to load it as an 
ActiveX control (certenr3.dll is properly authenticode signed by MS ;-). If 
you have ever enrolled e cert request at a CA you will have installed it.

At time of writing certenr3.dll is contained in 
http://www.microsoft.com/workshop/prog/security/csa/certenr3.exe. It comes 
with an README file which explains the available functions. It is labeled 
beta but every CA seems to use it anyway. The license.txt allows you the 
usage for your own purposes (as far as I understood) and a somehow limited 
distribution. 

The two functions of main interest are GenerateKeyPair and AcceptCredentials. 
For complete explanation of all possible parameters see the README file. Here 
are only minimal required parameters and their values.

GenerateKeyPair(sessionID, FASLE, szName, 0, "ClientAuth", TRUE, FALSE, 1)
- sessionID is a (locally to that computer) unique string to correlate the 
generated key pair with a cert installed later.
- szName is the DN of the form "C=DE; S=Thueringen; L=Ilmenau; CN=Holger 
Reif; 1.2.840.113549.1.9.1=reif@prakinf.tu-ilmenau.de". Note that S is the 
abreviation for StateOrProvince. The recognized abreviation include CN, O, C, 
OU, G, I, L, S, T. If the abreviation is unknown (eg. for PKCS#9 email addr) 
you need to use the full object identifier. The starting point for searching 
them could be crypto/objects.h since all OIDs know to SSLeay are listed 
there.
- note: the possible ninth parameter which should give a default name to the 
certificate storage location doesn't seem to work. Changes to the constant 
values in the call above doesn't seem to make sense. You can't generate 
PKCS#10 extensions with that function.

The result of GenerateKeyPair is the base64 encoded PKCS#10 request. However 
it has a little strange format that SSLeay doesn't accept. (BTW I feel the 
decision of rejecting that format as standard conforming.) It looks like 
follows:
	1st line with 76 chars
	2nd line with 76 chars
	...
	(n-2)th line with 76 chars
	(n-1)th line contains a multiple of 4 chars less then 76 (possible 
empty)
	(n)th line has zero or 4 chars (then with 1 or 2 equal signs - the 
		original text's lenght wasn'T a multiple of 3) 
	The line separator has two chars: 0x0d 0x0a

AcceptCredentials(sessionID, credentials, 0, FALSE)
- sessionID needs to be the same as while generating the key pair
- credentials is the base64 encoded PKCS#7 object containing the cert. 

CRL's and CA certs are not required simply just the client cert. (It seems to 
me that both are not even checked somehow.) The only format of the base64 
encoded object I succesfully used was all characters in a very long string 
without line feeds or carriage returns. (Hey, it doesn't matter, only a 
computer reads it!)

The result should be S_OK. For error handling see the example that comes with 
certenr3.dll.

A note about ASN.1 character encodings. certenr3.dll seems to know only about 
2 of them: UniversalString and PrintableString. First it is definitely wrong 
for an email address which is IA5STRING (checked by ssleay's ca). Second 
unfortunately MSIE (at least until version 3.02) can't handle UniversalString 
correctly - they just blow up you cert store! Therefore ssleay's ca (starting 
from version 0.8.0) tries to convert the encodings automatically to IA5STRING 
or TeletexString. The beef is it will work only for the latin-1 (western) 
charset. Microsoft still has to do abit of homework...

3.) An example
--------------

At least you need two steps: generating the key & request and then installing 
the certificate. A real world CA would have some more steps involved, eg. 
accepting some license. Note that both scripts shown below are just 
experimental state without any warrenty!

First how to generate a request. Note that we can't use a static page because 
of the sessionID. I generate it from system time plus pid and hope it is 
unique enough. Your are free to feed it through md5 to get more impressive 
ID's ;-) Then the intended text is read in with sed which inserts the 
sessionID. 

-----BEGIN ms-enroll.cgi-----
#!/bin/sh
SESSION_ID=`date '+%y%m%d%H%M%S'`$$
echo Content-type: text/html
echo
sed s/template_for_sessId/$SESSION_ID/ <<EOF
<HTML><HEAD>
<TITLE>Certificate Enrollment Test Page</TITLE>
</HEAD><BODY>

<OBJECT
    classid="clsid:33BEC9E0-F78F-11cf-B782-00C04FD7BF43"
    codebase=certenr3.dll
    id=certHelper
    >
</OBJECT>

<CENTER>
<H2>enrollment for a personal cert</H2>
<BR><HR WIDTH=50%><BR><P>
<FORM NAME="MSIE_Enrollment" ACTION="ms-gencert.cgi" ENCTYPE=x-www-form-
encoded METHOD=POST>
<TABLE>
    <TR><TD>Country</TD><TD><INPUT NAME="Country" VALUE=""></TD></TR>
    <TR><TD>State</TD><TD><INPUT NAME="StateOrProvince" VALUE=""></TD></TR>
    <TR><TD>Location</TD><TD><INPUT NAME="Location" VALUE=""></TD></TR>
    <TR><TD>Organization</TD><TD><INPUT NAME="Organization" 
VALUE=""></TD></TR>
    <TR><TD>Organizational Unit</TD>
        <TD><INPUT NAME="OrganizationalUnit" VALUE=""></TD></TR>
    <TR><TD>Name</TD><TD><INPUT NAME="CommonName" VALUE=""></TD></TR>
    <TR><TD>eMail Address</TD>
        <TD><INPUT NAME="EmailAddress" VALUE=""></TD></TR>
    <TR><TD></TD>
        <TD><INPUT TYPE="BUTTON" NAME="submit" VALUE="Beantragen"></TD></TR>
</TABLE>
	<INPUT TYPE="hidden" NAME="SessionId" VALUE="template_for_sessId">
	<INPUT TYPE="hidden" NAME="Request" VALUE="">
</FORM>
<BR><HR WIDTH=50%><BR><P>
</CENTER>

<SCRIPT LANGUAGE=VBS>
    Dim DN

    Sub Submit_OnClick
	Dim TheForm
	Set TheForm = Document.MSIE_Enrollment
	sessionId	= TheForm.SessionId.value
	reqHardware     = FALSE
	C		= TheForm.Country.value
	SP		= TheForm.StateOrProvince.value
	L		= TheForm.Location.value
	O		= TheForm.Organization.value
	OU		= TheForm.OrganizationalUnit.value
	CN              = TheForm.CommonName.value
	Email		= TheForm.EmailAddress.value
        szPurpose       = "ClientAuth"
        doAcceptanceUINow   = FALSE
        doOnline        = TRUE

	DN = ""

	Call Add_RDN("C", C)
	Call Add_RDN("S", SP)
	Call Add_RDN("L", L)
	Call Add_RDN("O", O)
	Call Add_RDN("OU", OU)
	Call Add_RDN("CN", CN)
	Call Add_RDN("1.2.840.113549.1.9.1", Email)
		      ' rsadsi
				     ' pkcs
				       ' pkcs9
					 ' eMailAddress
        On Error Resume Next
        sz10 = certHelper.GenerateKeyPair(sessionId, _
                FALSE, DN, 0, ClientAuth, FASLE, TRUE, 1)_
        theError = Err.Number
        On Error Goto 0
        if (sz10 = Empty OR theError <> 0) Then
            sz = "The error '" & Hex(theError) & "' occurred." & chr(13) & _
                chr(10) & "Your credentials could not be generated."
            result = MsgBox(sz, 0, "Credentials Enrollment")
            Exit Sub
	else 
	    TheForm.Request.value = sz10
	    TheForm.Submit
        end if
    End Sub

    Sub Add_RDN(sn, value)
	if (value <> "") then
	    if (DN <> "") then
		DN = DN & "; "
	    end if
	    DN = DN & sn & "=" & value
	end if
    End Sub
</SCRIPT>
</BODY>
</HTML>
EOF
-----END ms-enroll.cgi-----

Second, how to extract the request and feed the certificate back? We need to 
"normalize" the base64 encoding of the PKCS#10 format which means 
regenerating the lines and wrapping with BEGIN and END line. This is done by 
gawk. The request is taken by ca the normal way. Then the cert needs to be 
packed into a PKCS#7 structure (note: the use of a CRL is necessary for 
crl2pkcs7 as of version 0.6.6. Starting with 0.8.0 it it might probably be 
ommited). Finally we need to format the PKCS#7 object and generate the HTML 
text. I use two templates to have a clearer script.

1st note: postit2 is slightly modified from a program I found at ncsa's ftp 
site. Grab it from http://www.easterngraphics.com/certs/IX9704/postit2.c. You 
need utils.c from there too.

2nd note: I'm note quite sure wether the gawk script really handles all 
possible inputs for the request right! Today I don't use this construction 
anymore myself.

3d note: the cert must be of version 3! This could be done with the nsComment 
line in ssleay.cnf...

------BEGIN ms-gencert.cgi-----
#!/bin/sh
FILE="/tmp/"`date '+%y%m%d%H%M%S'-`$$
rm -f "$FILE".*

HOME=`pwd`; export HOME  # as ssleay.cnf insists on having such an env var
cd /usr/local/ssl #where demoCA (as named in ssleay.conf) is located

postit2 -s " " -i 0x0d > "$FILE".inp  # process the FORM vars

SESSION_ID=`gawk '$1 == "SessionId" { print $2; exit }' "$FILE".inp`

gawk \
	'BEGIN { \
		OFS = ""; \
		print "-----BEGIN CERTIFICATE REQUEST-----"; \
		req_seen=0 \
	} \
	$1 == "Request" { \
		req_seen=1; \
		if (length($2) == 72) print($2); \
		lastline=$2; \
		next; \
	} \
	{ \
		if (req_seen == 1) { \
			if (length($1) >= 72) print($1); \
			else if (length(lastline) < 72) { \
				req_seen=0; \
				print (lastline,$1); \
			} \
		lastline=$1; \
		} \
	} \
	END { \
		print "-----END CERTIFICATE REQUEST-----"; \
	}' > "$FILE".pem < "$FILE".inp 

ssleay ca -batch -in "$FILE".pem -key passwd -out "$FILE".out
ssleay crl2pkcs7 -certfile "$FILE".out -out "$FILE".pkcs7 -in demoCA/crl.pem

sed s/template_for_sessId/$SESSION_ID/ <ms-enroll2a.html >"$FILE".cert
/usr/local/bin/gawk \
	'BEGIN	{ \
		OFS = ""; \
		dq = sprintf("%c",34); \
	} \
	$0 ~ "PKCS7" { next; } \
	{ \
		print dq$0dq" & _"; \
	}' <"$FILE".pkcs7 >> "$FILE".cert
cat  ms-enroll2b.html >>"$FILE".cert

echo Content-type: text/html
echo Content-length: `wc -c "$FILE".cert`
echo
cat "$FILE".cert
rm -f "$FILE".*
-----END ms-gencert.cgi-----

----BEGIN ms-enroll2a.html----
<HTML><HEAD><TITLE>Certificate Acceptance Test Page</TITLE></HEAD><BODY>

<OBJECT
    classid="clsid:33BEC9E0-F78F-11cf-B782-00C04FD7BF43"
    codebase=certenr3.dll
    id=certHelper
    >
</OBJECT>

<CENTER>
<H2>Your personal certificate</H2>
<BR><HR WIDTH=50%><BR><P>
Press the button!
<P><INPUT TYPE=BUTTON VALUE="Nimm mich!" NAME="InstallCert">
</CENTER>
<BR><HR WIDTH=50%><BR>

<SCRIPT LANGUAGE=VBS>
    Sub InstallCert_OnClick

	sessionId	= "template_for_sessId"
credentials = "" & _
----END ms-enroll2a.html----

----BEGIN ms-enroll2b.html----
""
        On Error Resume Next
        result = certHelper.AcceptCredentials(sessionId, credentials, 0, 
FALSE)
        if (IsEmpty(result)) Then
           sz = "The error '" & Err.Number & "' occurred." & chr(13) & 
chr(10) & "This Digital ID could not be registered."
           msgOut = MsgBox(sz, 0, "Credentials Registration Error")
           navigate "error.html"
        else
           sz = "Digital ID successfully registered."
           msgOut = MsgBox(sz, 0, "Credentials Registration")
           navigate "success.html"
        end if
	Exit Sub
    End Sub
</SCRIPT>
</BODY>
</HTML>
----END ms-enroll2b.html----

4.) What do do with the cert?
-----------------------------

The cert is visible (without restarting MSIE) under the following menu:
View->Options->Security->Personal certs. You can examine it's contents at 
least partially.

To use it for client authentication you need to use SSL3.0 (fortunately 
SSLeay supports it with 0.8.0). Furthermore MSIE is told to only supports a 
kind of automatic selection of certs (I personally wasn't able to test it 
myself). But there is a requirement that the issuer of the server cert and 
the issuer of the client cert needs to be the same (according to a developer 
from MS). Which means: you need may more then one cert to talk to all 
servers...

I'm sure we will get a bit more experience after ApacheSSL is available for 
SSLeay 0.8.8.


I hope you enjoyed reading and that in future questions on this topic will 
rarely appear on ssl-users@moncom.com ;-)

Ilmenau, 9th of June 1997
Holger Reif <reif@prakinf.tu-ilmenau.de>
-- 
read you later  -  Holger Reif
----------------------------------------  Signaturprojekt Deutsche Einheit
TU Ilmenau - Informatik - Telematik                      (Verdamp lang her)
Holger.Reif@PrakInf.TU-Ilmenau.DE         Alt wie ein Baum werden, um ueber
http://Remus.PrakInf.TU-Ilmenau.DE/Reif/  alle 7 Bruecken gehen zu koennen