1 files changed, 135 insertions, 74 deletions
diff --git a/secure/usr.bin/openssl/man/pkcs8.1 b/secure/usr.bin/openssl/man/pkcs8.1
index 9a74c124ce34..da5edfc5b9ca 100644
--- a/secure/usr.bin/openssl/man/pkcs8.1
+++ b/secure/usr.bin/openssl/man/pkcs8.1
@@ -129,17 +129,17 @@
 .\" ========================================================================
 .\"
 .IX Title "PKCS8 1"
-.TH PKCS8 1 "2018-08-14" "1.0.2p" "OpenSSL"
+.TH PKCS8 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\-pkcs8,
-pkcs8 \- PKCS#8 format private key conversion tool
+openssl\-pkcs8, pkcs8 \- PKCS#8 format private key conversion tool
 .SH "SYNOPSIS"
 .IX Header "SYNOPSIS"
 \&\fBopenssl\fR \fBpkcs8\fR
+[\fB\-help\fR]
 [\fB\-topk8\fR]
 [\fB\-inform PEM|DER\fR]
 [\fB\-outform PEM|DER\fR]
@@ -147,38 +147,47 @@ pkcs8 \- PKCS#8 format private key conversion tool
 [\fB\-passin arg\fR]
 [\fB\-out filename\fR]
 [\fB\-passout arg\fR]
+[\fB\-iter count\fR]
 [\fB\-noiter\fR]
+[\fB\-rand file...\fR]
+[\fB\-writerand file\fR]
 [\fB\-nocrypt\fR]
-[\fB\-nooct\fR]
-[\fB\-embed\fR]
-[\fB\-nsdb\fR]
+[\fB\-traditional\fR]
 [\fB\-v2 alg\fR]
 [\fB\-v2prf alg\fR]
 [\fB\-v1 alg\fR]
 [\fB\-engine id\fR]
+[\fB\-scrypt\fR]
+[\fB\-scrypt_N N\fR]
+[\fB\-scrypt_r r\fR]
+[\fB\-scrypt_p p\fR]
 .SH "DESCRIPTION"
 .IX Header "DESCRIPTION"
 The \fBpkcs8\fR command processes private keys in PKCS#8 format. It can handle
 both unencrypted PKCS#8 PrivateKeyInfo format and EncryptedPrivateKeyInfo
 format with a variety of PKCS#5 (v1.5 and v2.0) and PKCS#12 algorithms.
-.SH "COMMAND OPTIONS"
-.IX Header "COMMAND OPTIONS"
+.SH "OPTIONS"
+.IX Header "OPTIONS"
+.IP "\fB\-help\fR" 4
+.IX Item "-help"
+Print out a usage message.
 .IP "\fB\-topk8\fR" 4
 .IX Item "-topk8"
-Normally a PKCS#8 private key is expected on input and a traditional format
-private key will be written. With the \fB\-topk8\fR option the situation is
-reversed: it reads a traditional format private key and writes a PKCS#8
-format key.
+Normally a PKCS#8 private key is expected on input and a private key will be
+written to the output file. With the \fB\-topk8\fR option the situation is
+reversed: it reads a private key and writes a PKCS#8 format key.
 .IP "\fB\-inform DER|PEM\fR" 4
 .IX Item "-inform DER|PEM"
