version 1.58, 2016/08/22 13:39:52 |
version 1.59, 2016/08/23 18:54:04 |
|
|
valid values include des, des3, and rc2. |
valid values include des, des3, and rc2. |
It is recommended that des3 is used. |
It is recommended that des3 is used. |
.El |
.El |
.\" |
|
.\" PKCS12 |
|
.\" |
|
.Sh PKCS12 |
.Sh PKCS12 |
.nr nS 1 |
.nr nS 1 |
.Nm "openssl pkcs12" |
.Nm "openssl pkcs12" |
.Bk -words |
.Op Fl aes128 | aes192 | aes256 | des | des3 |
.Oo |
|
.Fl aes128 | aes192 | aes256 | |
|
.Fl des | des3 |
|
.Oc |
|
.Op Fl cacerts |
.Op Fl cacerts |
.Op Fl CAfile Ar file |
.Op Fl CAfile Ar file |
.Op Fl caname Ar name |
.Op Fl caname Ar name |
|
|
.Op Fl passin Ar arg |
.Op Fl passin Ar arg |
.Op Fl passout Ar arg |
.Op Fl passout Ar arg |
.Op Fl twopass |
.Op Fl twopass |
.Ek |
|
.nr nS 0 |
.nr nS 0 |
.Pp |
.Pp |
The |
The |
|
|
command allows PKCS#12 files |
command allows PKCS#12 files |
.Pq sometimes referred to as PFX files |
.Pq sometimes referred to as PFX files |
to be created and parsed. |
to be created and parsed. |
PKCS#12 files are used by several programs including Netscape, MSIE |
|
and MS Outlook. |
|
.Pp |
|
There are a lot of options; the meaning of some depends on whether a |
|
PKCS#12 file is being created or parsed. |
|
By default, a PKCS#12 file is parsed; |
By default, a PKCS#12 file is parsed; |
a PKCS#12 file can be created by using the |
a PKCS#12 file can be created by using the |
.Fl export |
.Fl export |
option |
option. |
.Pq see below . |
.Pp |
.Sh PKCS12 PARSING OPTIONS |
The options for parsing a PKCS12 file are as follows: |
.Bl -tag -width "XXXX" |
.Bl -tag -width "XXXX" |
.It Xo |
.It Fl aes128 | aes192 | aes256 | des | des3 |
.Fl aes128 | aes192 | aes256 | |
Encrypt private keys |
.Fl des | des3 |
using AES, DES, or triple DES, respectively. |
.Xc |
|
Use AES, DES, or triple DES, respectively, |
|
to encrypt private keys before outputting. |
|
The default is triple DES. |
The default is triple DES. |
.It Fl cacerts |
.It Fl cacerts |
Only output CA certificates |
Only output CA certificates |
|
|
Only output client certificates |
Only output client certificates |
.Pq not CA certificates . |
.Pq not CA certificates . |
.It Fl in Ar file |
.It Fl in Ar file |
This specifies the |
The input file to read from, |
.Ar file |
or standard input if not specified. |
of the PKCS#12 file to be parsed. |
|
Standard input is used by default. |
|
.It Fl info |
.It Fl info |
Output additional information about the PKCS#12 file structure, |
Output additional information about the PKCS#12 file structure, |
algorithms used, and iteration counts. |
algorithms used, and iteration counts. |
.It Fl nocerts |
.It Fl nocerts |
No certificates at all will be output. |
Do not output certificates. |
.It Fl nodes |
.It Fl nodes |
Don't encrypt the private keys at all. |
Do not encrypt private keys. |
.It Fl nokeys |
.It Fl nokeys |
No private keys will be output. |
Do not output private keys. |
.It Fl nomacver |
.It Fl nomacver |
Don't attempt to verify the integrity MAC before reading the file. |
Do not attempt to verify the integrity MAC before reading the file. |
.It Fl noout |
.It Fl noout |
This option inhibits output of the keys and certificates to the output file |
Do not output the keys and certificates to the output file |
version of the PKCS#12 file. |
version of the PKCS#12 file. |
.It Fl out Ar file |
.It Fl out Ar file |
The |
The output file to write to, |
.Ar file |
or standard output if not specified. |
to write certificates and private keys to, standard output by default. |
|
They are all written in PEM format. |
|
.It Fl passin Ar arg |
.It Fl passin Ar arg |
The key password source. |
The key password source. |
.It Fl passout Ar arg |
.It Fl passout Ar arg |
|
|
always assumes these are the same so this option will render such |
always assumes these are the same so this option will render such |
PKCS#12 files unreadable. |
PKCS#12 files unreadable. |
.El |
.El |
.Sh PKCS12 FILE CREATION OPTIONS |
.Pp |
|
The options for PKCS12 file creation are as follows: |
.Bl -tag -width "XXXX" |
.Bl -tag -width "XXXX" |
.It Fl CAfile Ar file |
.It Fl CAfile Ar file |
CA storage as a file. |
CA storage as a file. |
.It Fl CApath Ar directory |
.It Fl CApath Ar directory |
CA storage as a directory. |
CA storage as a directory. |
This directory must be a standard certificate directory: |
The directory must be a standard certificate directory: |
that is, a hash of each subject name (using |
that is, a hash of each subject name (using |
.Cm x509 -hash ) |
.Nm x509 Fl hash ) |
should be linked to each certificate. |
should be linked to each certificate. |
.It Fl caname Ar name |
.It Fl caname Ar name |
This specifies the |
Specify the |
.Qq friendly name |
.Qq friendly name |
for other certificates. |
for other certificates. |
This option may be used multiple times to specify names for all certificates |
May be used multiple times to specify names for all certificates |
in the order they appear. |
in the order they appear. |
Netscape ignores friendly names on other certificates, |
|
whereas MSIE displays them. |
|
.It Fl certfile Ar file |
.It Fl certfile Ar file |
A file to read additional certificates from. |
A file to read additional certificates from. |
.It Fl certpbe Ar alg , Fl keypbe Ar alg |
.It Fl certpbe Ar alg , Fl keypbe Ar alg |
These options allow the algorithm used to encrypt the private key and |
Specify the algorithm used to encrypt the private key and |
certificates to be selected. |
certificates to be selected. |
Any PKCS#5 v1.5 or PKCS#12 PBE algorithm name can be used (see the |
Any PKCS#5 v1.5 or PKCS#12 PBE algorithm name can be used. |
.Sx PKCS12 NOTES |
|
section for more information). |
|
If a cipher name |
If a cipher name |
(as output by the |
(as output by the |
.Cm list-cipher-algorithms |
.Cm list-cipher-algorithms |
|
|
is used with PKCS#5 v2.0. |
is used with PKCS#5 v2.0. |
For interoperability reasons it is advisable to only use PKCS#12 algorithms. |
For interoperability reasons it is advisable to only use PKCS#12 algorithms. |
.It Fl chain |
.It Fl chain |
If this option is present, an attempt is made to include the entire |
Include the entire certificate chain of the user certificate. |
certificate chain of the user certificate. |
|
The standard CA store is used for this search. |
The standard CA store is used for this search. |
If the search fails, it is considered a fatal error. |
If the search fails, it is considered a fatal error. |
.It Fl CSP Ar name |
.It Fl CSP Ar name |
|
|
By default, the private key is encrypted using triple DES and the |
By default, the private key is encrypted using triple DES and the |
certificate using 40-bit RC2. |
certificate using 40-bit RC2. |
.It Fl export |
.It Fl export |
This option specifies that a PKCS#12 file will be created rather than |
Create a PKCS#12 file (rather than parsing one). |
parsed. |
|
.It Fl in Ar file |
.It Fl in Ar file |
The |
The input file to read from, |
.Ar file |
or standard input if not specified, |
to read certificates and private keys from, standard input by default. |
in PEM format. |
They must all be in PEM format. |
|
The order doesn't matter but one private key and its corresponding |
The order doesn't matter but one private key and its corresponding |
certificate should be present. |
certificate should be present. |
If additional certificates are present, they will also be included |
If additional certificates are present, they will also be included |
in the PKCS#12 file. |
in the PKCS#12 file. |
.It Fl inkey Ar file |
.It Fl inkey Ar file |
File to read private key from. |
File to read a private key from. |
If not present, a private key must be present in the input file. |
If not present, a private key must be present in the input file. |
.It Fl keyex | keysig |
.It Fl keyex | keysig |
Specifies that the private key is to be used for key exchange or just signing. |
Specify whether the private key is to be used for key exchange or just signing. |
This option is only interpreted by MSIE and similar MS software. |
|
Normally, |
Normally, |
.Qq export grade |
.Qq export grade |
software will only allow 512-bit RSA keys to be |
software will only allow 512-bit RSA keys to be |
|
|
option marks the key for signing only. |
option marks the key for signing only. |
Signing only keys can be used for S/MIME signing, authenticode |
Signing only keys can be used for S/MIME signing, authenticode |
.Pq ActiveX control signing |
.Pq ActiveX control signing |
and SSL client authentication; |
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. |
|
.It Fl macalg Ar alg |
.It Fl macalg Ar alg |
Specify the MAC digest algorithm. |
Specify the MAC digest algorithm. |
If not included then SHA1 is used. |
The default is SHA1. |
.It Fl maciter |
.It Fl maciter |
This option is included for compatibility with previous versions; it used |
Included for compatability only: |
to be needed to use MAC iterations counts but they are now used by default. |
it used to be needed to use MAC iterations counts |
|
but they are now used by default. |
.It Fl name Ar name |
.It Fl name Ar name |
This specifies the |
Specify the |
.Qq friendly name |
.Qq friendly name |
for the certificate and private key. |
for the certificate and private key. |
This name is typically displayed in list boxes by software importing the file. |
This name is typically displayed in list boxes by software importing the file. |
.It Fl nomac |
.It Fl nomac |
Don't attempt to provide the MAC integrity. |
Don't attempt to provide the MAC integrity. |
.It Fl nomaciter , noiter |
.It Fl nomaciter , noiter |
These options affect the iteration counts on the MAC and key algorithms. |
Affect the iteration counts on the MAC and key algorithms. |
Unless you wish to produce files compatible with MSIE 4.0, you should leave |
Unless you wish to produce files compatible with MSIE 4.0, you should leave |
these options alone. |
these options alone. |
.Pp |
.Pp |
|
|
.Fl nomaciter |
.Fl nomaciter |
option. |
option. |
.It Fl out Ar file |
.It Fl out Ar file |
This specifies |
The output file to write to, |
.Ar file |
or standard output if not specified. |
to write the PKCS#12 file to. |
|
Standard output is used by default. |
|
.It Fl passin Ar arg |
.It Fl passin Ar arg |
The key password source. |
The key password source. |
.It Fl passout Ar arg |
.It Fl passout Ar arg |
The output file password source. |
The output file password source. |
.El |
.El |
.Sh PKCS12 NOTES |
|
Although there are a large number of options, |
|
most of them are very rarely used. |
|
For PKCS#12 file parsing, only |
|
.Fl in |
|
and |
|
.Fl out |
|
need to be used for PKCS#12 file creation. |
|
.Fl export |
|
and |
|
.Fl name |
|
are also used. |
|
.Pp |
|
If none of the |
|
.Fl clcerts , cacerts , |
|
or |
|
.Fl 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 |
|
.Fl clcerts |
|
option will solve this problem by only outputting the certificate |
|
corresponding to the private key. |
|
If the CA certificates are required, they can be output to a separate |
|
file using the |
|
.Fl nokeys |
|
and |
|
.Fl cacerts |
|
options to just output CA certificates. |
|
.Pp |
|
The |
|
.Fl keypbe |
|
and |
|
.Fl 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 encrypted private keys; |
|
then the option |
|
.Fl keypbe Ar PBE-SHA1-RC2-40 |
|
can be used to reduce the private key encryption to 40-bit RC2. |
|
A complete description of all algorithms is contained in the |
|
.Sx PKCS8 |
|
section above. |
|
.Sh PKCS12 EXAMPLES |
|
Parse a PKCS#12 file and output it to a file: |
|
.Pp |
|
.Dl $ openssl pkcs12 -in file.p12 -out file.pem |
|
.Pp |
|
Output only client certificates to a file: |
|
.Pp |
|
.Dl $ openssl pkcs12 -in file.p12 -clcerts -out file.pem |
|
.Pp |
|
Don't encrypt the private key: |
|
.Pp |
|
.Dl $ openssl pkcs12 -in file.p12 -out file.pem -nodes |
|
.Pp |
|
Print some info about a PKCS#12 file: |
|
.Pp |
|
.Dl $ openssl pkcs12 -in file.p12 -info -noout |
|
.Pp |
|
Create a PKCS#12 file: |
|
.Bd -literal -offset indent |
|
$ openssl pkcs12 -export -in file.pem -out file.p12 \e |
|
-name "My Certificate" |
|
.Ed |
|
.Pp |
|
Include some extra certificates: |
|
.Bd -literal -offset indent |
|
$ openssl pkcs12 -export -in file.pem -out file.p12 \e |
|
-name "My Certificate" -certfile othercerts.pem |
|
.Ed |
|
.Sh PKCS12 BUGS |
|
Some would argue that the PKCS#12 standard is one big bug :\-) |
|
.Pp |
|
Versions of |
|
.Nm 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 |
|
.Pq MSIE or Netscape |
|
could not be decrypted by |
|
.Nm OpenSSL |
|
and similarly |
|
.Nm 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. |
|
.Pp |
|
A side effect of fixing this bug is that any old invalidly encrypted PKCS#12 |
|
files can no longer be parsed by the fixed version. |
|
Under such circumstances the |
|
.Nm pkcs12 |
|
utility will report that the MAC is OK but fail with a decryption |
|
error when extracting private keys. |
|
.Pp |
|
This problem can be resolved by extracting the private keys and certificates |
|
from the PKCS#12 file using an older version of |
|
.Nm OpenSSL |
|
and recreating |
|
the PKCS#12 file from the keys and certificates using a newer version of |
|
.Nm OpenSSL . |
|
For example: |
|
.Bd -literal -offset indent |
|
$ old-openssl -in bad.p12 -out keycerts.pem |
|
$ openssl -in keycerts.pem -export -name "My PKCS#12 file" \e |
|
-out fixed.p12 |
|
.Ed |
|
.\" |
.\" |
.\" PKEY |
.\" PKEY |
.\" |
.\" |