OpenSSL PKCS#12 Program FAQ v1.77

Contents.

Introduction and latest changes.

1. Basics.

Download Latest Version.
Commercial Licensing conditions.
2. Compiling.

3. Common problems.

Netscape Communicator Specific Issues.
MSIE and Outlook 98 specific issues.
MSIE Authenticode issues.
4. PFX.

5. Technical queries.

6. DSA keys.

7. Future Development.

Introduction and latest changes.

There are several questions that crop up frequently relating to my PKCS#12 patch for OpenSSL and SSLeay. After replying to the same things several times I decided to write an FAQ to deal with them.

If you read nothing else you should read the ca-fix question .

If you are using MSIE4 you should read the private key security question.

There is a new version of the patch available. Check the list of changes.

Recently added to the FAQ:

MSIE5 issues.
SSL client authentication problems.
PKCS#12 files and authenticode, using PVK files and using large keys in export versions of software.
Comment on using Netscape 4.5  and 4.06
Problems with CA certificates and Outlook 98.
 

1. Basics.

Q. Where can I get the latest version of your patch?

NB. It seems that the only way to stop MSIE, NS or this server screwing up my links or sending binary files as text is to give them a .bin extension. All files with a .bin extension are gziped tar files.

Version 0.3 of the patch is available here this is intended for use with SSLeay 0.8.1. This is no longer being developed and will be phased out soon.

Version 0.54 of the program is available here. This should work with SSLeay 0.9.x, OpenSSL 0.9.1c and 0.9.1.2.

If you use OpenSSL version 0.9.3 or later then my PKCS#12 program is built in: you use it with openssl pkcs12. In future the external versions of the program will be phased out and features only added to the internal version.

Q. What is PKCS#12?

A. PKCS#12 is a standard for storing private keys and certificates securely (well sort of). It is used in (among other things) Netscape 4.04 (and later) and Microsoft Internet Explorer 4.0 with their import and export options.

Q. Is your PKCS#12 implementation compatible with Netscape and MSIE versions?

A. Yes it is. You can readily export PKCS#12 files and have my patch pull them apart or generate PKCS#12 files that MSIE and NS will import - but see the Usage section below.

Q. What about Outlook 98?

A. Yes. Other than the ability to delete certificates and private keys all the comments about MSIE4 also apply to Outlook 98.
You should check out the Outlook 98 CA certificate question though.

Q. What about PFX is it the same as PKCS#12 or what?

A. I've had quite a few queries about PFX lately so I've added a PFX section to this FAQ.

Q. What is the copyright status of your patch?

A. There are now two separate copyright statuses. If you use the external program then the conditions are the same as SSLeay or OpenSSL. Its free: do what you want with it as long as you additionally mention my name if you use it. If you use the internal OpenSSL version then there are no additional conditions: it is released under the OpenSSL license.

Q. What are the commercial rules regarding the code?

A. Since 0.53 I've decided to remove the mandatory registration condition. Commercial conditions are now the same as non-commercial.

Q. Why should I use this patch?

A. Other than the obvious reason that you want PKCS#12 :-) It's probably the easiest way to generate your own certificates for MSIE and NS. You don't need a separate server and you can add them simply by importing a file. It is also the only way to access the private keys of other certificates (e.g. issued by a standard CA). You can also use PKCS#12 to bypass the Netscape export version 512 bit RSA key restriction (but not MSIE4). PKCS#12 files produced by my program are also more secure than the NS and MSIE4 versions.

Q. What has changed since the last version of the program?

A. Check out the CHANGES file for info about the latest changes. The main changes since 0.52 are that the pkcs12 program will now automatically work out which certificate belongs to the private key and the caname option is no longer need to produce files MSIE will import. Version 0.53 had a bug which broke the keyex and keysig options which is now fixed. 0.54 also includes some high level PKCS#12 functions that make handling PKCS#12 files considerably easier.

2. Compiling.

Q. How do I apply the patch?

A. Version 0.3 is just a set of replacement files. Simply extract them into the SSLeay main directory and do a make install. For version 0.54 check the INSTALL file.

Q. I get errors about undefined symbols and earlier something like:

make[2]: *** No rule to make target `/usr/include/libio.h', needed by
`hmac.o'.  Stop.

what's wrong?

A. There is some gunk in crypto/pkcs12/Makefile left over from a Linux compile. If you do a make depend first it should update the Makefiles appropriately.

Q. When I extract the patch I get errors about trailing garbage.

A. This is harmless: it can be ignored.

Q. How do I compile under Win95/NT?

A. This has been simplified a little :-) If you are using version 0.54 of the PKCS#12 program  follow the INSTALL file instructions. For 0.8.1 and version 0.3 of the patch you need perl and Visual C++ (I've tried 4.2 and 5.0). Extract the files and from the main SSLeay directory enter the following commands.

ms\do_ms
perl Configure VC-WIN32
nmake -f ms\ntdll.mak

This should compile everything and you can use the program as "ssleay pkcs12".  You will get a warning saying:
BIO_s_file_internal_w16 does not have a number assigned
at the ms\do_ms stage: this can be ignored.

Q. What compilation options are there?

A. Other than debugging options there is an option NO_IDEA which will not use the IDEA cipher. For information on the debugging options see the advanced section. There is also a RANLIB option in the Makefile.

3. Common problems.

Q. What do all those horrible options do?

A. I get the occasional comment that the various options are rather cryptic. Here is a description of them and their typical use.

