5 pkcs8 - PKCS#8 format private key conversion tool
32 The B<pkcs8> command processes private keys in PKCS#8 format. It can handle
33 both unencrypted PKCS#8 PrivateKeyInfo format and EncryptedPrivateKeyInfo
34 format with a variety of PKCS#5 (v1.5 and v2.0) and PKCS#12 algorithms.
36 =head1 COMMAND OPTIONS
42 Print out a usage message.
46 Normally a PKCS#8 private key is expected on input and a traditional format
47 private key will be written. With the B<-topk8> option the situation is
48 reversed: it reads a traditional format private key and writes a PKCS#8
51 =item B<-inform DER|PEM>
53 This specifies the input format. If a PKCS#8 format key is expected on input
54 then either a B<DER> or B<PEM> encoded version of a PKCS#8 key will be
55 expected. Otherwise the B<DER> or B<PEM> format of the traditional format
58 =item B<-outform DER|PEM>
60 This specifies the output format, the options have the same meaning as the
65 This specifies the input filename to read a key from or standard input if this
66 option is not specified. If the key is encrypted a pass phrase will be
71 the input file password source. For more information about the format of B<arg>
72 see the B<PASS PHRASE ARGUMENTS> section in L<openssl(1)>.
74 =item B<-out filename>
76 This specifies the output filename to write a key to or standard output by
77 default. If any encryption options are set then a pass phrase will be
78 prompted for. The output filename should B<not> be the same as the input
83 the output file password source. For more information about the format of B<arg>
84 see the B<PASS PHRASE ARGUMENTS> section in L<openssl(1)>.
88 When creating new PKCS#8 containers, use a given number of iterations on
89 the password in deriving the encryption key for the PKCS#8 output.
90 High values increase the time required to brute-force a PKCS#8 container.
94 PKCS#8 keys generated or input are normally PKCS#8 EncryptedPrivateKeyInfo
95 structures using an appropriate password based encryption algorithm. With
96 this option an unencrypted PrivateKeyInfo structure is expected or output.
97 This option does not encrypt private keys at all and should only be used
98 when absolutely necessary. Certain software such as some versions of Java
99 code signing software used unencrypted private keys.
103 This option enables the use of PKCS#5 v2.0 algorithms. Normally PKCS#8
104 private keys are encrypted with the password based encryption algorithm
105 called B<pbeWithMD5AndDES-CBC> this uses 56 bit DES encryption but it
106 was the strongest encryption algorithm supported in PKCS#5 v1.5. Using
107 the B<-v2> option PKCS#5 v2.0 algorithms are used which can use any
108 encryption algorithm such as 168 bit triple DES or 128 bit RC2 however
109 not many implementations support PKCS#5 v2.0 yet. If you are just using
110 private keys with OpenSSL then this doesn't matter.
112 The B<alg> argument is the encryption algorithm to use, valid values include
113 B<des>, B<des3> and B<rc2>. It is recommended that B<des3> is used.
117 This option sets the PRF algorithm to use with PKCS#5 v2.0. A typical value
118 values would be B<hmacWithSHA256>. If this option isn't set then the default
119 for the cipher is used or B<hmacWithSHA1> if there is no default.
123 This option specifies a PKCS#5 v1.5 or PKCS#12 algorithm to use. A complete
124 list of possible algorithms is included below.
128 specifying an engine (by its unique B<id> string) will cause B<pkcs8>
129 to attempt to obtain a functional reference to the specified engine,
130 thus initialising it if needed. The engine will then be set as the default
131 for all available algorithms.
135 uses the B<scrypt> algorithm for private key encryption using default
136 parameters: currently N=16384, r=8 and p=1 and AES in CBC mode with a 256 bit
137 key. These parameters can be modified using the B<-scrypt_N>, B<-scrypt_r>,
138 B<-scrypt_p> and B<-v2> options.
140 B<-scrypt_N N> B<-scrypt_r r> B<-scrypt_p p>
142 sets the scrypt B<N>, B<r> or B<p> parameters.
148 The encrypted form of a PEM encode PKCS#8 files uses the following
151 -----BEGIN ENCRYPTED PRIVATE KEY-----
152 -----END ENCRYPTED PRIVATE KEY-----
154 The unencrypted form uses:
156 -----BEGIN PRIVATE KEY-----
157 -----END PRIVATE KEY-----
159 Private keys encrypted using PKCS#5 v2.0 algorithms and high iteration
160 counts are more secure that those encrypted using the traditional
161 SSLeay compatible formats. So if additional security is considered
162 important the keys should be converted.
164 The default encryption is only 56 bits because this is the encryption
165 that most current implementations of PKCS#8 will support.
167 Some software may use PKCS#12 password based encryption algorithms
168 with PKCS#8 format private keys: these are handled automatically
169 but there is no option to produce them.
171 It is possible to write out DER encoded encrypted private keys in
172 PKCS#8 format because the encryption details are included at an ASN1
173 level whereas the traditional format includes them at a PEM level.
175 =head1 PKCS#5 v1.5 and PKCS#12 algorithms.
177 Various algorithms can be used with the B<-v1> command line option,
178 including PKCS#5 v1.5 and PKCS#12. These are described in more detail
183 =item B<PBE-MD2-DES PBE-MD5-DES>
185 These algorithms were included in the original PKCS#5 v1.5 specification.
186 They only offer 56 bits of protection since they both use DES.
188 =item B<PBE-SHA1-RC2-64 PBE-MD2-RC2-64 PBE-MD5-RC2-64 PBE-SHA1-DES>
190 These algorithms are not mentioned in the original PKCS#5 v1.5 specification
191 but they use the same key derivation algorithm and are supported by some
192 software. They are mentioned in PKCS#5 v2.0. They use either 64 bit RC2 or
195 =item B<PBE-SHA1-RC4-128 PBE-SHA1-RC4-40 PBE-SHA1-3DES PBE-SHA1-2DES PBE-SHA1-RC2-128 PBE-SHA1-RC2-40>
197 These algorithms use the PKCS#12 password based encryption algorithm and
198 allow strong encryption algorithms like triple DES or 128 bit RC2 to be used.
204 Convert a private from traditional to PKCS#5 v2.0 format using triple
207 openssl pkcs8 -in key.pem -topk8 -v2 des3 -out enckey.pem
209 Convert a private from traditional to PKCS#5 v2.0 format using AES with
210 256 bits in CBC mode and B<hmacWithSHA256> PRF:
212 openssl pkcs8 -in key.pem -topk8 -v2 aes-256-cbc -v2prf hmacWithSHA256 -out enckey.pem
214 Convert a private key to PKCS#8 using a PKCS#5 1.5 compatible algorithm
217 openssl pkcs8 -in key.pem -topk8 -out enckey.pem
219 Convert a private key to PKCS#8 using a PKCS#12 compatible algorithm
222 openssl pkcs8 -in key.pem -topk8 -out enckey.pem -v1 PBE-SHA1-3DES
224 Read a DER unencrypted PKCS#8 format private key:
226 openssl pkcs8 -inform DER -nocrypt -in key.der -out key.pem
228 Convert a private key from any PKCS#8 format to traditional format:
230 openssl pkcs8 -in pk8.pem -out key.pem
232 Convert a private key to PKCS#8 format, encrypting with AES-256 and with
233 one million iterations of the password:
235 openssl pkcs8 -in raw.pem -topk8 -v2 aes-256-cbc -iter 1000000 -out pk8.pem
239 Test vectors from this PKCS#5 v2.0 implementation were posted to the
240 pkcs-tng mailing list using triple DES, DES and RC2 with high iteration
241 counts, several people confirmed that they could decrypt the private
242 keys produced and Therefore it can be assumed that the PKCS#5 v2.0
243 implementation is reasonably accurate at least as far as these
244 algorithms are concerned.
246 The format of PKCS#8 DSA (and other) private keys is not well documented:
247 it is hidden away in PKCS#11 v2.01, section 11.9. OpenSSL's default DSA
248 PKCS#8 private key format complies with this standard.
252 There should be an option that prints out the encryption algorithm
253 in use and other details such as the iteration count.
255 PKCS#8 using triple DES and PKCS#5 v2.0 should be the default private
256 key format for OpenSSL: for compatibility several of the utilities use
257 the old format at present.
261 L<dsa(1)>, L<rsa(1)>, L<genrsa(1)>,
266 The B<-iter> option was added to OpenSSL 1.1.0.