diff options
Diffstat (limited to 'secure/usr.bin/openssl/man/pkcs12.1')
| -rw-r--r-- | secure/usr.bin/openssl/man/pkcs12.1 | 150 |
1 files changed, 82 insertions, 68 deletions
diff --git a/secure/usr.bin/openssl/man/pkcs12.1 b/secure/usr.bin/openssl/man/pkcs12.1 index d6b6851df98a..34d4f5559866 100644 --- a/secure/usr.bin/openssl/man/pkcs12.1 +++ b/secure/usr.bin/openssl/man/pkcs12.1 @@ -129,20 +129,20 @@ .\" ======================================================================== .\" .IX Title "PKCS12 1" -.TH PKCS12 1 "2018-08-14" "1.0.2p" "OpenSSL" +.TH PKCS12 1 "2018-09-11" "1.1.1" "OpenSSL" .\" For nroff, turn off justification. Always turn off hyphenation; it makes .\" way too many mistakes in technical documents. .if n .ad l .nh .SH "NAME" -openssl\-pkcs12, -pkcs12 \- PKCS#12 file utility +openssl\-pkcs12, pkcs12 \- PKCS#12 file utility .SH "SYNOPSIS" .IX Header "SYNOPSIS" \&\fBopenssl\fR \fBpkcs12\fR +[\fB\-help\fR] [\fB\-export\fR] [\fB\-chain\fR] -[\fB\-inkey filename\fR] +[\fB\-inkey file_or_id\fR] [\fB\-certfile filename\fR] [\fB\-name name\fR] [\fB\-caname name\fR] @@ -155,7 +155,7 @@ pkcs12 \- PKCS#12 file utility [\fB\-cacerts\fR] [\fB\-nokeys\fR] [\fB\-info\fR] -[\fB\-des | \-des3 | \-idea | \-aes128 | \-aes192 | \-aes256 | \-camellia128 | \-camellia192 | \-camellia256 | \-nodes\fR] +[\fB\-des | \-des3 | \-idea | \-aes128 | \-aes192 | \-aes256 | \-aria128 | \-aria192 | \-aria256 | \-camellia128 | \-camellia192 | \-camellia256 | \-nodes\fR] [\fB\-noiter\fR] [\fB\-maciter | \-nomaciter | \-nomac\fR] [\fB\-twopass\fR] @@ -168,22 +168,28 @@ pkcs12 \- PKCS#12 file utility [\fB\-password arg\fR] [\fB\-passin arg\fR] [\fB\-passout arg\fR] -[\fB\-rand file(s)\fR] +[\fB\-rand file...\fR] +[\fB\-writerand file\fR] [\fB\-CAfile file\fR] [\fB\-CApath dir\fR] +[\fB\-no\-CAfile\fR] +[\fB\-no\-CApath\fR] [\fB\-CSP name\fR] .SH "DESCRIPTION" .IX Header "DESCRIPTION" The \fBpkcs12\fR command allows PKCS#12 files (sometimes referred to as \&\s-1PFX\s0 files) to be created and parsed. PKCS#12 files are used by several programs including Netscape, \s-1MSIE\s0 and \s-1MS\s0 Outlook. -.SH "COMMAND OPTIONS" -.IX Header "COMMAND OPTIONS" +.SH "OPTIONS" +.IX Header "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 file can be created by using the \fB\-export\fR option (see below). .SH "PARSING OPTIONS" .IX Header "PARSING OPTIONS" +.IP "\fB\-help\fR" 4 +.IX Item "-help" +Print out a usage message. .IP "\fB\-in filename\fR" 4 .IX Item "-in filename" This specifies filename of the PKCS#12 file to be parsed. Standard input is used @@ -194,12 +200,12 @@ The filename to write certificates and private keys to, standard output by default. They are all written in \s-1PEM\s0 format. .IP "\fB\-passin arg\fR" 4 .IX Item "-passin arg" -the PKCS#12 file (i.e. input file) password source. For more information about +The PKCS#12 file (i.e. input file) password source. For more information about the format of \fBarg\fR see the \fB\s-1PASS PHRASE ARGUMENTS\s0\fR section in \&\fIopenssl\fR\|(1). .IP "\fB\-passout arg\fR" 4 .IX Item "-passout arg" -pass phrase source to encrypt any outputted private keys with. For more +Pass phrase source to encrypt any outputted private keys with. For more information about the format of \fBarg\fR see the \fB\s-1PASS PHRASE ARGUMENTS\s0\fR section in \fIopenssl\fR\|(1). .IP "\fB\-password arg\fR" 4 @@ -208,48 +214,51 @@ With \-export, \-password is equivalent to \-passout. Otherwise, \-password is equivalent to \-passin. .IP "\fB\-noout\fR" 4 .IX Item "-noout" -this option inhibits output of the keys and certificates to the output file +This option inhibits output of the keys and certificates to the output file version of the PKCS#12 file. .IP "\fB\-clcerts\fR" 4 .IX Item "-clcerts" -only output client certificates (not \s-1CA\s0 certificates). +Only output client certificates (not \s-1CA\s0 certificates). .IP "\fB\-cacerts\fR" 4 .IX Item "-cacerts" -only output \s-1CA\s0 certificates (not client certificates). +Only output \s-1CA\s0 certificates (not client certificates). .IP "\fB\-nocerts\fR" 4 .IX Item "-nocerts" -no certificates at all will be output. +No certificates at all will be output. .IP "\fB\-nokeys\fR" 4 .IX Item "-nokeys" -no private keys will be output. +No private keys will be output. .IP "\fB\-info\fR" 4 .IX Item "-info" -output additional information about the PKCS#12 file structure, algorithms used and -iteration counts. +Output additional information about the PKCS#12 file structure, algorithms +used and iteration counts. .IP "\fB\-des\fR" 4 .IX Item "-des" -use \s-1DES\s0 to encrypt private keys before outputting. +Use \s-1DES\s0 to encrypt private keys before outputting. .IP "\fB\-des3\fR" 4 .IX Item "-des3" -use triple \s-1DES\s0 to encrypt private keys before outputting, this is the default. +Use triple \s-1DES\s0 to encrypt private keys before outputting, this is the default. .IP "\fB\-idea\fR" 4 .IX Item "-idea" -use \s-1IDEA\s0 to encrypt private keys before outputting. +Use \s-1IDEA\s0 to encrypt private keys before outputting. .IP "\fB\-aes128\fR, \fB\-aes192\fR, \fB\-aes256\fR" 4 .IX Item "-aes128, -aes192, -aes256" -use \s-1AES\s0 to encrypt private keys before outputting. +Use \s-1AES\s0 to encrypt private keys before outputting. +.IP "\fB\-aria128\fR, \fB\-aria192\fR, \fB\-aria256\fR" 4 +.IX Item "-aria128, -aria192, -aria256" +Use \s-1ARIA\s0 to encrypt private keys before outputting. .IP "\fB\-camellia128\fR, \fB\-camellia192\fR, \fB\-camellia256\fR" 4 .IX Item "-camellia128, -camellia192, -camellia256" -use Camellia to encrypt private keys before outputting. +Use Camellia to encrypt private keys before outputting. .IP "\fB\-nodes\fR" 4 .IX Item "-nodes" -don't encrypt the private keys at all. +Don't encrypt the private keys at all. .IP "\fB\-nomacver\fR" 4 .IX Item "-nomacver" -don't attempt to verify the integrity \s-1MAC\s0 before reading the file. +Don't attempt to verify the integrity \s-1MAC\s0 before reading the file. .IP "\fB\-twopass\fR" 4 .IX Item "-twopass" -prompt for separate integrity and encryption passwords: most software +Prompt for separate integrity and encryption passwords: most software always assumes these are the same so this option will render such PKCS#12 files unreadable. .SH "FILE CREATION OPTIONS" @@ -268,10 +277,12 @@ The filename to read certificates and private keys from, standard input by default. They must all be in \s-1PEM\s0 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. -.IP "\fB\-inkey filename\fR" 4 -.IX Item "-inkey filename" -file to read private key from. If not present then a private key must be present +.IP "\fB\-inkey file_or_id\fR" 4 +.IX Item "-inkey file_or_id" +File to read private key from. If not present then a private key must be present in the input file. +If no engine is used, the argument is taken as a file; if an engine is +specified, the argument is given to the engine as a key identifier. .IP "\fB\-name friendlyname\fR" 4 .IX Item "-name friendlyname" This specifies the \*(L"friendly name\*(R" for the certificate and private key. This @@ -287,27 +298,27 @@ appear. Netscape ignores friendly names on other certificates whereas \s-1MSIE\s displays them. .IP "\fB\-pass arg\fR, \fB\-passout arg\fR" 4 .IX Item "-pass arg, -passout arg" -the PKCS#12 file (i.e. output file) password source. For more information about +The PKCS#12 file (i.e. output file) password source. For more information about the format of \fBarg\fR see the \fB\s-1PASS PHRASE ARGUMENTS\s0\fR section in \&\fIopenssl\fR\|(1). .IP "\fB\-passin password\fR" 4 .IX Item "-passin password" -pass phrase source to decrypt any input private keys with. For more information +Pass phrase source to decrypt any input private keys with. For more information about the format of \fBarg\fR see the \fB\s-1PASS PHRASE ARGUMENTS\s0\fR section in \&\fIopenssl\fR\|(1). .IP "\fB\-chain\fR" 4 .IX Item "-chain" -if this option is present then an attempt is made to include the entire +If this option is present then an attempt is made to include the entire certificate chain of the user certificate. The standard \s-1CA\s0 store is used for this search. If the search fails it is considered a fatal error. .IP "\fB\-descert\fR" 4 .IX Item "-descert" -encrypt the certificate using triple \s-1DES,\s0 this may render the PKCS#12 +Encrypt the certificate using triple \s-1DES,\s0 this may render the PKCS#12 file unreadable by some \*(L"export grade\*(R" software. By default the private key is encrypted using triple \s-1DES\s0 and the certificate using 40 bit \s-1RC2.\s0 .IP "\fB\-keypbe alg\fR, \fB\-certpbe alg\fR" 4 .IX Item "-keypbe alg, -certpbe alg" -these options allow the algorithm used to encrypt the private key and +These options allow the algorithm used to encrypt the private key and certificates to be selected. Any PKCS#5 v1.5 or PKCS#12 \s-1PBE\s0 algorithm name can be used (see \fB\s-1NOTES\s0\fR section for more information). If a cipher name (as output by the \fBlist-cipher-algorithms\fR command is specified then it @@ -315,7 +326,7 @@ is used with PKCS#5 v2.0. For interoperability reasons it is advisable to only use PKCS#12 algorithms. .IP "\fB\-keyex|\-keysig\fR" 4 .IX Item "-keyex|-keysig" -specifies that the private key is to be used for key exchange or just signing. +Specifies that the private key is to be used for key exchange or just signing. This option is only interpreted by \s-1MSIE\s0 and similar \s-1MS\s0 software. Normally \&\*(L"export grade\*(R" software will only allow 512 bit \s-1RSA\s0 keys to be used for encryption purposes but arbitrary length keys for signing. The \fB\-keysig\fR @@ -325,10 +336,10 @@ authentication, however due to a bug only \s-1MSIE 5.0\s0 and later support the use of signing only keys for \s-1SSL\s0 client authentication. .IP "\fB\-macalg digest\fR" 4 .IX Item "-macalg digest" -specify the \s-1MAC\s0 digest algorithm. If not included them \s-1SHA1\s0 will be used. +Specify the \s-1MAC\s0 digest algorithm. If not included them \s-1SHA1\s0 will be used. .IP "\fB\-nomaciter\fR, \fB\-noiter\fR" 4 .IX Item "-nomaciter, -noiter" -these options affect the iteration counts on the \s-1MAC\s0 and key algorithms. +These options affect the iteration counts on the \s-1MAC\s0 and key algorithms. Unless you wish to produce files compatible with \s-1MSIE 4.0\s0 you should leave these options alone. .Sp @@ -349,14 +360,18 @@ This option is included for compatibility with previous versions, it used to be needed to use \s-1MAC\s0 iterations counts but they are now used by default. .IP "\fB\-nomac\fR" 4 .IX Item "-nomac" -don't attempt to provide the \s-1MAC\s0 integrity. -.IP "\fB\-rand file(s)\fR" 4 -.IX Item "-rand file(s)" -a file or files containing random data used to seed the random number -generator, or an \s-1EGD\s0 socket (see \fIRAND_egd\fR\|(3)). -Multiple files can be specified separated by a OS-dependent character. +Don't attempt to provide the \s-1MAC\s0 integrity. +.IP "\fB\-rand file...\fR" 4 +.IX Item "-rand file..." +A file or files containing random data used to seed the random number +generator. +Multiple files can be specified separated by an OS-dependent character. The separator is \fB;\fR for MS-Windows, \fB,\fR for OpenVMS, and \fB:\fR for all others. +.IP "[\fB\-writerand file\fR]" 4 +.IX Item "[-writerand file]" +Writes random data to the specified \fIfile\fR upon exit. +This can be used with a subsequent \fB\-rand\fR flag. .IP "\fB\-CAfile file\fR" 4 .IX Item "-CAfile file" \&\s-1CA\s0 storage as a file. @@ -365,9 +380,15 @@ all others. \&\s-1CA\s0 storage as a directory. This directory must be a standard certificate directory: that is a hash of each subject name (using \fBx509 \-hash\fR) should be linked to each certificate. +.IP "\fB\-no\-CAfile\fR" 4 +.IX Item "-no-CAfile" +Do not load the trusted \s-1CA\s0 certificates from the default file location. +.IP "\fB\-no\-CApath\fR" 4 +.IX Item "-no-CApath" +Do not load the trusted \s-1CA\s0 certificates from the default directory location. .IP "\fB\-CSP name\fR" 4 .IX Item "-CSP name" -write \fBname\fR as a Microsoft \s-1CSP\s0 name. +Write \fBname\fR as a Microsoft \s-1CSP\s0 name. .SH "NOTES" .IX Header "NOTES" Although there are a large number of options most of them are very rarely @@ -391,6 +412,16 @@ the defaults are fine but occasionally software can't handle triple \s-1DES\s0 encrypted private keys, then the option \fB\-keypbe \s-1PBE\-SHA1\-RC2\-40\s0\fR can be used to reduce the private key encryption to 40 bit \s-1RC2. A\s0 complete description of all algorithms is contained in the \fBpkcs8\fR manual page. +.PP +Prior 1.1 release passwords containing non-ASCII characters were encoded +in non-compliant manner, which limited interoperability, in first hand +with Windows. But switching to standard-compliant password encoding +poses problem accessing old data protected with broken encoding. For +this reason even legacy encodings is attempted when reading the +data. If you use PKCS#12 files in production application you are advised +to convert the data, because implemented heuristic approach is not +MT-safe, its sole goal is to facilitate the data upgrade with this +utility. .SH "EXAMPLES" .IX Header "EXAMPLES" Parse a PKCS#12 file and output it to a file: @@ -429,31 +460,14 @@ Include some extra certificates: \& openssl pkcs12 \-export \-in file.pem \-out file.p12 \-name "My Certificate" \e \& \-certfile othercerts.pem .Ve -.SH "BUGS" -.IX Header "BUGS" -Some would argue that the PKCS#12 standard is one big bug :\-) -.PP -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 (\s-1MSIE\s0 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. -.PP -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 \fBpkcs12\fR utility will report that the \s-1MAC\s0 is \s-1OK\s0 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 OpenSSL and recreating the PKCS#12 -file from the keys and certificates using a newer version of OpenSSL. For example: -.PP -.Vb 2 -\& old\-openssl \-in bad.p12 \-out keycerts.pem -\& openssl \-in keycerts.pem \-export \-name "My PKCS#12 file" \-out fixed.p12 -.Ve .SH "SEE ALSO" .IX Header "SEE ALSO" \&\fIpkcs8\fR\|(1) +.SH "COPYRIGHT" +.IX Header "COPYRIGHT" +Copyright 2000\-2017 The OpenSSL Project Authors. All Rights Reserved. +.PP +Licensed under the OpenSSL license (the \*(L"License\*(R"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file \s-1LICENSE\s0 in the source distribution or at +<https://www.openssl.org/source/license.html>. |