=head1 SYNOPSIS
B<openssl> B<pkcs8>
+[B<-help>]
[B<-topk8>]
[B<-inform PEM|DER>]
[B<-outform PEM|DER>]
[B<-in filename>]
-[B<-passin password>]
-[B<-envpassin var>]
+[B<-passin arg>]
[B<-out filename>]
-[B<-passout password>]
-[B<-envpassout var>]
+[B<-passout arg>]
+[B<-iter count>]
[B<-noiter>]
[B<-nocrypt>]
-[B<-nooct>]
-[B<-embed>]
-[B<-nsdb>]
[B<-v2 alg>]
+[B<-v2prf alg>]
[B<-v1 alg>]
+[B<-engine id>]
+[B<-scrypt>]
+[B<-scrypt_N N>]
+[B<-scrypt_r r>]
+[B<-scrypt_p p>]
=head1 DESCRIPTION
=over 4
+=item B<-help>
+
+Print out a usage message.
+
=item B<-topk8>
Normally a PKCS#8 private key is expected on input and a traditional format
=item B<-outform DER|PEM>
-This specifies the output format, the options have the same meaning as the
+This specifies the output format, the options have the same meaning as the
B<-inform> option.
=item B<-in filename>
option is not specified. If the key is encrypted a pass phrase will be
prompted for.
-=item B<-passin password>
-
-the input file password. Since certain utilities like "ps" make the command line
-visible this option should be used with caution.
-
-=item B<-envpassin var>
+=item B<-passin arg>
-read the input file password from the environment variable B<var>.
+the input file password source. For more information about the format of B<arg>
+see the B<PASS PHRASE ARGUMENTS> section in L<openssl(1)>.
=item B<-out filename>
prompted for. The output filename should B<not> be the same as the input
filename.
-=item B<-passout password>
+=item B<-passout arg>
-the output file password. Since certain utilities like "ps" make the command line
-visible this option should be used with caution.
+the output file password source. For more information about the format of B<arg>
+see the B<PASS PHRASE ARGUMENTS> section in L<openssl(1)>.
-=item B<-envpassout var>
+=item B<-iter count>
-read the output file password from the environment variable B<var>.
+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.
=item B<-nocrypt>
when absolutely necessary. Certain software such as some versions of Java
code signing software used unencrypted private keys.
-=item B<-nooct>
+=item B<-v2 alg>
-This option generates RSA private keys in a broken format that some software
-uses. Specifically the private key should be enclosed in a OCTET STRING
-but some software just includes the structure itself without the
-surrounding OCTET STRING.
+This option sets the PKCS#5 v2.0 algorithm.
-=item B<-embed>
+The B<alg> argument is the encryption algorithm to use, valid values include
+B<aes128>, B<aes256> and B<des3>. If this option isn't specified then B<aes256>
+is used.
-This option generates DSA keys in a broken format. The DSA parameters are
-embedded inside the PrivateKey structure. In this form the OCTET STRING
-contains an ASN1 SEQUENCE consisting of two structures: a SEQUENCE containing
-the parameters and an ASN1 INTEGER containing the private key.
+=item B<-v2prf alg>
-=item B<-nsdb>
+This option sets the PRF algorithm to use with PKCS#5 v2.0. A typical value
+value would be B<hmacWithSHA256>. If this option isn't set then the default
+for the cipher is used or B<hmacWithSHA256> if there is no default.
-This option generates DSA keys in a broken format compatible with Netscape
-private key databases. The PrivateKey contains a SEQUENCE consisting of
-the public and private keys respectively.
+Some implementations may not support custom PRF algorithms and may require
+the B<hmacWithSHA1> option to work.
-=item B<-v2 alg>
+=item B<-v1 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 B<pbeWithMD5AndDES-CBC> this uses 56 bit DES encryption but it
-was the strongest encryption algorithm supported in PKCS#5 v1.5. Using
-the B<-v2> option PKCS#5 v2.0 algorithms are used which can use any
-encryption algorithm such as 168 bit triple DES or 128 bit RC2 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 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 for is used.
-The B<alg> argument is the encryption algorithm to use, valid values include
-B<des>, B<des3> and B<rc2>. It is recommended that B<des3> is used.
+=item B<-engine id>
-=item B<-v1 alg>
+specifying an engine (by its unique B<id> string) will cause B<pkcs8>
+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.
+
+=item B<-scrypt>
+
+uses the B<scrypt> algorithm for private key encryption using default
+parameters: currently N=16384, r=8 and p=1 and AES in CBC mode with a 256 bit
+key. These parameters can be modified using the B<-scrypt_N>, B<-scrypt_r>,
+B<-scrypt_p> and B<-v2> options.
+
+B<-scrypt_N N> B<-scrypt_r r> B<-scrypt_p p>
-This option specifies a PKCS#5 v1.5 or PKCS#12 algorithm to use. A complete
-list of possible algorithms is included below.
+sets the scrypt B<N>, B<r> or B<p> parameters.
=back
=head1 NOTES
+By default, when converting a key to PKCS#8 format, PKCS#5 v2.0 using 256 bit
+AES with HMAC and SHA256 is used.
+
+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 DES.
+
The encrypted form of a PEM encode PKCS#8 files uses the following
headers and footers:
SSLeay compatible formats. So if additional security is considered
important the keys should be converted.
-The default encryption is only 56 bits because this is the encryption
-that most current implementations of PKCS#8 will support.
-
-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.
-
It is possible to write out DER encoded encrypted private keys in
PKCS#8 format because the encryption details are included at an ASN1
level whereas the traditional format includes them at a PEM level.
openssl pkcs8 -in key.pem -topk8 -v2 des3 -out enckey.pem
+Convert a private from traditional to PKCS#5 v2.0 format using AES with
+256 bits in CBC mode and B<hmacWithSHA256> PRF:
+
+ openssl pkcs8 -in key.pem -topk8 -v2 aes-256-cbc -v2prf hmacWithSHA256 -out enckey.pem
+
Convert a private key to PKCS#8 using a PKCS#5 1.5 compatible algorithm
(DES):
openssl pkcs8 -in pk8.pem -out key.pem
+Convert a private key to PKCS#8 format, encrypting with AES-256 and with
+one million iterations of the password:
+
+ openssl pkcs8 -in raw.pem -topk8 -v2 aes-256-cbc -iter 1000000 -out pk8.pem
+
=head1 STANDARDS
Test vectors from this PKCS#5 v2.0 implementation were posted to the
algorithms are concerned.
The format of PKCS#8 DSA (and other) private keys is not well documented:
-it is hidden away in PKCS#11 v2.01, section 11.9. OpenSSL's DSA private
-key format complies with this standard.
+it is hidden away in PKCS#11 v2.01, section 11.9. OpenSSL's default DSA
+PKCS#8 private key format complies with this standard.
=head1 BUGS
=head1 SEE ALSO
-L<dsa(1)|dsa(1)>, L<rsa(1)|rsa(1)>, L<genrsa(1)|genrsa(1)>,
-L<gendsa(1)|gendsa(1)>
+L<dsa(1)>, L<rsa(1)>, L<genrsa(1)>,
+L<gendsa(1)>
+
+=head1 HISTORY
+
+The B<-iter> option was added to OpenSSL 1.1.0.
+
+=head1 COPYRIGHT
+
+Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved.
+
+Licensed under the OpenSSL license (the "License"). You may not use
+this file except in compliance with the License. You can obtain a copy
+in the file LICENSE in the source distribution or at
+L<https://www.openssl.org/source/license.html>.
=cut
projects / openssl.git / blobdiff