Docs for new utilities.

[openssl.git] / doc / apps / pkcs12.pod

diff --git a/doc/apps/pkcs12.pod b/doc/apps/pkcs12.pod
index 0aa2f8e16df4afa5649f094c8bbfd379a1038bb3..7d84146293d26e50780e3e77a73e84acbd962996 100644 (file)
--- a/doc/apps/pkcs12.pod
+++ b/doc/apps/pkcs12.pod
@@ -242,9 +242,10 @@ to be needed to use MAC iterations counts but they are now used by default.
 =item B<-rand file(s)>
 
 a file or files containing random data used to seed the random number
-generator. Multiple files can be specified separated by a OS-dependent
-character.  For MS-Windows, the separator is B<;>.  For OpenVMS, it's
-B<,>.  For all others, it's B<:>.
+generator, or an EGD socket (see L<RAND_egd(3)|RAND_egd(3)>).
+Multiple files can be specified separated by a OS-dependent character.
+The separator is B<;> for MS-Windows, B<,> for OpenVMS, and B<:> for
+all others.
 
 =back
 
@@ -261,7 +262,7 @@ the one corresponding to the private key. Certain software which requires
 a private key and certificate and assumes the first certificate in the
 file is the one corresponding to the private key: this may not always
 be the case. Using the B<-clcerts> option will solve this problem by only
-outputing the certificate corresponding to the private key. If the CA
+outputting the certificate corresponding to the private key. If the CA
 certificates are required then they can be output to a separate file using
 the B<-nokeys -cacerts> options to just output CA certificates.
 
@@ -303,6 +304,26 @@ Include some extra certificates:
 
 Some would argue that the PKCS#12 standard is one big bug :-)
 
+Versions of OpenSSL before 0.9.6a had a bug in the PKCS#12 key generation
+routines. Under rare circumstances this could produce a PKCS#12 file encrypted
+with an invalid key. As a result some PKCS#12 files which triggered this bug
+from other implementations (MSIE or Netscape) could not be decrypted
+by OpenSSL and similarly OpenSSL could produce PKCS#12 files which could
+not be decrypted by other implementations. The chances of producing such
+a file are relatively small: less than 1 in 256.
+
+A side effect of fixing this bug is that any old invalidly encrypted PKCS#12
+files cannot no longer be parsed by the fixed version. Under such circumstances
+the B<pkcs12> utility will report that the MAC is OK but fail with a decryption
+error when extracting private keys.
+
+This problem can be resolved by extracting the private keys and certificates
+from the PKCS#12 file using an older version of OpenSSL and recreating the PKCS#12
+file from the keys and certificates using a newer version of OpenSSL. For example:
+
+ old-openssl -in bad.p12 -out keycerts.pem
+ openssl -in keycerts.pem -export -name "My PKCS#12 file" -out fixed.p12
+
 =head1 SEE ALSO
 
 L<pkcs8(1)|pkcs8(1)>