Q. I followed the instructions for generating client certificates but the certificates seem to be invalid: when I try to use them for SSL client authentication I get a box saying I have no client certificates (Communicator) or an empty listbox asking me to select a certificate (MSIE).

A. This is actually nothing to do with my PKCS#12 program but it gets asked so much I'll include the answer here. With all versions of MSIE and Netscape 4.05 or later you can only use a certificate for SSL client authentication if the CA is sent in the acceptable CA list by the server: so if it doesn't work your server is misconfigured. How you include the CA in the list depends on the server in question: with Apache SSL for example you include your client CA in the directory pointed to by SSLCACertificatePath and do a c_rehash <dir> or append it to the file pointed to by SSLCACertificateFile. You can use the s_client program to check if your CA appears in the list.
 

Netscape Communicator Specific Issues.

Q. I can't seem to import a PKCS#12 file into Netscape why?

A. One common reason if that you haven't set a friendly name with the -name option. If you don't set this it may complain. Alternatively if you are using Netscape 4.03 or earlier you should read the PFX section.

Q. I'm using Netscape 3.0x can I still use your program or PFX or some equivalent?

A. No: they don't support PKCS#12 or PFX nor is it possible to directly access the key and certificate database because its format is undocumented.

Q. Are there any issues relating to Netscape private key security.

A.  If you delete a certificate it still retains the private key in the database: from where it can be retrieved by anyone with the appropriate knowledge (e.g. me) and the Communicator password. The easiest way to delete the private key is by deleting the key3.db and cert7.db files in the Communicator diectory. This deletes all private keys, be very very sure this is what you want. There are circumstances where you will also need to delete or rename the Netscape 3.0 database files called key.db and cert5.db. The reason for this is that if Communicator doesn't see the key3.db and cert7.db files but does see the older database files it reads in and converts the older files (when you next give the password).

Q. Netscape complains that my certificate is not certified for email, why?

A. This is because you need to set the nsCertType (see openssl.cnf or ssleay.cnf) option properly. For email and normal client verification you need the option 0xa0. Alternatively you can comment out the nsCertType line completely to get S/MIME and SSL client use (which is probably what you want) See also the ca-fix question below.

Q. I want to use the certificate for object signing with Netscape: how do I do this?

A You need to set nsCertType to 0xb0 (or 0x10 for just object signing and nothing else) and modify the CA certificate appropriately (nsCertType 0x7 or 0x01). See the ca-fix question below.

Otherwise things proceed as per the instructions for the signing tools. It appears that (unlike email) Netscape does not install an object signing CA certificate as untrusted if it does not recognize it. This means that if you want your object signing CA to be recognized its certificate needs to be already loaded and trusted in the user's database.

Qs Why when I send signed mail to someone do they say NS complain that my CA certificate is invalid? My CA certificate doesn't seem to be added to the list when I import a certificate.

A. This is due to what older versions of Netscape Communicator consider to be a valid CA certificate. For a fuller description of this issue see my document Netscape CA handling: When is a CA Not a CA? I have written a program that can patch CA certificates to allow Netscape to tolerate them: for details see: the Certificate patcher program description. You NEED to fix this if you want to use S/MIME properly. Even if you only use MSIE or Outlook Express you should still patch your CA certificate.

Q. I'm using 4.5 or 4.06 and the patcher program doesn't help. When I send signed mail to someone it doesn't auto add the CA with 4.5. Whats happening?

A. 4.5 and 4.06 certificate handling appears to be badly broken. It regards the nsCertType extension as invalid (this is a Netscape specific extension!) you can see this for yourself by removing the trust settings of some standard CAs then clicking on verify it will say the CA is invalid and not trusted for several standard CAs. Also when you send signed mail it does not include the root CA.

Q. When I send mail to someone they say that although my CA is added to the list of signers but they cannot select it in order to trust it!

A. This problem has recently been brought to my attention. In this case it was apparently due to ampersand characters (&) in the CA fields. I say apparently because, although I can reproduce the problem by reading the signed mail in question, I have been unable to reproduce it by generating CAs and certificates with & characters in them. I'll give more info if I can determine the precise cause of this.

Q. I'm using Windows 95/NT and ca-fix crashes or doesn't work.

A. The usual reason for this is that OpenSSL and ca-fix are linked with different runtime libraries. The default Makefiles for OpenSSL link with the multithreaded DLL version (/MD option).

Q. What about the ca-kludge.doc file in the PFX documentation?

A. While this does still work it is not really recommended because it just sets the nsCertType extension. ca-fix is the preferred solution.

Q. Netscape seems to import certificates with >512 bit RSA keys.

A. Just be happy it does! There don't seem to be any side effects.

Q. The recreated file is quite a bit smaller than the original NS one, why?

A. For some reason the encoding used by NS is not very efficient. The encoding used by my patch is somewhat better (actually its the indefinite length encoding in OpenSSL).

Q. I'm having real problems getting a certificate into Netscape, help!

A. OK here is a  step by step guide on how to do things.

