]>
Commit | Line | Data |
---|---|---|
aba3e65f | 1 | =pod |
625c781d | 2 | {- OpenSSL::safe::output_do_not_edit_headers(); -} |
9fcb9702 | 3 | |
aba3e65f DSH |
4 | =head1 NAME |
5 | ||
4b537191 | 6 | openssl-pkcs8 - PKCS#8 format private key conversion command |
aba3e65f DSH |
7 | |
8 | =head1 SYNOPSIS | |
9 | ||
10 | B<openssl> B<pkcs8> | |
169394d4 | 11 | [B<-help>] |
aba3e65f | 12 | [B<-topk8>] |
e8769719 RS |
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>] | |
aba3e65f DSH |
20 | [B<-noiter>] |
21 | [B<-nocrypt>] | |
05dba815 | 22 | [B<-traditional>] |
8dc57d76 RL |
23 | [B<-v2> I<alg>] |
24 | [B<-v2prf> I<alg>] | |
25 | [B<-v1> I<alg>] | |
0ceb8b74 | 26 | [B<-scrypt>] |
e8769719 RS |
27 | [B<-scrypt_N> I<N>] |
28 | [B<-scrypt_r> I<r>] | |
29 | [B<-scrypt_p> I<p>] | |
9f679bdc | 30 | [B<-saltlen> I<size>] |
9fcb9702 | 31 | {- $OpenSSL::safe::opt_r_synopsis -} |
d55e4487 | 32 | {- $OpenSSL::safe::opt_engine_synopsis -}{- $OpenSSL::safe::opt_provider_synopsis -} |
aba3e65f DSH |
33 | |
34 | =head1 DESCRIPTION | |
35 | ||
35a810bb | 36 | This command processes private keys in PKCS#8 format. It can handle |
aba3e65f DSH |
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 | 53 | |
777182a0 | 54 | =item B<-inform> B<DER>|B<PEM>, B<-outform> B<DER>|B<PEM> |
aba3e65f | 55 | |
777182a0 | 56 | The input and formats; the default is B<PEM>. |
46949153 | 57 | See L<openssl-format-options(1)> for details. |
aba3e65f | 58 | |
777182a0 RS |
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. | |
aba3e65f | 74 | |
05dba815 DSH |
75 | =item B<-traditional> |
76 | ||
77 | When this option is present and B<-topk8> is not a traditional format private | |
78 | key is written. | |
aba3e65f | 79 | |
e8769719 | 80 | =item B<-in> I<filename> |
aba3e65f DSH |
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 | ||
3a4e43de | 86 | =item B<-passin> I<arg>, B<-passout> I<arg> |
20432eae | 87 | |
3a4e43de RS |
88 | The password source for the input and output file. |
89 | For more information about the format of B<arg> | |
46949153 | 90 | see L<openssl-passphrase-options(1)>. |
20432eae | 91 | |
e8769719 | 92 | =item B<-out> I<filename> |
aba3e65f DSH |
93 | |
94 | This specifies the output filename to write a key to or standard output by | |
174a4a8c | 95 | default. If any encryption options are set then a pass phrase will be |
aba3e65f DSH |
96 | prompted for. The output filename should B<not> be the same as the input |
97 | filename. | |
98 | ||
e8769719 | 99 | =item B<-iter> I<count> |
96fc4b72 | 100 | |
f20bb4eb JW |
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. | |
359efeac DDO |
104 | |
105 | =item B<-noiter> | |
106 | ||
107 | When creating new PKCS#8 containers, use 1 as iteration count. | |
96fc4b72 | 108 | |
174a4a8c | 109 | =item B<-nocrypt> |
aba3e65f | 110 | |
174a4a8c DSH |
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. | |
aba3e65f | 117 | |
8dc57d76 | 118 | =item B<-v2> I<alg> |
aba3e65f | 119 | |
8fc06e88 | 120 | This option sets the PKCS#5 v2.0 algorithm. |
aba3e65f | 121 | |
2f0ea936 | 122 | The I<alg> argument is the encryption algorithm to use, valid values include |
8fc06e88 DSH |
123 | B<aes128>, B<aes256> and B<des3>. If this option isn't specified then B<aes256> |
124 | is used. | |
aba3e65f | 125 | |
8dc57d76 | 126 | =item B<-v2prf> I<alg> |
5693a308 DSH |
127 | |
128 | This option sets the PRF algorithm to use with PKCS#5 v2.0. A typical value | |
8fc06e88 DSH |
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. | |
5693a308 | 134 | |
8dc57d76 | 135 | =item B<-v1> I<alg> |
525f51f6 | 136 | |
8fc06e88 DSH |
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. | |
05dba815 | 139 | If not specified PKCS#5 v2.0 form is used. |
525f51f6 | 140 | |
0ceb8b74 DSH |
141 | =item B<-scrypt> |
142 | ||
c4de074e | 143 | Uses the B<scrypt> algorithm for private key encryption using default |
5fc3ee4b | 144 | parameters: currently N=16384, r=8 and p=1 and AES in CBC mode with a 256 bit |
0ceb8b74 DSH |
145 | key. These parameters can be modified using the B<-scrypt_N>, B<-scrypt_r>, |
146 | B<-scrypt_p> and B<-v2> options. | |
147 | ||
e8769719 | 148 | =item B<-scrypt_N> I<N>, B<-scrypt_r> I<r>, B<-scrypt_p> I<p> |
0ceb8b74 | 149 | |
2f0ea936 | 150 | Sets the scrypt I<N>, I<r> or I<p> parameters. |
0ceb8b74 | 151 | |
9f679bdc | 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 | ||
9fcb9702 RS |
158 | {- $OpenSSL::safe::opt_r_item -} |
159 | ||
018aaeb4 RS |
160 | {- $OpenSSL::safe::opt_engine_item -} |
161 | ||
6bd4e3f2 P |
162 | {- $OpenSSL::safe::opt_provider_item -} |
163 | ||
174a4a8c | 164 | =back |
aba3e65f | 165 | |
174a4a8c | 166 | =head1 NOTES |
aba3e65f | 167 | |
8fc06e88 DSH |
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 | ||
174a4a8c DSH |
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. | |
aba3e65f | 179 | |
174a4a8c DSH |
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. | |
aba3e65f | 183 | |
485d3361 | 184 | =head1 PKCS#5 V1.5 AND PKCS#12 ALGORITHMS |
525f51f6 DSH |
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 | ||
dfee8626 | 197 | =item B<PBE-SHA1-RC2-64>, B<PBE-MD2-RC2-64>, B<PBE-MD5-RC2-64>, B<PBE-SHA1-DES> |
525f51f6 DSH |
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 | |
c3ed3b6e | 201 | software. They are mentioned in PKCS#5 v2.0. They use either 64 bit RC2 or |
525f51f6 DSH |
202 | 56 bit DES. |
203 | ||
dfee8626 | 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> |
525f51f6 DSH |
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 | ||
aba3e65f DSH |
211 | =head1 EXAMPLES |
212 | ||
05dba815 DSH |
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: | |
aba3e65f | 223 | |
174a4a8c | 224 | openssl pkcs8 -in key.pem -topk8 -v2 des3 -out enckey.pem |
aba3e65f | 225 | |
05dba815 DSH |
226 | Convert a private key to PKCS#5 v2.0 format using AES with 256 bits in CBC |
227 | mode and B<hmacWithSHA512> PRF: | |
5693a308 | 228 | |
05dba815 | 229 | openssl pkcs8 -in key.pem -topk8 -v2 aes-256-cbc -v2prf hmacWithSHA512 -out enckey.pem |
5693a308 | 230 | |
174a4a8c DSH |
231 | Convert a private key to PKCS#8 using a PKCS#5 1.5 compatible algorithm |
232 | (DES): | |
aba3e65f | 233 | |
05dba815 | 234 | openssl pkcs8 -in key.pem -topk8 -v1 PBE-MD5-DES -out enckey.pem |
aba3e65f | 235 | |
525f51f6 DSH |
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 | ||
174a4a8c | 241 | Read a DER unencrypted PKCS#8 format private key: |
aba3e65f | 242 | |
174a4a8c | 243 | openssl pkcs8 -inform DER -nocrypt -in key.der -out key.pem |
aba3e65f | 244 | |
05dba815 | 245 | Convert a private key from any PKCS#8 encrypted format to traditional format: |
aba3e65f | 246 | |
05dba815 | 247 | openssl pkcs8 -in pk8.pem -traditional -out key.pem |
8fc06e88 DSH |
248 | |
249 | Convert a private key to PKCS#8 format, encrypting with AES-256 and with | |
96fc4b72 | 250 | one million iterations of the password: |
251 | ||
05dba815 | 252 | openssl pkcs8 -in key.pem -topk8 -v2 aes-256-cbc -iter 1000000 -out pk8.pem |
aba3e65f | 253 | |
174a4a8c | 254 | =head1 STANDARDS |
aba3e65f | 255 | |
66430207 DSH |
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 | |
8c1cbc72 | 259 | keys produced and therefore, it can be assumed that the PKCS#5 v2.0 |
66430207 DSH |
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: | |
0cd4498b DSH |
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. | |
aba3e65f DSH |
266 | |
267 | =head1 BUGS | |
268 | ||
174a4a8c DSH |
269 | There should be an option that prints out the encryption algorithm |
270 | in use and other details such as the iteration count. | |
271 | ||
aba3e65f DSH |
272 | =head1 SEE ALSO |
273 | ||
b6b66573 DMSP |
274 | L<openssl(1)>, |
275 | L<openssl-dsa(1)>, | |
276 | L<openssl-rsa(1)>, | |
277 | L<openssl-genrsa(1)>, | |
278 | L<openssl-gendsa(1)> | |
aba3e65f | 279 | |
f20bb4eb JW |
280 | =head1 HISTORY |
281 | ||
fc5ecadd | 282 | The B<-iter> option was added in OpenSSL 1.1.0. |
f20bb4eb | 283 | |
0f221d9c P |
284 | The B<-engine> option was deprecated in OpenSSL 3.0. |
285 | ||
e2f92610 RS |
286 | =head1 COPYRIGHT |
287 | ||
da1c088f | 288 | Copyright 2000-2023 The OpenSSL Project Authors. All Rights Reserved. |
e2f92610 | 289 | |
449040b4 | 290 | Licensed under the Apache License 2.0 (the "License"). You may not use |
e2f92610 RS |
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 |