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