-This specifies the input format. If a PKCS#8 format key is expected on input
-then either a \fB\s-1DER\s0\fR or \fB\s-1PEM\s0\fR encoded version of a PKCS#8 key will be
-expected. Otherwise the \fB\s-1DER\s0\fR or \fB\s-1PEM\s0\fR format of the traditional format
-private key is used.
+This specifies the input format: see \*(L"\s-1KEY FORMATS\*(R"\s0 for more details. The default
+format is \s-1PEM.\s0
 .IP "\fB\-outform DER|PEM\fR" 4
 .IX Item "-outform DER|PEM"
-This specifies the output format, the options have the same meaning as the 
-\&\fB\-inform\fR option.
+This specifies the output format: see \*(L"\s-1KEY FORMATS\*(R"\s0 for more details. The default
+format is \s-1PEM.\s0
+.IP "\fB\-traditional\fR" 4
+.IX Item "-traditional"
+When this option is present and \fB\-topk8\fR is not a traditional format private
+key is written.
 .IP "\fB\-in filename\fR" 4
 .IX Item "-in filename"
 This specifies the input filename to read a key from or standard input if this
@@ -186,7 +195,7 @@ option is not specified. If the key is encrypted a pass phrase will be
 prompted for.
 .IP "\fB\-passin arg\fR" 4
 .IX Item "-passin arg"
-the input file password source. For more information about the format of \fBarg\fR
+The 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\-out filename\fR" 4
 .IX Item "-out filename"
@@ -196,8 +205,13 @@ prompted for. The output filename should \fBnot\fR be the same as the input
 filename.
 .IP "\fB\-passout arg\fR" 4
 .IX Item "-passout arg"
-the output file password source. For more information about the format of \fBarg\fR
+The 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\-iter count\fR" 4
+.IX Item "-iter count"
+When creating new PKCS#8 containers, use a given number of iterations on
+the password in deriving the encryption key for the PKCS#8 output.
+High values increase the time required to brute-force a PKCS#8 container.
 .IP "\fB\-nocrypt\fR" 4
 .IX Item "-nocrypt"
 PKCS#8 keys generated or input are normally PKCS#8 EncryptedPrivateKeyInfo
@@ -206,53 +220,81 @@ this option an unencrypted PrivateKeyInfo structure is expected or output.
 This option does not encrypt private keys at all and should only be used
 when absolutely necessary. Certain software such as some versions of Java
 code signing software used unencrypted private keys.
-.IP "\fB\-nooct\fR" 4
-.IX Item "-nooct"
-This option generates \s-1RSA\s0 private keys in a broken format that some software
-uses. Specifically the private key should be enclosed in a \s-1OCTET STRING\s0
-but some software just includes the structure itself without the
-surrounding \s-1OCTET STRING.\s0
-.IP "\fB\-embed\fR" 4
-.IX Item "-embed"
-This option generates \s-1DSA\s0 keys in a broken format. The \s-1DSA\s0 parameters are
-embedded inside the PrivateKey structure. In this form the \s-1OCTET STRING\s0
-contains an \s-1ASN1 SEQUENCE\s0 consisting of two structures: a \s-1SEQUENCE\s0 containing
-the parameters and an \s-1ASN1 INTEGER\s0 containing the private key.
-.IP "\fB\-nsdb\fR" 4
-.IX Item "-nsdb"
-This option generates \s-1DSA\s0 keys in a broken format compatible with Netscape
-private key databases. The PrivateKey contains a \s-1SEQUENCE\s0 consisting of
-the public and private keys respectively.
+.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\-v2 alg\fR" 4
 .IX Item "-v2 alg"
-This option enables the use of PKCS#5 v2.0 algorithms. Normally PKCS#8
-private keys are encrypted with the password based encryption algorithm
-called \fBpbeWithMD5AndDES\-CBC\fR this uses 56 bit \s-1DES\s0 encryption but it
-was the strongest encryption algorithm supported in PKCS#5 v1.5. Using 
-the \fB\-v2\fR option PKCS#5 v2.0 algorithms are used which can use any
-encryption algorithm such as 168 bit triple \s-1DES\s0 or 128 bit \s-1RC2\s0 however
-not many implementations support PKCS#5 v2.0 yet. If you are just using
-private keys with OpenSSL then this doesn't matter.
+This option sets the PKCS#5 v2.0 algorithm.
 .Sp
 The \fBalg\fR argument is the encryption algorithm to use, valid values include
-\&\fBdes\fR, \fBdes3\fR and \fBrc2\fR. It is recommended that \fBdes3\fR is used.
+\&\fBaes128\fR, \fBaes256\fR and \fBdes3\fR. If this option isn't specified then \fBaes256\fR
+is used.
 .IP "\fB\-v2prf alg\fR" 4
 .IX Item "-v2prf alg"
 This option sets the \s-1PRF\s0 algorithm to use with PKCS#5 v2.0. A typical value
-values would be \fBhmacWithSHA256\fR. If this option isn't set then the default
-for the cipher is used or \fBhmacWithSHA1\fR if there is no default.
+value would be \fBhmacWithSHA256\fR. If this option isn't set then the default
+for the cipher is used or \fBhmacWithSHA256\fR if there is no default.
+.Sp
+Some implementations may not support custom \s-1PRF\s0 algorithms and may require
+the \fBhmacWithSHA1\fR option to work.
 .IP "\fB\-v1 alg\fR" 4
 .IX Item "-v1 alg"
-This option specifies a PKCS#5 v1.5 or PKCS#12 algorithm to use. A complete
-list of possible algorithms is included below.
+This option indicates a PKCS#5 v1.5 or PKCS#12 algorithm should be used.  Some
+older implementations may not support PKCS#5 v2.0 and may require this option.
+If not specified PKCS#5 v2.0 form is used.
 .IP "\fB\-engine id\fR" 4
 .IX Item "-engine id"
-specifying an engine (by its unique \fBid\fR string) will cause \fBpkcs8\fR
+Specifying an engine (by its unique \fBid\fR string) will cause \fBpkcs8\fR
 to attempt to obtain a functional reference to the specified engine,
 thus initialising it if needed. The engine will then be set as the default
 for all available algorithms.
+.IP "\fB\-scrypt\fR" 4
+.IX Item "-scrypt"
+Uses the \fBscrypt\fR algorithm for private key encryption using default
+parameters: currently N=16384, r=8 and p=1 and \s-1AES\s0 in \s-1CBC\s0 mode with a 256 bit
+key. These parameters can be modified using the \fB\-scrypt_N\fR, \fB\-scrypt_r\fR,
+\&\fB\-scrypt_p\fR and \fB\-v2\fR options.
+.IP "\fB\-scrypt_N N\fR \fB\-scrypt_r r\fR \fB\-scrypt_p p\fR" 4
+.IX Item "-scrypt_N N -scrypt_r r -scrypt_p p"
+Sets the scrypt \fBN\fR, \fBr\fR or \fBp\fR parameters.
+.SH "KEY FORMATS"
+.IX Header "KEY FORMATS"
+Various different formats are used by the pkcs8 utility. These are detailed
+below.
+.PP
+If a key is being converted from PKCS#8 form (i.e. the \fB\-topk8\fR option is
+not used) then the input file must be in PKCS#8 format. An encrypted
+key is expected unless \fB\-nocrypt\fR is included.
+.PP
+If \fB\-topk8\fR is not used and \fB\s-1PEM\s0\fR mode is set the output file will be an
+unencrypted private key in PKCS#8 format. If the \fB\-traditional\fR option is
+used then a traditional format private key is written instead.
+.PP
+If \fB\-topk8\fR is not used and \fB\s-1DER\s0\fR mode is set the output file will be an
+unencrypted private key in traditional \s-1DER\s0 format.
+.PP
+If \fB\-topk8\fR is used then any supported private key can be used for the input
+file in a format specified by \fB\-inform\fR. The output file will be encrypted
+PKCS#8 format using the specified encryption parameters unless \fB\-nocrypt\fR
+is included.
 .SH "NOTES"
 .IX Header "NOTES"
+By default, when converting a key to PKCS#8 format, PKCS#5 v2.0 using 256 bit
+\&\s-1AES\s0 with \s-1HMAC\s0 and \s-1SHA256\s0 is used.
+.PP
+Some older implementations do not support PKCS#5 v2.0 format and require
+the older PKCS#5 v1.5 form instead, possibly also requiring insecure weak
+encryption algorithms such as 56 bit \s-1DES.\s0
+.PP
 The encrypted form of a \s-1PEM\s0 encode PKCS#8 files uses the following
 headers and footers:
 .PP
@@ -273,13 +315,6 @@ counts are more secure that those encrypted using the traditional
 SSLeay compatible formats. So if additional security is considered
 important the keys should be converted.
 .PP
-The default encryption is only 56 bits because this is the encryption
-that most current implementations of PKCS#8 will support.
-.PP
-Some software may use PKCS#12 password based encryption algorithms
-with PKCS#8 format private keys: these are handled automatically
-but there is no option to produce them.
-.PP
 It is possible to write out \s-1DER\s0 encoded encrypted private keys in
 PKCS#8 format because the encryption details are included at an \s-1ASN1\s0
 level whereas the traditional format includes them at a \s-1PEM\s0 level.
@@ -292,37 +327,49 @@ below.
 .IX Item "PBE-MD2-DES PBE-MD5-DES"
 These algorithms were included in the original PKCS#5 v1.5 specification.
 They only offer 56 bits of protection since they both use \s-1DES.\s0
-.IP "\fB\s-1PBE\-SHA1\-RC2\-64 PBE\-MD2\-RC2\-64 PBE\-MD5\-RC2\-64 PBE\-SHA1\-DES\s0\fR" 4
-.IX Item "PBE-SHA1-RC2-64 PBE-MD2-RC2-64 PBE-MD5-RC2-64 PBE-SHA1-DES"
+.IP "\fB\s-1PBE\-SHA1\-RC2\-64\s0\fR, \fB\s-1PBE\-MD2\-RC2\-64\s0\fR, \fB\s-1PBE\-MD5\-RC2\-64\s0\fR, \fB\s-1PBE\-SHA1\-DES\s0\fR" 4
+.IX Item "PBE-SHA1-RC2-64, PBE-MD2-RC2-64, PBE-MD5-RC2-64, PBE-SHA1-DES"
 These algorithms are not mentioned in the original PKCS#5 v1.5 specification
 but they use the same key derivation algorithm and are supported by some
 software. They are mentioned in PKCS#5 v2.0. They use either 64 bit \s-1RC2\s0 or
 56 bit \s-1DES.\s0
-.IP "\fB\s-1PBE\-SHA1\-RC4\-128 PBE\-SHA1\-RC4\-40 PBE\-SHA1\-3DES PBE\-SHA1\-2DES PBE\-SHA1\-RC2\-128 PBE\-SHA1\-RC2\-40\s0\fR" 4
-.IX Item "PBE-SHA1-RC4-128 PBE-SHA1-RC4-40 PBE-SHA1-3DES PBE-SHA1-2DES PBE-SHA1-RC2-128 PBE-SHA1-RC2-40"
+.IP "\fB\s-1PBE\-SHA1\-RC4\-128\s0\fR, \fB\s-1PBE\-SHA1\-RC4\-40\s0\fR, \fB\s-1PBE\-SHA1\-3DES\s0\fR, \fB\s-1PBE\-SHA1\-2DES\s0\fR, \fB\s-1PBE\-SHA1\-RC2\-128\s0\fR, \fB\s-1PBE\-SHA1\-RC2\-40\s0\fR" 4
+.IX Item "PBE-SHA1-RC4-128, PBE-SHA1-RC4-40, PBE-SHA1-3DES, PBE-SHA1-2DES, PBE-SHA1-RC2-128, PBE-SHA1-RC2-40"
 These algorithms use the PKCS#12 password based encryption algorithm and
 allow strong encryption algorithms like triple \s-1DES\s0 or 128 bit \s-1RC2\s0 to be used.
 .SH "EXAMPLES"
 .IX Header "EXAMPLES"
-Convert a private from traditional to PKCS#5 v2.0 format using triple
-\&\s-1DES:\s0
+Convert a private key to PKCS#8 format using default parameters (\s-1AES\s0 with
+256 bit key and \fBhmacWithSHA256\fR):
+.PP
+.Vb 1
+\& openssl pkcs8 \-in key.pem \-topk8 \-out enckey.pem
+.Ve
+.PP
+Convert a private key to PKCS#8 unencrypted format:
+.PP
+.Vb 1
+\& openssl pkcs8 \-in key.pem \-topk8 \-nocrypt \-out enckey.pem
+.Ve
+.PP
+Convert a private key to PKCS#5 v2.0 format using triple \s-1DES:\s0
 .PP
 .Vb 1
 \& openssl pkcs8 \-in key.pem \-topk8 \-v2 des3 \-out enckey.pem
 .Ve
 .PP
