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