diff options
Diffstat (limited to 'doc/ms3-ca.doc')
| -rw-r--r-- | doc/ms3-ca.doc | 398 |
1 files changed, 0 insertions, 398 deletions
diff --git a/doc/ms3-ca.doc b/doc/ms3-ca.doc deleted file mode 100644 index f8350aadc2..0000000000 --- a/doc/ms3-ca.doc +++ /dev/null @@ -1,398 +0,0 @@ -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 - |