-Convert a private from traditional to PKCS#5 v2.0 format using \s-1AES\s0 with
-256 bits in \s-1CBC\s0 mode and \fBhmacWithSHA256\fR \s-1PRF:\s0
+Convert a private key to PKCS#5 v2.0 format using \s-1AES\s0 with 256 bits in \s-1CBC\s0
+mode and \fBhmacWithSHA512\fR \s-1PRF:\s0
 .PP
 .Vb 1
-\& openssl pkcs8 \-in key.pem \-topk8 \-v2 aes\-256\-cbc \-v2prf hmacWithSHA256 \-out enckey.pem
+\& openssl pkcs8 \-in key.pem \-topk8 \-v2 aes\-256\-cbc \-v2prf hmacWithSHA512 \-out enckey.pem
 .Ve
 .PP
 Convert a private key to PKCS#8 using a PKCS#5 1.5 compatible algorithm
 (\s-1DES\s0):
 .PP
 .Vb 1
-\& openssl pkcs8 \-in key.pem \-topk8 \-out enckey.pem
+\& openssl pkcs8 \-in key.pem \-topk8 \-v1 PBE\-MD5\-DES \-out enckey.pem
 .Ve
 .PP
 Convert a private key to PKCS#8 using a PKCS#12 compatible algorithm
