Merge from 1.0.0-stable branch.
[openssl.git] / doc / apps / pkcs12.pod
index 241f9c4..f69a5c5 100644 (file)
@@ -23,22 +23,23 @@ B<openssl> B<pkcs12>
 [B<-cacerts>]
 [B<-nokeys>]
 [B<-info>]
-[B<-des>]
-[B<-des3>]
-[B<-idea>]
-[B<-nodes>]
+[B<-des | -des3 | -idea | -aes128 | -aes192 | -aes256 | -camellia128 | -camellia192 | -camellia256 | -nodes>]
 [B<-noiter>]
-[B<-maciter>]
+[B<-maciter | -nomaciter | -nomac>]
 [B<-twopass>]
 [B<-descert>]
-[B<-certpbe>]
-[B<-keypbe>]
+[B<-certpbe cipher>]
+[B<-keypbe cipher>]
+[B<-macalg digest>]
 [B<-keyex>]
 [B<-keysig>]
 [B<-password arg>]
 [B<-passin arg>]
 [B<-passout arg>]
 [B<-rand file(s)>]
+[B<-CAfile file>]
+[B<-CApath dir>]
+[B<-CSP name>]
 
 =head1 DESCRIPTION
 
@@ -49,7 +50,7 @@ programs including Netscape, MSIE and MS Outlook.
 =head1 COMMAND OPTIONS
 
 There are a lot of options the meaning of some depends of whether a PKCS#12 file
-is being created or parsed. By default a PKCS#12 file is parsed a PKCS#12
+is being created or parsed. By default a PKCS#12 file is parsed. A PKCS#12
 file can be created by using the B<-export> option (see below).
 
 =head1 PARSING OPTIONS
@@ -63,25 +64,25 @@ by default.
 
 =item B<-out filename>
 
-The filename to write certificates and private keys to, standard output by default.
-They are all written in PEM format.
+The filename to write certificates and private keys to, standard output by
+default.  They are all written in PEM format.
 
 =item B<-pass arg>, B<-passin arg>
 
-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
+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<-passout arg>
 
-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)>.
+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>
 
-this option inhibits output of the keys and certificates to the output file version
-of the PKCS#12 file.
+this option inhibits output of the keys and certificates to the output file
+version of the PKCS#12 file.
 
 =item B<-clcerts>
 
@@ -116,6 +117,14 @@ use triple DES to encrypt private keys before outputting, this is the default.
 
 use IDEA to encrypt private keys before outputting.
 
+=item B<-aes128>, B<-aes192>, B<-aes256>
+
+use AES to encrypt private keys before outputting.
+
+=item B<-camellia128>, B<-camellia192>, B<-camellia256>
+
+use Camellia to encrypt private keys before outputting.
+
 =item B<-nodes>
 
 don't encrypt the private keys at all.
@@ -148,10 +157,10 @@ by default.
 
 =item B<-in filename>
 
-The filename to read certificates and private keys from, standard input by default.
-They must all be in PEM format. The order doesn't matter but one private key and
-its corresponding certificate should be present. If additional certificates are
-present they will also be included in the PKCS#12 file.
+The filename to read certificates and private keys from, standard input by
+default.  They must all be in PEM format. The order doesn't matter but one
+private key and its corresponding certificate should be present. If additional
+certificates are present they will also be included in the PKCS#12 file.
 
 =item B<-inkey filename>
 
@@ -160,8 +169,8 @@ in the input file.
 
 =item B<-name friendlyname>
 
-This specifies the "friendly name" for the certificate and private key. This name
-is typically displayed in list boxes by software importing the file.
+This specifies the "friendly name" for the certificate and private key. This
+name is typically displayed in list boxes by software importing the file.
 
 =item B<-certfile filename>
 
@@ -201,9 +210,11 @@ key is encrypted using triple DES and the certificate using 40 bit RC2.
 =item B<-keypbe alg>, B<-certpbe alg>
 
 these options allow the algorithm used to encrypt the private key and
-certificates to be selected. Although any PKCS#5 v1.5 or PKCS#12 algorithms
-can be selected it is advisable only to use PKCS#12 algorithms. See the list
-in the B<NOTES> section for more information.
+certificates to be selected. Any PKCS#5 v1.5 or PKCS#12 PBE algorithm name
+can be used (see B<NOTES> section for more information). If a a cipher name
+(as output by the B<list-cipher-algorithms> command is specified then it
+is used with PKCS#5 v2.0. For interoperability reasons it is advisable to only
+use PKCS#12 algorithms.
 
 =item B<-keyex|-keysig>
 
@@ -216,6 +227,10 @@ S/MIME signing, authenticode (ActiveX control signing)  and SSL client
 authentication, however due to a bug only MSIE 5.0 and later support
 the use of signing only keys for SSL client authentication.
 
+=item B<-macalg digest>
+
+specify the MAC digest algorithm. If not included them SHA1 will be used.
+
 =item B<-nomaciter>, B<-noiter>
 
 these options affect the iteration counts on the MAC and key algorithms.
@@ -239,14 +254,32 @@ 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<-nomac>
+
+don't attempt to provide the MAC integrity.
+
 =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 OpenVSM, and B<:> for
+The separator is B<;> for MS-Windows, B<,> for OpenVMS, and B<:> for
 all others.
 
+=item B<-CAfile file>
+
+CA storage as a file.
+
+=item B<-CApath dir>
+
+CA storage as a directory. This directory must be a standard certificate
+directory: that is a hash of each subject name (using B<x509 -hash>) should be
+linked to each certificate.
+
+=item B<-CSP name>
+
+write B<name> as a Microsoft CSP name.
+
 =back
 
 =head1 NOTES
@@ -262,7 +295,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.
 
@@ -304,6 +337,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)>