1. Create a CA. E.g. use CA.sh -newca.
2. If you are using OpenSSL 0.9.2 or later, and your configuration file adds the correct extensions (the default configuration file does), then skip to step 4, otherwise get and compile the ca-fix program if you don't have it already.
3. Patch the CA certificate with:
ca-fix -in demoCA/cacert.pem -inkey demoCA/private/cakey.pem -caset  -out newca.pem
This allows the CA to be used for signing SSL Client and S/MIME certificates. If you want to use the CA for object signing only then include the -nscertype 1 option, to support object signing as well as S/MIME and SSL Client use -nscertype 7. For more information on the -nscertype option see the ca-fix documentation. If you are using the latest version of ca-fix then the nobscrit option is unnecessary: see the Outlook 98 CA question for more info.
4. Extend the CA expiry date with e.g.:
x509 -in newca.pem -days 1024 -out cacert.pem -signkey demoCA/private/cakey.pem
5. Replace the CA certificate (demoCA/cacert.pem) with the one created above.
6. If you are using OpenSSL 0.9.2 or later then edit the nsCertType line in openssl.cnf (or ssleay.cnf) to read email, sslclient or just comment it out for S/MIME and SSL Client use. If you are using SSLeay or earlier versions of OpenSSL change it to 0xa0 or comment it out. For object signing only use objsign (0x10 in earlier versions), for all three use email, sslclient, objsign (0xb0).
7. Create a new certificate request with CA.sh -newreq
8. Sign the request with CA.sh -signreq
9 .Create a PKCS#12 file with:
pkcs12 -export -in newcert.pem -inkey newreq.pem -certfile demoCA/cacert.pem -name "MY CERTIFICATE" -out mycert.p12
10. Import mycert.p12 file into Netscape: Security->Yours->Import.
11. You should now have the CA certificate in "signers". Set it to trust the CA.
12. Try verifying the cert in Netscape.
13. Try some test signed mail (just "save draft" then check the drafts folder).

To generate more certificates just repeat steps 7 to 13.

Q. I followed the instructions to create a client certificate but I can't seem to use the certificate for SSL client authentication: it says I have no user certificates!

A. If you can verify the certificate in Netscape then this is almost certainly due to server misconfiguration: check out the SSL client authentication question for details.

MSIE and Outlook 98 specific issues.

Q. MSIE4 or Outlook 98 flashes up a warning or asks for my password lots of times when I try to export a certificate.

A. This is a known bug: it asks 16 or 17 times. When it will be fixed is anyones guess. If it only asks a small number of times (around 4) then your private key is not exportable. Check the exportable question below.

Q. What's this about warnings and passwords? When I export my certificates it doesn't give any warning.

A. This is because you have the default (low) private key security. This is more like no private key security. You need to correct this problem: see the private key security question.

Q. I've exported a certificate and key to a file with MSIE4 but when I examine it with your utilities it doesn't contain a private key!

A. This is horrible MSIE4 PKCS#12 behaviour. The private keys have a flag set at creation time (in practice by a CA) which determines whether they are exportable (readable) or not. A non exportable key cannot be read by any documented calls (and thus cannot be stolen in this way). Unfortunately this makes the key impossible to back up: if you lose it, for example due to registry corruption, then you have lost it forever.

Worse when you export a certificate it gives no indication that the key hasn't been exported: it just appears to work as normal. If a warning has been set it erroneously says that the something is requesting permission to read the key even though this is not permitted. As a result it gives the impression that the private key has been backed up when it has not.

Q. Outlook 98 flashes up a dialog box saying "An error occurred while trying to export security information" what's wrong?

A. Your private key is probably not exportable. This means that it cannot be backed up. Even though a warning dialog box may flash up asking your permission to read the key.

Q. I can't seem to import a PKCS#12 file into MSIE, why?

You noted the informative error message? There are lots of possible reasons for this.

It is possible that you haven't set a friendly name with the -name option. You need to set this or MSIE will complain.

If the file is from MSIE or Outlook 98 then it is possible that it doesn't contain a private key. Check out the exportable question for more info.

It may not like your CA certificate (see ca-fix question).

The most common reason is that you are using a user certificate with an RSA key larger than 512 bits with MSIE export version. If you can, apply the domestic (128 bit) security patch and try again. Apparently this doesn't always work properly though. The domestic security patch doesn't properly set the enhanced CSP to be the default provider, the following fix was posted to the CryptoAPI group by Blair Dillaway (blaird@microsoft.com):

There is a known installation problem when upgrading IE 4 to the export controlled cryptographic components.  When you install these components, the Microsoft Enhanced Provider is installed on the system and registered under
HKLM\SOFTWARE\Microsoft\Cryptography\Defaults\Provider
(i.e., there will be a sub-key entry under this key for "Microsoft Enhanced Cryptographic Provider v1.0").  However, when importing a PKCS-12 blob, the system uses the default Type 001 provider as indicated under the key
HKLM\SOFTWARE\Microsoft\Cryptography\Defaults\Provider Types\Type
001
This key is not updated when the Enhanced provider is installed.  If you edit this key value (using regedit) to change it from the "Microsoft Base Cryptographic Provider v1.0" to "Microsoft Enhanced Cryptographic Provider v1.0" you will be able to import 1024-bit (or larger) RSA keys.  Be sure to double check the spelling!

If you apply this fix then you should be read the PVK file question if you have PVK files created before the fix.

Alternatively if you want to use the key for signing only then you may be in luck: check out the signature key question.

The rest of us need to use 512 bit keys. This only applies to user certificates, CA certificates don't have this restriction.

Q. MSIE will import my certificate but it complains that it has expired!

A. This happens because the expiry date of the CA is before the expiry date of the certificate. If this happens you can extend the CA expiry date using the command:

x509 -in cacert.pem -days 1024 -out newca.pem -signkey private/cakey.pem

and then replacing cacert.pem with newca.pem.

Q. How do I delete a certificate or private key from MSIE4?

A. Unfortunately this cannot be done with MSIE4, for MSIE5 there is an option to delete the certificate. There are several other options. Before you try these check out the exportable question.

