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