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