You can install Outlook 98: it has the option to export and delete a certificate and private key. If you don't mind installing Outlook 98 this is probably the easiest option.

You could edit the registry (not recommended).

You can also use the certmgr tool. This is a very useful tool that can be obtained from  here . The command:

certmgr -s MY -del -c

will either delete your user certificate or give you a choice of which to delete (if you have more than one). It does not delete the private key.

Q. Is there anything else to watch out for with MSIE import?

A. When you import a PKCS#12 file into MSIE4 it is added with low security. This means that any program running under the same Windows user (programs, abusers of security holes, signed ActiveX controls) can silently read your private keys and thus steal your identity. A program has been written by Microsoft that allows the security level to increased for already existing keys, download it from here . The command:

certmgr -s MY -addui -c

will allow you to increase the security level of any private keys you have associated with certificates. For a more complete description of the problem see my document: CryptoAPI, base CSPs and private key security.

With MSIE5 things have changed somewhat. You can either check the 'Enable strong private key protection' box or leave the 'Mark the private key as exportable' box unchecked. It is advisable to check the 'Enable strong private key protection' box so private keys cannot be used without your approval. If you leave the 'Mark the private key as exportable'  box unchecked then your private keys cannot be extracted (and hence stolen) but keep the imported PKCS#12 file safe because it is the only way to recover your private key.

Q. I'm using Outlook 98 and it complains that there is a problem with my certificate. I get complaints from users of Outlook 98 saying that my signed mail is not recognised and it says "some other error".

