X-Git-Url: https://git.openssl.org/gitweb/?p=openssl.git;a=blobdiff_plain;f=doc%2Fapps%2Fpkcs12.pod;h=7d84146293d26e50780e3e77a73e84acbd962996;hp=14982096c102a3ef4c70166c9719c6eca256c6a6;hb=49131a7d942d85bc3a8d649e23ff14f0da18ee4c;hpb=dd46d58f65bd3a342bbcd8586680942be643fc7d

diff --git a/doc/apps/pkcs12.pod b/doc/apps/pkcs12.pod
index 14982096c1..7d84146293 100644
--- a/doc/apps/pkcs12.pod
+++ b/doc/apps/pkcs12.pod
@@ -35,8 +35,10 @@ B<openssl> B<pkcs12>
 [B<-keypbe>]
 [B<-keyex>]
 [B<-keysig>]
-[B<-password password>]
-[B<-envpass var>]
+[B<-password arg>]
+[B<-passin arg>]
+[B<-passout arg>]
+[B<-rand file(s)>]
 
 =head1 DESCRIPTION
 
@@ -64,14 +66,17 @@ by default.
 The filename to write certificates and private keys to, standard output by default.
 They are all written in PEM format.
 
-=item B<-pass password>
+=item B<-pass arg>, B<-passin arg>
 
-the PKCS#12 file password. Since certain utilities like "ps" make the command line
-visible this option should be used with caution.
+the PKCS#12 file (i.e. input file) password source. For more information about the
+format of B<arg> see the B<PASS PHRASE ARGUMENTS> section in
+L<openssl(1)|openssl(1)>.
 
-=item B<-envpass var>
+=item B<-passout arg>
 
-read the PKCS#12 file password from the environment variable B<var>.
+pass phrase source to encrypt any outputed private keys with. For more information
+about the format of B<arg> see the B<PASS PHRASE ARGUMENTS> section in
+L<openssl(1)|openssl(1)>.
 
 =item B<-noout>
 
@@ -169,14 +174,17 @@ used multiple times to specify names for all certificates in the order they
 appear. Netscape ignores friendly names on other certificates whereas MSIE
 displays them.
 
-=item B<-pass password>
+=item B<-pass arg>, B<-passout arg>
 
-the PKCS#12 file password. Since certain utilities like "ps" make the command line
-visible this option should be used with caution.
+the PKCS#12 file (i.e. output file) password source. For more information about
+the format of B<arg> see the B<PASS PHRASE ARGUMENTS> section in
+L<openssl(1)|openssl(1)>.
 
-=item B<-envpass var>
+=item B<-passin password>
 
-read the PKCS#12 file password from the environment variable B<var>.
+pass phrase source to decrypt any input private keys with. For more information
+about the format of B<arg> see the B<PASS PHRASE ARGUMENTS> section in
+L<openssl(1)|openssl(1)>.
 
 =item B<-chain>
 
@@ -231,6 +239,14 @@ option.
 This option is included for compatibility with previous versions, it used
 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, 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
 
 =head1 NOTES
@@ -239,6 +255,17 @@ Although there are a large number of options most of them are very rarely
 used. For PKCS#12 file parsing only B<-in> and B<-out> need to be used
 for PKCS#12 file creation B<-export> and B<-name> are also used.
 
+If none of the B<-clcerts>, B<-cacerts> or B<-nocerts> options are present
+then all certificates will be output in the order they appear in the input
+PKCS#12 files. There is no guarantee that the first certificate present is
+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
+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.
+
 The B<-keypbe> and B<-certpbe> algorithms allow the precise encryption
 algorithms for private keys and certificates to be specified. Normally
 the defaults are fine but occasionally software can't handle triple DES
@@ -277,10 +304,27 @@ Include some extra certificates:
 
 Some would argue that the PKCS#12 standard is one big bug :-)
 
-Need password options for the PEM files: this will probably be fixed before
-release.
+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
 
-pkcs8(1)
+L<pkcs8(1)|pkcs8(1)>