X-Git-Url: https://git.openssl.org/gitweb/?p=openssl.git;a=blobdiff_plain;f=doc%2Fapps%2Fpkcs12.pod;h=7ec70a22ac995f4c2b0cb370c10d2162ae45def9;hp=6a17b910b66e793c48e3c5241f8ce3a4489bd826;hb=6264c9b2a9e19119f59112f4e47a79c9dc062148;hpb=0cd4498b8f32bb0cb60724c42aa1014f724b2f2c diff --git a/doc/apps/pkcs12.pod b/doc/apps/pkcs12.pod index 6a17b910b6..7ec70a22ac 100644 --- a/doc/apps/pkcs12.pod +++ b/doc/apps/pkcs12.pod @@ -35,12 +35,10 @@ B B [B<-keypbe>] [B<-keyex>] [B<-keysig>] -[B<-password password>] -[B<-envpass var>] -[B<-passin password>] -[B<-envpassin var>] -[B<-passout password>] -[B<-envpassout var>] +[B<-password arg>] +[B<-passin arg>] +[B<-passout arg>] +[B<-rand file(s)>] =head1 DESCRIPTION @@ -51,7 +49,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 @@ -65,31 +63,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 password>, B<-passin password> +=item B<-pass arg>, B<-passin arg> -the PKCS#12 file (i.e. input 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 see the B section in +L. -=item B<-envpass var>, B<-envpassin password> +=item B<-passout arg> -read the PKCS#12 file password from the environment variable B. - -=item B<-passout password> - -pass phrase to encrypt any outputed private keys with. Since certain utilities like -"ps" make the command line visible this option should be used with caution. - -=item B<-envpass var>, B<-envpassin password> - -read the outputed private keys file password from the environment variable B. +pass phrase source to encrypt any outputed private keys with. For more +information about the format of B see the B section +in L. =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> @@ -156,10 +148,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> @@ -168,8 +160,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> @@ -182,23 +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>, B<-passout password> +=item B<-pass arg>, B<-passout arg> -the PKCS#12 file (i.e. output file) password. Since certain utilities like "ps" -make the command line visible this option should be used with caution. - -=item B<-envpass var>, B<-envpassout var> - -read the PKCS#12 file password from the environment variable B. +the PKCS#12 file (i.e. output file) password source. For more information about +the format of B see the B section in +L. =item B<-passin password> -pass phrase to decrypt the input private key with. Since certain utilities like -"ps" make the command line visible this option should be used with caution. - -=item B<-envpassin password> - -read the input private key file password from the environment variable B. +pass phrase source to decrypt any input private keys with. For more information +about the format of B see the B section in +L. =item B<-chain> @@ -215,9 +201,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 section for more information. +certificates to be selected. Any PKCS#5 v1.5 or PKCS#12 PBE algorithm name +can be used (see B section for more information). If a a cipher name +(as output by the B 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> @@ -230,6 +218,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. @@ -253,6 +245,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). +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 @@ -268,7 +268,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. @@ -310,6 +310,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 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