A. The reason for this is that Outlook 98 certificate handling is broken. If you follow the PKIX guidelines and include a critical basicConstraints extension then Outlook 98 will complain. The easiest fix is to include the basicConstraints flag in your CA certificate but not critical. You then need to reinstall the CA certificate in anything that uses it :-( The new version of ca-fix by default no longer makes basicConstraints critical. The older version needs the nobscrit option.:

Q. I'm having real problems getting a certificate into MSIE, help!

A. OK here is a  step by step guide on how to do things.

1. Create a CA. E.g. use CA.sh -newca.
2. If you are using OpenSSL 0.9.2 or later, and your configuration file adds the correct extensions (the default configuration file does), then skip to step 4, otherwise get and compile the ca-fix program if you don't have it already.
3. Patch the CA certificate with:
ca-fix -nobscrit -in demoCA/cacert.pem -inkey demoCA/private/cakey.pem -caset  -out newca.pem
If you are using the latest version of ca-fix then the nobscrit option is unnecessary: see the Outlook 98 CA question for more info.
4. Extend the CA expiry date with e.g.:
x509 -in newca.pem -days 1024 -out cacert.pem -signkey demoCA/private/cakey.pem
5. Replace the CA certificate (demoCA/cacert.pem) with the one created above.
6. If you are using MSIE5 then skip to 7, otherwise create a certificate file with:
x509 -in demoCA/cacert.pem -outform DER -out cacert.der
You now need to open the cacert.der file with MSIE as MIME type application/x-x509-ca-cert. Files with extension .der seem to be already registered as this type so just transfer cacert.der to the PC and double click on it. You should then be able to open the file and set it to be trusted as a CA. Check it appears in View->Internet Options->Content->Authorities.
7. If you are using OpenSSL 0.9.2 or later then the nsCertType line in openssl.cnf (or ssleay.cnf) to read sslclient, email or just comment it out. For earlier versions of OpenSSL or SSLeay the nsCertType line in openssl.cnf (or ssleay.cnf) to read 0xa0 or just comment it out.
8.  If you are using the export version edit the default_bits section in openssl.cnf (or ssleay.cnf) to set the key size to 512 bits.
9. Create a new certificate request with CA.sh -newreq
10. Sign the request with CA.sh -signreq
11 .Create a PKCS#12 file with:
pkcs12 -export -in newcert.pem -inkey newreq.pem -name "MY CERTIFICATE" -certfile demoCA/cacert.pem -out mycert.p12
If you are using MSIE5 then also add the maciter option to make the PKCS#12 file more secure.
12. Import mycert.p12 file into MSIE4: View->Internet Options->Content->Personal->Import. With MSIE5 choose Tools->Internet Options->Content->Certificates->Import and follow the instructions in the wizard. If you haven't got the root CA added to the database it will be added automatically, but you need to confirm that you want to do this.
13. In MSIE4 check the certificate is present with View->Internet Options->Content->Personal->View Certificate. In MSIE5 you should be able to see the certificate in the list after you import it.
14. If you are using Outlook Express or Outlook 98 try signing mail with the certificate.
15. After you are satisfied that it works OK check the private key security question and increase the security level of your newly imported private key.

If you want to generate more certificates repeat steps 9 to 14.

Q. I followed the instructions to create a client certificate but I can't seem to use the certificate for SSL client authentication: it asks me to pick a certificate from an empty listbox!

A. This is almost certainly due to server misconfiguration: check out the SSL client authentication question for details.

Q. Are there any specific MSIE5 issues?

A. Many of the problems with MSIE4 seem to have been fixed in MSIE5, check out the technical section for more info.

MSIE Authenticode issues.

My thanks to Miguel Angel Fraga  for some initial suggestions about how this might be done.

Q. How can I generate and use certificates for Authenticode?

A. This is a lot easier than it might first appear, if you handle it right. If you look at the test Authenticode certificates and authorities you see lots of horrible non standard, complex and deprecated extensions. On top of that there are things like SPC files PVK files and other nasties. Anyway enough waffle here's a step by step guide about what to do.

1. Make sure you have the latest Authenticode tools. The only version of signcode this is known to work with is 5.101.1663.1 several older versions most definitely do not work (I had all manner of problems until I tried the latest version). The easiest place to get these is in the Microsoft Internet Client SDK. You need to use MSIE to download this properly. The latest tools are part of the common stuff that is downloaded whenever you download anything, so select a small package to download and you'll get the tools as well. They are in the bin directory.
2. Generate a CA certificate, trust it for software publishing and import an end user PKCS#12 file with the appropriate values in the certificate (if unsure how to so this just read the MSIE certificate help question). If you wish to use a key larger than 512 bits in size and you do not have the domestic security patch installed then check the signature key question. If you've already got a CA installed but you haven't set it for software publishing then you can just select View->Internet->Options->Content->Authorities and select software publishing in the listbox headed Issuer Type. Find your CA in the window and check the box next to it, assuming you haven't already done so. Increase the security level of the private key see the private key security question. The comments made there are doubly important for Authenticode private keys: it is strongly advised that you use high security and pick a good password. Never ever click on the remember password option when you access an Authenticode key.
3. Find out the commonName (CN) of your user certificate. If unsure you can use:
x509 -in cert.pem -noout -subject
In case it isn't obvious the CN is the bit after CN= part. The file cert.pem if the user certificate file. If you don't have it you can always extract it from the PKCS#12 file with:
pkcs12 -in myfile.p12 -clcerts -nokeys -out cert.pem
4. You should now be able to sign a something with:
signcode -cn "My Object Cert" file.dll
5. Test out the file with:
chktrust file.dll
A nice friendly dialog box should appear letting you examine who it thinks signed it and allowing all sorts of info to be displayed.

Q. Why doesn't this involve messing around messing around with SPC and PVK files?

A. Well if you really want to mess around with SPC and PVK files you can. See the next few questions.

Q. What are SPC files?

A. They are simply DER encoded PKCS#7 files containing the certificates. Well they are in the newer versions of the tools. The older versions used an invalid PKCS#7 format.

Q. How can I extract the contents of an SPC file?

A. If it was created with a newer version of the tools then try:
pkcs7 -inform DER -in mycert.spc -print_certs -out certs.pem
The file certs.pem will then contain all the certificates in PEM form, you can manually cut and paste them if you want.

Q. How can I generate an SPC file?

A. The easiest way is to use the SSLeay tools. Collect all your certificates together into one file in PEM format, you can do this easily from a PKCS#12 file with:
pkcs12 -in mycert.p12 -nokeys -out certs.pem

Then use the OpenSSL program crl2pkcs7 to generate a DER encoded PKCS#7 file:
openssl crl2pkcs7 -nocrl -certfile certs.pem -outform DER -out mycert.spc
You can then use the file mycert.spc just like any other SPC file.

That's the easy way. Slightly harder is to convert each certificate to DER form with:
x509 -in cert1.pem -outform DER -out cert1.der
Then use the supplied cert2spc tool:
cert2spc cert1.der cert2.der ... mycert.spc

Q. How can I use this SPC file with signcode?

A. You can use it in conjunction with the private key (if it has been imported in a PKCS#12 file) with:
signcode -spc mycert.spc -k "MY KEY" file.dll
Replace the name MY KEY with the name of the corresponding private key container. This is the friendly name of the imported PKCS#12 file (the value you gave after the -name parameter).

Q. What about PVK files?

A. I've recently managed to work out the latest PVK format. For more details and SSLeay conversion tools check out my PVK file information page. Using my PVK conversion program you can generate a PVK file from the PEM encoded private key with:

pvk -in key.pem -topvk -out key.pvk

You would then use this with signcode with:

signcode -spc mycert.spc -v key.pvk file.dll

Using this method there is no need to import or generate the PKCS#12 file at all. Simply use the private keys and certificates converted directly from SSLeay.

Q. What about signing with keys larger than 512 bits?

A. If you are able, then installing the domestic security patch and the registry fix is the easiest thing to do. If you are not then you can in actual fact still use keys larger than 512 bits. This isn't documented very well: hence my original assumption that this was not possible. The reason you can do this is that MS CryptoAPI (used by the signing tools) allows signing only keys to be larger than 512 bits. Indeed the documentation suggests that the limit is at least 16,384 bits including key generation. This document is not concerned with key generation because it assumes that OpenSSL creates the necessary keys. Anway there are two ways to handle things. Either with a PVK file or import of a PKCS#12 file.

If you wish to use a PVK file (and this is discouraged due to the weak encryption) then you can just use the sig option to create a PVK file with the private key marked as a signature key, future versions of the PVK conversion program will have this option set by default. For example:

pvk -sig -in key.pem -topvk -out key.pvk

If you wish to keep the key in the registry and import a PKCS#12 file then you need version 0.52 or later of my PKCS#12 program. If you supply the keysig option a special attribute is set in the PKCS#12 file and the private key is imported as a signature key. For example:

pkcs12 -export -in newcert.pem -inkey newreq.pem -name "MY CERTIFICATE" -certfile demoCA/cacert.pem -out mycert.p12 -keysig

If you import the key with MSIE4 you will notice something odd. Although you get no error message the certificate is not listed! This is a bug in MSIE4. If you use Outlook 98 or MSIE5 to import the file you will have no such problems.

This keysig option is off by default: this is because signature keys cannot be used for SSL (in MSIE4 due to a bug) and S/MIME encryption. Note: version 0.53 of my PKCS#12 program had a bug which mean the keysig option didn't work. Upgrade to 0.54.

Q. I've applied the registry fix but I can no longer use old PVK files! What's wrong?

A. The reason for this is that signcode just uses the default CSP which the registry fix changes. You can get round this by telling it to use the base CSP on the command line by using the option: -p "Microsoft Base Cryptographic Provider v1.0". If it doesn't work then double check the spelling! A better solution is to use my PVK conversion tool to convert the key to the newer format which uses strong encryption. You can do this with:

pvk -in key.pvk -out key.pem
pvk -in key.pem -strong -topvk -out key2.pvk

Delete the key.pem intermediate file afterwards.

General issues.

Q. What order do the certificates and keys appear in the output file?

A. They appear in the order they appear in the input file. You can dump just user certificates or CA certificates with the clcerts and cacerts options respectively.

Q. I've outputed a PKCS#12 file to a PEM file, created a new PKCS#12 file from the PEM file and Netscape or MSIE wont import them.

A. Other than the MSIE and NS specific reasons this may be because the prior to version 0.53 the pkcs12 program was a bit naive about matching private keys and certificates. In the input file it takes the first certificate it finds and uses this as the user certificate. This is sometimes incompatible with the output format (see above). The easiest way to do this is to output just client certificates then CA certificates, as follows:

pkcs12 -in my.p12 -clcerts -out cl.pem
pkcs12 -in my.p12 -cacerts -nokeys -out ca.pem
pkcs12 -in cl.pem -certsfile ca.pem -export -name "MYNAME" -out new.p12

From version 0.53 this should not happen any more: the pkcs12 program will automatically work out the right certificate for a private key and supply generic CA names so:

pkcs12 -in my.p12 -out cl.pem
pkcs12 -in cl.pem -export -name "MYNAME"  -out new.p12

should work just fine.

Q. Why would anyone want to split up a PKCS#12 file and recreate it?

A. There are several reasons.  The new file uses triple DES encryption for private keys. It is harder to make dictionary attacks on the password (see iteration counts question). You can also specify a new friendly name, MSIE chooses very unfriendly friendly names. You can also add CA friendly names so the same file works with MSIE and NS.

Q. Version 0.4 of the program seems to produce invalid PKCS#12 files.

A. Yes it does, this was fixed in 0.41.

Q. What is the caname option for?

A. In version 0.50 I added an option to allow a name (friendly name in PKCS#12 jargon) to be associated with each CA certificate in the PKCS#12 file. If you add more than one CA certificate you can use multiple caname arguments to assign a name to each. You can check the names are correct by using the pkcs12 program to display the certificates, since it also includes the name. In version 0.53 and later you no longer need this option with MSIE: it uses another approach.

4. PFX.

Q. What is this PFX format I keep hearing about?

A. You really don't want to know.

Q. I really do want to know.

A. All right but don't say I didn't warn you...

PFX is a horrible, evil, broken predecessor to PKCS#12. It was invented by Microsoft who never really implemented it. Netscape Communicator 4.03 and earlier used it because PKCS#12 didn't exist at the time. For compatibility reasons Netscape 4.04 and later and all versions of MSIE support PFX on import only. This table summarizes the situation.
 

Software PKCS#12 import PKCS#12 export PFX Import PFX export
Netscape 4.03 and earlier No No Yes Yes
Netscape 4.04 and later Yes Yes Yes No
MSIE 4.0 and later Yes Yes Yes No

From this it should be apparent that you only ever need PFX for Netscape 4.03 and earlier. I wrote a PFX implementation a while ago that has to be just as broken otherwise it wouldn't work. If you really need PFX then you can  get version 0.1.2 of my implementation here. Don't be surprised if it blows up, eats your cat or leaves stubborn stains all over your filesystem.

I get the occasional query about this. The situation is confused by the fact that Netscape always uses the extension .p12 and describes the files as "PKCS#12": nevertheless what it called "PKCS#12" in 4.03 and earlier is actually PFX. MSIE on the other hand uses .pfx as the default extension, even though the file is actually PKCS#12. Microsoft (and several others) are currently using the term "PFX" interchangably with PKCS#12 in some documentation just to add to the confusion. The PKCS#12 document even calls its outer ASN1 structure "PFX". Now read this paragraph again and if it makes sense then I haven't explained it properly.

If anyone actually knows different and some international versions behave differently let me know. I don't mean just guessing "it ends in .p12 so it must be a PKCS#12 file" or "it ends in .pfx so it must be a PFX file".

Q. What about adding PFX support to the PKCS#12 patch, or a converter program between the two formats?

A. From the above question you may gather that I don't like PFX. A PFX to PKCS#12 converter would be of minimal use because (from the table above) MSIE and Netscape versions that support PKCS#12 also support PFX import. A PKCS#12 to PFX converter would be of minor use if for example you wanted to export a PKCS#12 file from MSIE and import it into Netscape 4.03 or earlier, but I would suggest you upgrade to Netscape 4.04 or later.

If someone wants to pay me to write a converter then I'd consider it. Otherwise looking over the PFX stuff again is too horrible to contemplate. If after all this you really think you need a converter then mail me.

Q. PFX 0.1.1 doesn't compile under 0.9.0.

A. The bug workarounds I did don't work any more because the bugs no longer exist to workaround :-) Version 0.1.2 of PFX fixes the problem (see above). I only had a quick look at the PFX code and I still feel ill.

Q. What about OpenSSL versions of your PFX code?

A. There isn't any realy point. PFX is now effectively obsolete. The standards used can no longer be downloaded and the key generation algorithms were never publically documented anyway.

5. Technical queries.

Q. I want to create and parse PKCS#12 files, how can I do this?

A. Before version 0.54 you needed to manually parse the PKCS#12 structures and decrypt and convert as necessary or manually build and encrypt them: not a job to be taken lightly. In 0.54 that all changed, there are now two "high level" functions that do all the hard work, PK12_parse() and PKCS12_create(). PKCS12_parse() was originally written for Celo Communications who have kindly allowed them to be included in the main distribution. Check the documentation for more details on how to use these functions.

Q. Where can I get technical documentation on this stuff?

A. If you want info about my implementation see docs/pk12api.doc and docs/pkcs12.doc.
Latest PKCS#12 Draft.

Q. What about test vectors for that horrible key generation algorithm?

A. If you compile the code you can uncomment out the  KEYGEN_DEBUG line in crypto/pkcs12/p12_key.c and it will print out info as it goes along. Alternatively here are some sample test vectors.

Q. What encryption is used in the files?

A. Depends on which files you mean. PKCS#12 supports the following encryption algorithms.

In addition it is suggested that PKCS#5 modes are possible as well. This would also permit the following. However none of the implementations currently support these.

I've decided to clarify the supported encryption of various implementations with a table.
 
Software and mode. Certificate encryption Private key encryption
MSIE4 (domestic and export versions) PKCS#12 export. 40 bit RC2. 40 bit RC2
MSIE4, 5(domestic and export versions) PKCS#12 import. All. All.
MSIE5  PKCS#12 export. 40 bit RC2 3 key triple DES with SHA1 (168 bits)
Netscape Communicator (domestic and export versions) PKCS#12 export 40 bit RC2. 3 key triple DES with SHA1 (168 bits)
Netscape Communicator (export version) PKCS#12 import. 40 bit ciphers only. All.
Netscape Comminicator (domestic or fortified version) PKCS#12 import. All. All.
OpenSSL PKCS#12 code. All. All.

If you want to see for yourself what is used try the info option to pkcs12.

By default I use the strongest encryption supported by all implementations in my pkcs12 sample application: 3DES for private keys and RC2-40 for certificates. The descert option allows certificates to be encrypted with 3DES as well.

If you use the API (or edit pkcs12.c) you can use whatever encryption you want.

It should be noted that superencryption (that is placing one encrypted structure within another) .may not work with either browser.

As for the OpenSSL output files, the encryption is whatever you set it to (default triple DES).

Q. What's the MAC it keeps saying is OK?

A. This is an integrity check. When used with the correct password it can be used to verify that the file has not been corrupted.
My pkcs12 application (and NS/MSIE) currently uses the same password for integrity (MAC) and privacy (encryption) by default. If you use the twopass option you can set and input separate passwords: such files cannot be imported into current versions of MSIE or NS.

Q. What's this I hear about iteration counts?

A. The algorithm used to generate keys from passwords and the MAC has an optional iteration count. This determines how many times part of the algorithm is repeated. It's a way of slowing down the key derivation process to make it harder to make dictionary attacks on the password. The -info option now prints information about iteration counts.
Q. What iteration counts are used?

A. By default I set the encryption iteration count to 1000 and the MAC count to 1. If you use the maciter option the MAC iteration count is also set to 1000 but the file cannot be imported into MSIE4 (but it can be imported into MSIE5). If you use the noiter option the iteration count is set to 1: since this makes dictionary attacks on the password easier this is not recommended.

The PKCS#12 files output by both MS and MSIE4 use 1 for all iteration counts. You can see this yourself with the info option. MSIE5 uses 2000 for the encryption iteration count. If you have the 'enable strong protection' option checked then it uses 2000 for the MAC count otherwise it uses 1 (for compatability with earlier versions of MSIE).

NS will happily import files with MAC and encryption iteration counts. MSIE4 will only handle encryption iteration counts.
This makes MSIE4 more vulnerable because whatever you set the encryption iteration count to you can always make dictionary attacks on the MAC. Even if you pick a good password you are stuck with its weak RC2-40 encryption. For this reason alone you should consider upgrading to MSIE5.

Q. I'm paranoid. I need a bigger iteration count.

A. Have a look for the _ITER_ definition near the start of pkcs12.c, set it to whatever you like and recompile. Setting this to a huge value is a bad idea because it can adversely slow down the handling of files.

Q. How do I create more complex PKCS#12 files?

You can create PKCS#12 files of arbitrary complexity using the API.

Q. What are the "friendly name" and "local key id" referred to in the output?

A. The "friendly name" is just a user friendly way of referring to a user certificate, it is also the name Netscape puts in its list box when you import. E.g. "My certificate". It is set with the -name parameter to pkcs12. "local key id" is just a string to allow keys and certificates to be matched (same id means matched).

Q. What values are used for these attributes?

A. In my implementation the friendly name is set to the value passed with the -name parameter. The key id is set to the SHA-1 hash of the certificate. Before version 0.53 it used 00 00 00 01 .

NS uses the name in the list box for the friendly name and the key id is the SHA-1 hash of the certificate.

MSIE uses the key container name (a weird bunch of digits which looks suspiciously like a GUID) for the friendly name and 00 00 00 01 for the key id.

Q. Can PKCS#12 be used for non RSA private keys, for example DSA and DH keys?

A. Yes it can. PKCS#12 uses PKCS#8 for storing private keys but PKCS#8 itself only gives information about RSA. PKCS#11 however extends PKCS#8 and provides a standard for storing DSA and DH private keys using PKCS#8. Netscape follows the PKCS#11 extension to PKCS#8 for DSA private keys. For more information see the PKCS#11 specification.

Q. What do the 40 bit and 128 bit RC2 modes mean, that is what is their key length and number of bits? My key and IV generation seems fine but I have problems decoding 40 bit RC2 encrypted data, whats wrong?

A. The RC2 algorithm takes a key, a key length and a number of bits parameter. They number of bits paramater is also sometimes called the effective key length. What PKCS#12 refers to as 40 bit RC2 is a keylength of 5 bytes and 40 for the number of bits. If you use any different parameters then you will be unable to decrypt the data.

Q. What is this special attribute added to PKCS#12 files to make MS software import keys as signature only?

A. When I closely analysed MS PKCS#12 files used for signing only and key exchange I noticed that the PKCS#8 PrivateKeyInfo structure contained a keyUsage attribute. The object identifier is the same as the keyUsage certificate extensions and the associcated parameter is a BITSTRING. A signature key has the digitalsignature bit set and an exchange key has the dataEncipherment bit set. This corresponds to bits 0 and 3 or the values 0x80 and 0x10 respectively.

Q. What has changed in MSIE5?

A. MSIE5 seems to have fixed many of the problems associated with private key security in MSIE4. In particular:

For all these reasons upgrading to MSIE5 is strongly advisable.

6. DSA keys.

Q. What's this about DSA keys?

A. This version supports certificates with DSA keys. These can now be imported/exported to/from Netscape. MSIE and Outlook Express appear to import them OK but don't use them properly. If you know better let me know.

Q. I've been testing some DSA stuff before but it doesn't seem to work after applying your patch.

A. This is because the values of the DSA oids have been changed to match those used by NS. The values used are those in PKIX and PKCS#11 and seem to be the most commonly used now. Version 0.9.0 of SSLeay and OpenSSL allow both values to be recognized.

Q. I want to play with DSA keys and Netscape. How do I get a DSA key into Netscape?

A. This is what I did.

1. If you are using OpenSSL then skip to step 2. Otherwise you need to add DSA support to the "ca" program. This is can be added by including the line:

        if (pkey->type == EVP_PKEY_DSA) dgst=EVP_dss1();

just before the lines:

#endif

        if (!X509_sign(ret,pkey,dgst))
                goto err;

these are at line 1530 (before the #endif line) in SSLeay 0.8.1 or line 1668 in 0.9.0 .
If you want DSA CRL support then you should also add the three lines:

#ifndef NO_DSA
                if (pkey->type == EVP_PKEY_DSA) dgst=EVP_dss1();
#endif

just before the line:

                if (!X509_CRL_sign(crl,pkey,dgst)) goto err;

this is at about line 1000 in SSLeay 0.9.0.
2. You need some DSA parameters. You can either use the dsa512.pem and dsa1024.pem parameters in the apps directory or create your own with e.g. dsaparam 512 -out dsa512.pem.
3. Create a dsa CA certificate with: req -x509 -newkey dsa:dsa512.pem -out dsaca.pem
4. Fix up the dsa CA certificate with ca-fix. E.g.
ca-fix -caset -in dsaca.pem -out dsanew.pem -inkey privkey.pem
The old version of ca-fix didn't support DSA keys. Download the new version if necessary.
5. Create a new DSA CA with CA.sh -newca . Enter dsanew.pem when prompted for the certificate name. Copy the private key across with: cp privkey.pem demoCA/private/cakey.pem and the CA certificate with
cp dsanew.pem demoCA/cacert.pem
6. Things now proceed fairly normally. Create a request with req -newkey dsa:dsa512.pem -out newreq.pem
7. Sign the request with CA.sh -signreq (be sure that nsCertType is set to 0xa0 or 0xb0 in openssl.cnf or ssleay.cnf).
8. Create a PKCS#12 file with:
pkcs12 -export -name "DSATEST" -in newcert.pem -inkey privkey.pem -certfile demoCA/cacert.pem -out dsa.p12
9. Import into Netscape. Set to trust new DSA CA and have fun.

Q. Why can't I send encrypted mail with the DSA key?

A. You can't. DSA keys are signature only.

Q. What about getting DSA keys into Netscape using the <KEYGEN> tag via a web server?

A. Yes you can do this. This is left as an exercise to the reader. The info you need is here.

Q. Why would I want to use DSA keys?

A. DSA keys can be used without having to purchase expensive software in the US (unlike RSA keys due to the RSA patent) and there are no export restrictions on DSA key generation (Netscape export version will generate 1024 bit DSA keys but restrictions only allow 512 bit RSA keys to be generated). This is presumably due to the "sign only" nature of DSA keys: the various security organizations are currently only interested in reading encrypted mail and not forging signatures.

7. Future Development.

Q. When will the next version of the program be available?

A. If I notice something needs fixing or soon after the next version of OpenSSL

Q. What is planned for the next version?

A. All thats currently planned is to tidy up and improve the integration with OpenSSL.

Q. What about support for the public key modes?

A. The public key privacy and integrity modes are an alternative way of encrypting the data, very similar to those used in PKCS#7 and S/MIME.  They can be safely transported over insecure channels (e.g. email/internet) and rely on public key encryption as opposed to password based encryption.

Since no one seems to use these modes and no one seems to want them either I've shelved plans to add support.

Please send any comments to my email address on the contact page.

Back to Index