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