[B<-iter count>]
[B<-noiter>]
[B<-nocrypt>]
+[B<-traditional>]
[B<-v2 alg>]
[B<-v2prf alg>]
[B<-v1 alg>]
=item B<-topk8>
-Normally a PKCS#8 private key is expected on input and a traditional format
-private key will be written. With the B<-topk8> 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 B<-topk8> option the situation is
+reversed: it reads a private key and writes a PKCS#8 format key.
=item B<-inform DER|PEM>
-This specifies the input format. If a PKCS#8 format key is expected on input
-then either a B<DER> or B<PEM> encoded version of a PKCS#8 key will be
-expected. Otherwise the B<DER> or B<PEM> format of the traditional format
-private key is used.
+This specifies the input format: see L<KEY FORMATS> for more details.
=item B<-outform DER|PEM>
-This specifies the output format, the options have the same meaning as the
-B<-inform> option.
+This specifies the output format: see L<KEY FORMATS> for more details.
+
+=item B<-traditional>
+
+When this option is present and B<-topk8> is not a traditional format private
+key is written.
=item B<-in filename>
=item B<-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 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 sets the PKCS#5 v2.0 algorithm.
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.
+B<aes128>, B<aes256> and B<des3>. If this option isn't specified then B<aes256>
+is used.
=item B<-v2prf alg>
This option sets the PRF algorithm to use with PKCS#5 v2.0. A typical value
-values would be B<hmacWithSHA256>. If this option isn't set then the default
-for the cipher is used or B<hmacWithSHA1> if there is no default.
+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.
+
+Some implementations may not support custom PRF algorithms and may require
+the B<hmacWithSHA1> option to work.
=item B<-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.
=item B<-engine id>
=back
+=head1 KEY FORMATS
+
+Various different formats are used by the pkcs8 utility. These are detailed
+below.
+
+If a key is being converted from PKCS#8 form (i.e. the B<-topk8> option is
+not used) then the input file must be in PKCS#8 format. An encrypted
+key is expected unless B<-nocrypt> is included.
+
+If B<-topk8> is not used and B<PEM> mode is set the output file will be an
+unencrypted private key in PKCS#8 format. If the B<-traditional> option is
+used then a traditional format private key is written instead.
+
+If B<-topk8> is not used and B<DER> mode is set the output file will be an
+unencrypted private key in traditional DER format.
+
+If B<-topk8> is used then any supported private key can be used for the input
+file in a format specified by B<-inform>. The output file will be encrypted
+PKCS#8 format using the specified encryption parameters unless B<-nocrypt>
+is included.
+
=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.
=head1 EXAMPLES
-Convert a private from traditional to PKCS#5 v2.0 format using triple
-DES:
+Convert a private key to PKCS#8 format using default parameters (AES with
+256 bit key and B<hmacWithSHA256>):
+
+ openssl pkcs8 -in key.pem -topk8 -out enckey.pem
+
+Convert a private key to PKCS#8 unencrypted format:
+
+ openssl pkcs8 -in key.pem -topk8 -nocrypt -out enckey.pem
+
+Convert a private key to PKCS#5 v2.0 format using triple DES:
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:
+Convert a private key to PKCS#5 v2.0 format using AES with 256 bits in CBC
+mode and B<hmacWithSHA512> PRF:
- 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
Convert a private key to PKCS#8 using a PKCS#5 1.5 compatible algorithm
(DES):
- openssl pkcs8 -in key.pem -topk8 -out enckey.pem
+ openssl pkcs8 -in key.pem -topk8 -v1 PBE-MD5-DES -out enckey.pem
Convert a private key to PKCS#8 using a PKCS#12 compatible algorithm
(3DES):
openssl pkcs8 -inform DER -nocrypt -in key.der -out key.pem
-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:
+
+ openssl pkcs8 -in pk8.pem -traditional -out key.pem
- openssl pkcs8 -in pk8.pem -out key.pem
-
-Convert a private key to PKCS#8 format, encrypting with AES-256 and with
+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
+ openssl pkcs8 -in key.pem -topk8 -v2 aes-256-cbc -iter 1000000 -out pk8.pem
=head1 STANDARDS
There should be an option that prints out the encryption algorithm
in use and other details such as the iteration count.
-PKCS#8 using triple DES 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.
-
=head1 SEE ALSO
L<dsa(1)>, L<rsa(1)>, L<genrsa(1)>,
-L<gendsa(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 / oweals / openssl.git / blobdiff