]>
Commit | Line | Data |
---|---|---|
aba3e65f DSH |
1 | =pod |
2 | ||
3 | =head1 NAME | |
4 | ||
174a4a8c | 5 | pkcs8 - PKCS#8 format private key conversion tool |
aba3e65f DSH |
6 | |
7 | =head1 SYNOPSIS | |
8 | ||
9 | B<openssl> B<pkcs8> | |
10 | [B<-topk8>] | |
11 | [B<-inform PEM|DER>] | |
12 | [B<-outform PEM|DER>] | |
13 | [B<-in filename>] | |
a3fe382e | 14 | [B<-passin arg>] |
aba3e65f | 15 | [B<-out filename>] |
a3fe382e | 16 | [B<-passout arg>] |
96fc4b72 | 17 | [B<-iter count>] |
aba3e65f DSH |
18 | [B<-noiter>] |
19 | [B<-nocrypt>] | |
20 | [B<-nooct>] | |
66430207 DSH |
21 | [B<-embed>] |
22 | [B<-nsdb>] | |
aba3e65f | 23 | [B<-v2 alg>] |
5693a308 | 24 | [B<-v2prf alg>] |
525f51f6 | 25 | [B<-v1 alg>] |
bfa35550 | 26 | [B<-engine id>] |
0ceb8b74 DSH |
27 | [B<-scrypt>] |
28 | [B<-scrypt_N N>] | |
29 | [B<-scrypt_r r>] | |
30 | [B<-scrypt_p p>] | |
aba3e65f DSH |
31 | |
32 | =head1 DESCRIPTION | |
33 | ||
34 | The B<pkcs8> command processes private keys in PKCS#8 format. It can handle | |
35 | both unencrypted PKCS#8 PrivateKeyInfo format and EncryptedPrivateKeyInfo | |
36 | format with a variety of PKCS#5 (v1.5 and v2.0) and PKCS#12 algorithms. | |
37 | ||
38 | =head1 COMMAND OPTIONS | |
39 | ||
40 | =over 4 | |
41 | ||
42 | =item B<-topk8> | |
43 | ||
174a4a8c | 44 | Normally a PKCS#8 private key is expected on input and a traditional format |
aba3e65f DSH |
45 | private key will be written. With the B<-topk8> option the situation is |
46 | reversed: it reads a traditional format private key and writes a PKCS#8 | |
47 | format key. | |
48 | ||
49 | =item B<-inform DER|PEM> | |
50 | ||
51 | This specifies the input format. If a PKCS#8 format key is expected on input | |
52 | then either a B<DER> or B<PEM> encoded version of a PKCS#8 key will be | |
174a4a8c | 53 | expected. Otherwise the B<DER> or B<PEM> format of the traditional format |
aba3e65f DSH |
54 | private key is used. |
55 | ||
174a4a8c | 56 | =item B<-outform DER|PEM> |
aba3e65f DSH |
57 | |
58 | This specifies the output format, the options have the same meaning as the | |
59 | B<-inform> option. | |
60 | ||
61 | =item B<-in filename> | |
62 | ||
63 | This specifies the input filename to read a key from or standard input if this | |
64 | option is not specified. If the key is encrypted a pass phrase will be | |
65 | prompted for. | |
66 | ||
a3fe382e | 67 | =item B<-passin arg> |
20432eae | 68 | |
a3fe382e | 69 | the input file password source. For more information about the format of B<arg> |
9b86974e | 70 | see the B<PASS PHRASE ARGUMENTS> section in L<openssl(1)>. |
20432eae | 71 | |
aba3e65f DSH |
72 | =item B<-out filename> |
73 | ||
74 | This specifies the output filename to write a key to or standard output by | |
174a4a8c | 75 | default. If any encryption options are set then a pass phrase will be |
aba3e65f DSH |
76 | prompted for. The output filename should B<not> be the same as the input |
77 | filename. | |
78 | ||
a3fe382e | 79 | =item B<-passout arg> |
20432eae | 80 | |
a3fe382e | 81 | the output file password source. For more information about the format of B<arg> |
9b86974e | 82 | see the B<PASS PHRASE ARGUMENTS> section in L<openssl(1)>. |
20432eae | 83 | |
96fc4b72 | 84 | =item B<-iter count> |
85 | ||
f20bb4eb JW |
86 | When creating new PKCS#8 containers, use a given number of iterations on |
87 | the password in deriving the encryption key for the PKCS#8 output. | |
88 | High values increase the time required to brute-force a PKCS#8 container. | |
96fc4b72 | 89 | |
174a4a8c | 90 | =item B<-nocrypt> |
aba3e65f | 91 | |
174a4a8c DSH |
92 | PKCS#8 keys generated or input are normally PKCS#8 EncryptedPrivateKeyInfo |
93 | structures using an appropriate password based encryption algorithm. With | |
94 | this option an unencrypted PrivateKeyInfo structure is expected or output. | |
95 | This option does not encrypt private keys at all and should only be used | |
96 | when absolutely necessary. Certain software such as some versions of Java | |
97 | code signing software used unencrypted private keys. | |
aba3e65f | 98 | |
174a4a8c | 99 | =item B<-nooct> |
aba3e65f | 100 | |
66430207 | 101 | This option generates RSA private keys in a broken format that some software |
174a4a8c DSH |
102 | uses. Specifically the private key should be enclosed in a OCTET STRING |
103 | but some software just includes the structure itself without the | |
104 | surrounding OCTET STRING. | |
aba3e65f | 105 | |
66430207 DSH |
106 | =item B<-embed> |
107 | ||
108 | This option generates DSA keys in a broken format. The DSA parameters are | |
109 | embedded inside the PrivateKey structure. In this form the OCTET STRING | |
110 | contains an ASN1 SEQUENCE consisting of two structures: a SEQUENCE containing | |
111 | the parameters and an ASN1 INTEGER containing the private key. | |
112 | ||
113 | =item B<-nsdb> | |
114 | ||
115 | This option generates DSA keys in a broken format compatible with Netscape | |
116 | private key databases. The PrivateKey contains a SEQUENCE consisting of | |
117 | the public and private keys respectively. | |
118 | ||
174a4a8c | 119 | =item B<-v2 alg> |
aba3e65f | 120 | |
174a4a8c DSH |
121 | This option enables the use of PKCS#5 v2.0 algorithms. Normally PKCS#8 |
122 | private keys are encrypted with the password based encryption algorithm | |
123 | called B<pbeWithMD5AndDES-CBC> this uses 56 bit DES encryption but it | |
124 | was the strongest encryption algorithm supported in PKCS#5 v1.5. Using | |
125 | the B<-v2> option PKCS#5 v2.0 algorithms are used which can use any | |
126 | encryption algorithm such as 168 bit triple DES or 128 bit RC2 however | |
127 | not many implementations support PKCS#5 v2.0 yet. If you are just using | |
128 | private keys with OpenSSL then this doesn't matter. | |
aba3e65f | 129 | |
174a4a8c DSH |
130 | The B<alg> argument is the encryption algorithm to use, valid values include |
131 | B<des>, B<des3> and B<rc2>. It is recommended that B<des3> is used. | |
aba3e65f | 132 | |
5693a308 DSH |
133 | =item B<-v2prf alg> |
134 | ||
135 | This option sets the PRF algorithm to use with PKCS#5 v2.0. A typical value | |
136 | values would be B<hmacWithSHA256>. If this option isn't set then the default | |
137 | for the cipher is used or B<hmacWithSHA1> if there is no default. | |
138 | ||
525f51f6 DSH |
139 | =item B<-v1 alg> |
140 | ||
141 | This option specifies a PKCS#5 v1.5 or PKCS#12 algorithm to use. A complete | |
142 | list of possible algorithms is included below. | |
143 | ||
bfa35550 RL |
144 | =item B<-engine id> |
145 | ||
e5fa864f | 146 | specifying an engine (by its unique B<id> string) will cause B<pkcs8> |
bfa35550 RL |
147 | to attempt to obtain a functional reference to the specified engine, |
148 | thus initialising it if needed. The engine will then be set as the default | |
149 | for all available algorithms. | |
150 | ||
0ceb8b74 DSH |
151 | =item B<-scrypt> |
152 | ||
153 | uses the B<scrypt> algorithm for private key encryption using default | |
154 | parameters: currently N=1024, r=8 and p=16 and AES in CBC mode with a 256 bit | |
155 | key. These parameters can be modified using the B<-scrypt_N>, B<-scrypt_r>, | |
156 | B<-scrypt_p> and B<-v2> options. | |
157 | ||
158 | B<-scrypt_N N> B<-scrypt_r r> B<-scrypt_p p> | |
159 | ||
160 | sets the scrypt B<N>, B<r> or B<p> parameters. | |
161 | ||
174a4a8c | 162 | =back |
aba3e65f | 163 | |
174a4a8c | 164 | =head1 NOTES |
aba3e65f | 165 | |
0286d944 DSH |
166 | The encrypted form of a PEM encode PKCS#8 files uses the following |
167 | headers and footers: | |
168 | ||
169 | -----BEGIN ENCRYPTED PRIVATE KEY----- | |
170 | -----END ENCRYPTED PRIVATE KEY----- | |
171 | ||
172 | The unencrypted form uses: | |
173 | ||
174 | -----BEGIN PRIVATE KEY----- | |
175 | -----END PRIVATE KEY----- | |
176 | ||
174a4a8c DSH |
177 | Private keys encrypted using PKCS#5 v2.0 algorithms and high iteration |
178 | counts are more secure that those encrypted using the traditional | |
179 | SSLeay compatible formats. So if additional security is considered | |
180 | important the keys should be converted. | |
aba3e65f | 181 | |
174a4a8c DSH |
182 | The default encryption is only 56 bits because this is the encryption |
183 | that most current implementations of PKCS#8 will support. | |
aba3e65f | 184 | |
174a4a8c DSH |
185 | Some software may use PKCS#12 password based encryption algorithms |
186 | with PKCS#8 format private keys: these are handled automatically | |
187 | but there is no option to produce them. | |
aba3e65f | 188 | |
174a4a8c DSH |
189 | It is possible to write out DER encoded encrypted private keys in |
190 | PKCS#8 format because the encryption details are included at an ASN1 | |
191 | level whereas the traditional format includes them at a PEM level. | |
aba3e65f | 192 | |
525f51f6 DSH |
193 | =head1 PKCS#5 v1.5 and PKCS#12 algorithms. |
194 | ||
195 | Various algorithms can be used with the B<-v1> command line option, | |
196 | including PKCS#5 v1.5 and PKCS#12. These are described in more detail | |
197 | below. | |
198 | ||
199 | =over 4 | |
200 | ||
201 | =item B<PBE-MD2-DES PBE-MD5-DES> | |
202 | ||
203 | These algorithms were included in the original PKCS#5 v1.5 specification. | |
204 | They only offer 56 bits of protection since they both use DES. | |
205 | ||
206 | =item B<PBE-SHA1-RC2-64 PBE-MD2-RC2-64 PBE-MD5-RC2-64 PBE-SHA1-DES> | |
207 | ||
208 | These algorithms are not mentioned in the original PKCS#5 v1.5 specification | |
209 | but they use the same key derivation algorithm and are supported by some | |
c3ed3b6e | 210 | software. They are mentioned in PKCS#5 v2.0. They use either 64 bit RC2 or |
525f51f6 DSH |
211 | 56 bit DES. |
212 | ||
213 | =item B<PBE-SHA1-RC4-128 PBE-SHA1-RC4-40 PBE-SHA1-3DES PBE-SHA1-2DES PBE-SHA1-RC2-128 PBE-SHA1-RC2-40> | |
214 | ||
215 | These algorithms use the PKCS#12 password based encryption algorithm and | |
216 | allow strong encryption algorithms like triple DES or 128 bit RC2 to be used. | |
217 | ||
218 | =back | |
219 | ||
aba3e65f DSH |
220 | =head1 EXAMPLES |
221 | ||
174a4a8c DSH |
222 | Convert a private from traditional to PKCS#5 v2.0 format using triple |
223 | DES: | |
aba3e65f | 224 | |
174a4a8c | 225 | openssl pkcs8 -in key.pem -topk8 -v2 des3 -out enckey.pem |
aba3e65f | 226 | |
5693a308 DSH |
227 | Convert a private from traditional to PKCS#5 v2.0 format using AES with |
228 | 256 bits in CBC mode and B<hmacWithSHA256> PRF: | |
229 | ||
230 | openssl pkcs8 -in key.pem -topk8 -v2 aes-256-cbc -v2prf hmacWithSHA256 -out enckey.pem | |
231 | ||
174a4a8c DSH |
232 | Convert a private key to PKCS#8 using a PKCS#5 1.5 compatible algorithm |
233 | (DES): | |
aba3e65f | 234 | |
174a4a8c | 235 | openssl pkcs8 -in key.pem -topk8 -out enckey.pem |
aba3e65f | 236 | |
525f51f6 DSH |
237 | Convert a private key to PKCS#8 using a PKCS#12 compatible algorithm |
238 | (3DES): | |
239 | ||
240 | openssl pkcs8 -in key.pem -topk8 -out enckey.pem -v1 PBE-SHA1-3DES | |
241 | ||
174a4a8c | 242 | Read a DER unencrypted PKCS#8 format private key: |
aba3e65f | 243 | |
174a4a8c | 244 | openssl pkcs8 -inform DER -nocrypt -in key.der -out key.pem |
aba3e65f | 245 | |
174a4a8c | 246 | Convert a private key from any PKCS#8 format to traditional format: |
aba3e65f | 247 | |
174a4a8c | 248 | openssl pkcs8 -in pk8.pem -out key.pem |
96fc4b72 | 249 | |
250 | Convert a private key to PKCS#8 format, encrypting with AES-256 and with | |
251 | one million iterations of the password: | |
252 | ||
253 | openssl pkcs8 -in raw.pem -topk8 -v2 aes-256-cbc -iter 1000000 -out pk8.pem | |
aba3e65f | 254 | |
174a4a8c | 255 | =head1 STANDARDS |
aba3e65f | 256 | |
66430207 DSH |
257 | Test vectors from this PKCS#5 v2.0 implementation were posted to the |
258 | pkcs-tng mailing list using triple DES, DES and RC2 with high iteration | |
259 | counts, several people confirmed that they could decrypt the private | |
260 | keys produced and Therefore it can be assumed that the PKCS#5 v2.0 | |
261 | implementation is reasonably accurate at least as far as these | |
262 | algorithms are concerned. | |
263 | ||
264 | The format of PKCS#8 DSA (and other) private keys is not well documented: | |
0cd4498b DSH |
265 | it is hidden away in PKCS#11 v2.01, section 11.9. OpenSSL's default DSA |
266 | PKCS#8 private key format complies with this standard. | |
aba3e65f DSH |
267 | |
268 | =head1 BUGS | |
269 | ||
174a4a8c DSH |
270 | There should be an option that prints out the encryption algorithm |
271 | in use and other details such as the iteration count. | |
272 | ||
273 | PKCS#8 using triple DES and PKCS#5 v2.0 should be the default private | |
19d2bb57 | 274 | key format for OpenSSL: for compatibility several of the utilities use |
174a4a8c | 275 | the old format at present. |
aba3e65f DSH |
276 | |
277 | =head1 SEE ALSO | |
278 | ||
9b86974e RS |
279 | L<dsa(1)>, L<rsa(1)>, L<genrsa(1)>, |
280 | L<gendsa(1)> | |
aba3e65f | 281 | |
f20bb4eb JW |
282 | =head1 HISTORY |
283 | ||
284 | The B<-iter> option was added to OpenSSL 1.1.0. | |
285 | ||
aba3e65f | 286 | =cut |