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