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