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