1=pod 2{- OpenSSL::safe::output_do_not_edit_headers(); -} 3 4=head1 NAME 5 6openssl-pkcs8 - PKCS#8 format private key conversion command 7 8=head1 SYNOPSIS 9 10B<openssl> B<pkcs8> 11[B<-help>] 12[B<-topk8>] 13[B<-inform> B<DER>|B<PEM>] 14[B<-outform> B<DER>|B<PEM>] 15[B<-in> I<filename>] 16[B<-passin> I<arg>] 17[B<-out> I<filename>] 18[B<-passout> I<arg>] 19[B<-iter> I<count>] 20[B<-noiter>] 21[B<-nocrypt>] 22[B<-traditional>] 23[B<-v2> I<alg>] 24[B<-v2prf> I<alg>] 25[B<-v1> I<alg>] 26[B<-scrypt>] 27[B<-scrypt_N> I<N>] 28[B<-scrypt_r> I<r>] 29[B<-scrypt_p> I<p>] 30{- $OpenSSL::safe::opt_r_synopsis -} 31{- $OpenSSL::safe::opt_engine_synopsis -}{- $OpenSSL::safe::opt_provider_synopsis -} 32 33=head1 DESCRIPTION 34 35This command processes private keys in PKCS#8 format. It can handle 36both unencrypted PKCS#8 PrivateKeyInfo format and EncryptedPrivateKeyInfo 37format with a variety of PKCS#5 (v1.5 and v2.0) and PKCS#12 algorithms. 38 39=head1 OPTIONS 40 41=over 4 42 43=item B<-help> 44 45Print out a usage message. 46 47=item B<-topk8> 48 49Normally a PKCS#8 private key is expected on input and a private key will be 50written to the output file. With the B<-topk8> option the situation is 51reversed: it reads a private key and writes a PKCS#8 format key. 52 53=item B<-inform> B<DER>|B<PEM>, B<-outform> B<DER>|B<PEM> 54 55The input and formats; the default is B<PEM>. 56See L<openssl-format-options(1)> for details. 57 58If a key is being converted from PKCS#8 form (i.e. the B<-topk8> option is 59not used) then the input file must be in PKCS#8 format. An encrypted 60key is expected unless B<-nocrypt> is included. 61 62If B<-topk8> is not used and B<PEM> mode is set the output file will be an 63unencrypted private key in PKCS#8 format. If the B<-traditional> option is 64used then a traditional format private key is written instead. 65 66If B<-topk8> is not used and B<DER> mode is set the output file will be an 67unencrypted private key in traditional DER format. 68 69If B<-topk8> is used then any supported private key can be used for the input 70file in a format specified by B<-inform>. The output file will be encrypted 71PKCS#8 format using the specified encryption parameters unless B<-nocrypt> 72is included. 73 74=item B<-traditional> 75 76When this option is present and B<-topk8> is not a traditional format private 77key is written. 78 79=item B<-in> I<filename> 80 81This specifies the input filename to read a key from or standard input if this 82option is not specified. If the key is encrypted a pass phrase will be 83prompted for. 84 85=item B<-passin> I<arg>, B<-passout> I<arg> 86 87The password source for the input and output file. 88For more information about the format of B<arg> 89see L<openssl-passphrase-options(1)>. 90 91=item B<-out> I<filename> 92 93This specifies the output filename to write a key to or standard output by 94default. If any encryption options are set then a pass phrase will be 95prompted for. The output filename should B<not> be the same as the input 96filename. 97 98=item B<-iter> I<count> 99 100When creating new PKCS#8 containers, use a given number of iterations on 101the password in deriving the encryption key for the PKCS#8 output. 102High values increase the time required to brute-force a PKCS#8 container. 103 104=item B<-noiter> 105 106When creating new PKCS#8 containers, use 1 as iteration count. 107 108=item B<-nocrypt> 109 110PKCS#8 keys generated or input are normally PKCS#8 EncryptedPrivateKeyInfo 111structures using an appropriate password based encryption algorithm. With 112this option an unencrypted PrivateKeyInfo structure is expected or output. 113This option does not encrypt private keys at all and should only be used 114when absolutely necessary. Certain software such as some versions of Java 115code signing software used unencrypted private keys. 116 117=item B<-v2> I<alg> 118 119This option sets the PKCS#5 v2.0 algorithm. 120 121The I<alg> argument is the encryption algorithm to use, valid values include 122B<aes128>, B<aes256> and B<des3>. If this option isn't specified then B<aes256> 123is used. 124 125=item B<-v2prf> I<alg> 126 127This option sets the PRF algorithm to use with PKCS#5 v2.0. A typical value 128value would be B<hmacWithSHA256>. If this option isn't set then the default 129for the cipher is used or B<hmacWithSHA256> if there is no default. 130 131Some implementations may not support custom PRF algorithms and may require 132the B<hmacWithSHA1> option to work. 133 134=item B<-v1> I<alg> 135 136This option indicates a PKCS#5 v1.5 or PKCS#12 algorithm should be used. Some 137older implementations may not support PKCS#5 v2.0 and may require this option. 138If not specified PKCS#5 v2.0 form is used. 139 140=item B<-scrypt> 141 142Uses the B<scrypt> algorithm for private key encryption using default 143parameters: currently N=16384, r=8 and p=1 and AES in CBC mode with a 256 bit 144key. These parameters can be modified using the B<-scrypt_N>, B<-scrypt_r>, 145B<-scrypt_p> and B<-v2> options. 146 147=item B<-scrypt_N> I<N>, B<-scrypt_r> I<r>, B<-scrypt_p> I<p> 148 149Sets the scrypt I<N>, I<r> or I<p> parameters. 150 151{- $OpenSSL::safe::opt_r_item -} 152 153{- $OpenSSL::safe::opt_engine_item -} 154 155{- $OpenSSL::safe::opt_provider_item -} 156 157=back 158 159=head1 NOTES 160 161By default, when converting a key to PKCS#8 format, PKCS#5 v2.0 using 256 bit 162AES with HMAC and SHA256 is used. 163 164Some older implementations do not support PKCS#5 v2.0 format and require 165the older PKCS#5 v1.5 form instead, possibly also requiring insecure weak 166encryption algorithms such as 56 bit DES. 167 168Private keys encrypted using PKCS#5 v2.0 algorithms and high iteration 169counts are more secure that those encrypted using the traditional 170SSLeay compatible formats. So if additional security is considered 171important the keys should be converted. 172 173It is possible to write out DER encoded encrypted private keys in 174PKCS#8 format because the encryption details are included at an ASN1 175level whereas the traditional format includes them at a PEM level. 176 177=head1 PKCS#5 V1.5 AND PKCS#12 ALGORITHMS 178 179Various algorithms can be used with the B<-v1> command line option, 180including PKCS#5 v1.5 and PKCS#12. These are described in more detail 181below. 182 183=over 4 184 185=item B<PBE-MD2-DES PBE-MD5-DES> 186 187These algorithms were included in the original PKCS#5 v1.5 specification. 188They only offer 56 bits of protection since they both use DES. 189 190=item B<PBE-SHA1-RC2-64>, B<PBE-MD2-RC2-64>, B<PBE-MD5-RC2-64>, B<PBE-SHA1-DES> 191 192These algorithms are not mentioned in the original PKCS#5 v1.5 specification 193but they use the same key derivation algorithm and are supported by some 194software. They are mentioned in PKCS#5 v2.0. They use either 64 bit RC2 or 19556 bit DES. 196 197=item B<PBE-SHA1-RC4-128>, B<PBE-SHA1-RC4-40>, B<PBE-SHA1-3DES>, B<PBE-SHA1-2DES>, B<PBE-SHA1-RC2-128>, B<PBE-SHA1-RC2-40> 198 199These algorithms use the PKCS#12 password based encryption algorithm and 200allow strong encryption algorithms like triple DES or 128 bit RC2 to be used. 201 202=back 203 204=head1 EXAMPLES 205 206Convert a private key to PKCS#8 format using default parameters (AES with 207256 bit key and B<hmacWithSHA256>): 208 209 openssl pkcs8 -in key.pem -topk8 -out enckey.pem 210 211Convert a private key to PKCS#8 unencrypted format: 212 213 openssl pkcs8 -in key.pem -topk8 -nocrypt -out enckey.pem 214 215Convert a private key to PKCS#5 v2.0 format using triple DES: 216 217 openssl pkcs8 -in key.pem -topk8 -v2 des3 -out enckey.pem 218 219Convert a private key to PKCS#5 v2.0 format using AES with 256 bits in CBC 220mode and B<hmacWithSHA512> PRF: 221 222 openssl pkcs8 -in key.pem -topk8 -v2 aes-256-cbc -v2prf hmacWithSHA512 -out enckey.pem 223 224Convert a private key to PKCS#8 using a PKCS#5 1.5 compatible algorithm 225(DES): 226 227 openssl pkcs8 -in key.pem -topk8 -v1 PBE-MD5-DES -out enckey.pem 228 229Convert a private key to PKCS#8 using a PKCS#12 compatible algorithm 230(3DES): 231 232 openssl pkcs8 -in key.pem -topk8 -out enckey.pem -v1 PBE-SHA1-3DES 233 234Read a DER unencrypted PKCS#8 format private key: 235 236 openssl pkcs8 -inform DER -nocrypt -in key.der -out key.pem 237 238Convert a private key from any PKCS#8 encrypted format to traditional format: 239 240 openssl pkcs8 -in pk8.pem -traditional -out key.pem 241 242Convert a private key to PKCS#8 format, encrypting with AES-256 and with 243one million iterations of the password: 244 245 openssl pkcs8 -in key.pem -topk8 -v2 aes-256-cbc -iter 1000000 -out pk8.pem 246 247=head1 STANDARDS 248 249Test vectors from this PKCS#5 v2.0 implementation were posted to the 250pkcs-tng mailing list using triple DES, DES and RC2 with high iteration 251counts, several people confirmed that they could decrypt the private 252keys produced and therefore, it can be assumed that the PKCS#5 v2.0 253implementation is reasonably accurate at least as far as these 254algorithms are concerned. 255 256The format of PKCS#8 DSA (and other) private keys is not well documented: 257it is hidden away in PKCS#11 v2.01, section 11.9. OpenSSL's default DSA 258PKCS#8 private key format complies with this standard. 259 260=head1 BUGS 261 262There should be an option that prints out the encryption algorithm 263in use and other details such as the iteration count. 264 265=head1 SEE ALSO 266 267L<openssl(1)>, 268L<openssl-dsa(1)>, 269L<openssl-rsa(1)>, 270L<openssl-genrsa(1)>, 271L<openssl-gendsa(1)> 272 273=head1 HISTORY 274 275The B<-iter> option was added in OpenSSL 1.1.0. 276 277The B<-engine> option was deprecated in OpenSSL 3.0. 278 279=head1 COPYRIGHT 280 281Copyright 2000-2021 The OpenSSL Project Authors. All Rights Reserved. 282 283Licensed under the Apache License 2.0 (the "License"). You may not use 284this file except in compliance with the License. You can obtain a copy 285in the file LICENSE in the source distribution or at 286L<https://www.openssl.org/source/license.html>. 287 288=cut 289