@@ -338,10 +385,17 @@ Read a \s-1DER\s0 unencrypted PKCS#8 format private key:
 \& openssl pkcs8 \-inform DER \-nocrypt \-in key.der \-out key.pem
 .Ve
 .PP
-Convert a private key from any PKCS#8 format to traditional format:
+Convert a private key from any PKCS#8 encrypted format to traditional format:
 .PP
 .Vb 1
-\& openssl pkcs8 \-in pk8.pem \-out key.pem
+\& openssl pkcs8 \-in pk8.pem \-traditional \-out key.pem
+.Ve
+.PP
+Convert a private key to PKCS#8 format, encrypting with \s-1AES\-256\s0 and with
+one million iterations of the password:
+.PP
+.Vb 1
+\& openssl pkcs8 \-in key.pem \-topk8 \-v2 aes\-256\-cbc \-iter 1000000 \-out pk8.pem
 .Ve
 .SH "STANDARDS"
 .IX Header "STANDARDS"
@@ -359,11 +413,18 @@ PKCS#8 private key format complies with this standard.
 .IX Header "BUGS"
 There should be an option that prints out the encryption algorithm
 in use and other details such as the iteration count.
-.PP
-PKCS#8 using triple \s-1DES\s0 and PKCS#5 v2.0 should be the default private
-key format for OpenSSL: for compatibility several of the utilities use
-the old format at present.
 .SH "SEE ALSO"
 .IX Header "SEE ALSO"
 \&\fIdsa\fR\|(1), \fIrsa\fR\|(1), \fIgenrsa\fR\|(1),
 \&\fIgendsa\fR\|(1)
+.SH "HISTORY"
+.IX Header "HISTORY"
+The \fB\-iter\fR option was added to OpenSSL 1.1.0.
+.SH "COPYRIGHT"
+.IX Header "COPYRIGHT"
+Copyright 2000\-2018 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>.