]>
Commit | Line | Data |
---|---|---|
dad666fb DSH |
1 | |
2 | =pod | |
3 | ||
4 | =head1 NAME | |
5 | ||
6 | pkcs12 - PKCS#12 file utility | |
7 | ||
8 | =head1 SYNOPSIS | |
9 | ||
10 | B<openssl> B<pkcs12> | |
c3ed3b6e DSH |
11 | [B<-export>] |
12 | [B<-chain>] | |
13 | [B<-inkey filename>] | |
14 | [B<-certfile filename>] | |
15 | [B<-name name>] | |
16 | [B<-caname name>] | |
17 | [B<-in filename>] | |
18 | [B<-out filename>] | |
19 | [B<-noout>] | |
20 | [B<-nomacver>] | |
21 | [B<-nocerts>] | |
22 | [B<-clcerts>] | |
23 | [B<-cacerts>] | |
24 | [B<-nokeys>] | |
25 | [B<-info>] | |
ec1edeb5 | 26 | [B<-des | -des3 | -idea | -aes128 | -aes192 | -aes256 | -camellia128 | -camellia192 | -camellia256 | -nodes>] |
c3ed3b6e | 27 | [B<-noiter>] |
ec1edeb5 | 28 | [B<-maciter | -nomaciter | -nomac>] |
c3ed3b6e DSH |
29 | [B<-twopass>] |
30 | [B<-descert>] | |
ec1edeb5 NL |
31 | [B<-certpbe cipher>] |
32 | [B<-keypbe cipher>] | |
33 | [B<-macalg digest>] | |
c3ed3b6e DSH |
34 | [B<-keyex>] |
35 | [B<-keysig>] | |
a3fe382e DSH |
36 | [B<-password arg>] |
37 | [B<-passin arg>] | |
38 | [B<-passout arg>] | |
d13e4eb0 | 39 | [B<-rand file(s)>] |
ec1edeb5 NL |
40 | [B<-CAfile file>] |
41 | [B<-CApath dir>] | |
42 | [B<-CSP name>] | |
dad666fb DSH |
43 | |
44 | =head1 DESCRIPTION | |
45 | ||
46 | The B<pkcs12> command allows PKCS#12 files (sometimes referred to as | |
47 | PFX files) to be created and parsed. PKCS#12 files are used by several | |
ef7eaa4c | 48 | programs including Netscape, MSIE and MS Outlook. |
dad666fb DSH |
49 | |
50 | =head1 COMMAND OPTIONS | |
51 | ||
52 | There are a lot of options the meaning of some depends of whether a PKCS#12 file | |
6264c9b2 | 53 | is being created or parsed. By default a PKCS#12 file is parsed. A PKCS#12 |
dad666fb DSH |
54 | file can be created by using the B<-export> option (see below). |
55 | ||
56 | =head1 PARSING OPTIONS | |
57 | ||
58 | =over 4 | |
59 | ||
60 | =item B<-in filename> | |
61 | ||
62 | This specifies filename of the PKCS#12 file to be parsed. Standard input is used | |
63 | by default. | |
64 | ||
65 | =item B<-out filename> | |
66 | ||
112161bd DSH |
67 | The filename to write certificates and private keys to, standard output by |
68 | default. They are all written in PEM format. | |
dad666fb | 69 | |
856c6dfb | 70 | =item B<-passin arg> |
dad666fb | 71 | |
112161bd DSH |
72 | the PKCS#12 file (i.e. input file) password source. For more information about |
73 | the format of B<arg> see the B<PASS PHRASE ARGUMENTS> section in | |
9b86974e | 74 | L<openssl(1)>. |
dad666fb | 75 | |
a3fe382e | 76 | =item B<-passout arg> |
dad666fb | 77 | |
2b4ffc65 | 78 | pass phrase source to encrypt any outputted private keys with. For more |
112161bd | 79 | information about the format of B<arg> see the B<PASS PHRASE ARGUMENTS> section |
9b86974e | 80 | in L<openssl(1)>. |
f07fb9b2 | 81 | |
856c6dfb SS |
82 | =item B<-password arg> |
83 | ||
84 | With -export, -password is equivalent to -passout. | |
85 | Otherwise, -password is equivalent to -passin. | |
86 | ||
dad666fb DSH |
87 | =item B<-noout> |
88 | ||
112161bd DSH |
89 | this option inhibits output of the keys and certificates to the output file |
90 | version of the PKCS#12 file. | |
dad666fb DSH |
91 | |
92 | =item B<-clcerts> | |
93 | ||
94 | only output client certificates (not CA certificates). | |
95 | ||
96 | =item B<-cacerts> | |
97 | ||
98 | only output CA certificates (not client certificates). | |
99 | ||
100 | =item B<-nocerts> | |
101 | ||
102 | no certificates at all will be output. | |
103 | ||
104 | =item B<-nokeys> | |
105 | ||
106 | no private keys will be output. | |
107 | ||
108 | =item B<-info> | |
109 | ||
110 | output additional information about the PKCS#12 file structure, algorithms used and | |
111 | iteration counts. | |
112 | ||
113 | =item B<-des> | |
114 | ||
115 | use DES to encrypt private keys before outputting. | |
116 | ||
117 | =item B<-des3> | |
118 | ||
119 | use triple DES to encrypt private keys before outputting, this is the default. | |
120 | ||
121 | =item B<-idea> | |
122 | ||
123 | use IDEA to encrypt private keys before outputting. | |
124 | ||
ec1edeb5 NL |
125 | =item B<-aes128>, B<-aes192>, B<-aes256> |
126 | ||
127 | use AES to encrypt private keys before outputting. | |
128 | ||
129 | =item B<-camellia128>, B<-camellia192>, B<-camellia256> | |
130 | ||
131 | use Camellia to encrypt private keys before outputting. | |
132 | ||
dad666fb DSH |
133 | =item B<-nodes> |
134 | ||
135 | don't encrypt the private keys at all. | |
136 | ||
137 | =item B<-nomacver> | |
138 | ||
139 | don't attempt to verify the integrity MAC before reading the file. | |
140 | ||
141 | =item B<-twopass> | |
142 | ||
143 | prompt for separate integrity and encryption passwords: most software | |
144 | always assumes these are the same so this option will render such | |
145 | PKCS#12 files unreadable. | |
146 | ||
147 | =back | |
148 | ||
149 | =head1 FILE CREATION OPTIONS | |
150 | ||
151 | =over 4 | |
152 | ||
153 | =item B<-export> | |
154 | ||
155 | This option specifies that a PKCS#12 file will be created rather than | |
156 | parsed. | |
157 | ||
158 | =item B<-out filename> | |
159 | ||
160 | This specifies filename to write the PKCS#12 file to. Standard output is used | |
161 | by default. | |
162 | ||
163 | =item B<-in filename> | |
164 | ||
112161bd DSH |
165 | The filename to read certificates and private keys from, standard input by |
166 | default. They must all be in PEM format. The order doesn't matter but one | |
167 | private key and its corresponding certificate should be present. If additional | |
168 | certificates are present they will also be included in the PKCS#12 file. | |
dad666fb DSH |
169 | |
170 | =item B<-inkey filename> | |
171 | ||
172 | file to read private key from. If not present then a private key must be present | |
173 | in the input file. | |
174 | ||
175 | =item B<-name friendlyname> | |
176 | ||
112161bd DSH |
177 | This specifies the "friendly name" for the certificate and private key. This |
178 | name is typically displayed in list boxes by software importing the file. | |
dad666fb DSH |
179 | |
180 | =item B<-certfile filename> | |
181 | ||
182 | A filename to read additional certificates from. | |
183 | ||
184 | =item B<-caname friendlyname> | |
185 | ||
186 | This specifies the "friendly name" for other certificates. This option may be | |
187 | used multiple times to specify names for all certificates in the order they | |
188 | appear. Netscape ignores friendly names on other certificates whereas MSIE | |
189 | displays them. | |
190 | ||
a3fe382e | 191 | =item B<-pass arg>, B<-passout arg> |
dad666fb | 192 | |
a3fe382e DSH |
193 | the PKCS#12 file (i.e. output file) password source. For more information about |
194 | the format of B<arg> see the B<PASS PHRASE ARGUMENTS> section in | |
9b86974e | 195 | L<openssl(1)>. |
dad666fb | 196 | |
f07fb9b2 DSH |
197 | =item B<-passin password> |
198 | ||
a3fe382e DSH |
199 | pass phrase source to decrypt any input private keys with. For more information |
200 | about the format of B<arg> see the B<PASS PHRASE ARGUMENTS> section in | |
9b86974e | 201 | L<openssl(1)>. |
f07fb9b2 | 202 | |
dad666fb DSH |
203 | =item B<-chain> |
204 | ||
205 | if this option is present then an attempt is made to include the entire | |
206 | certificate chain of the user certificate. The standard CA store is used | |
207 | for this search. If the search fails it is considered a fatal error. | |
208 | ||
209 | =item B<-descert> | |
210 | ||
211 | encrypt the certificate using triple DES, this may render the PKCS#12 | |
212 | file unreadable by some "export grade" software. By default the private | |
213 | key is encrypted using triple DES and the certificate using 40 bit RC2. | |
214 | ||
215 | =item B<-keypbe alg>, B<-certpbe alg> | |
216 | ||
217 | these options allow the algorithm used to encrypt the private key and | |
112161bd | 218 | certificates to be selected. Any PKCS#5 v1.5 or PKCS#12 PBE algorithm name |
740ceb5b | 219 | can be used (see B<NOTES> section for more information). If a cipher name |
112161bd DSH |
220 | (as output by the B<list-cipher-algorithms> command is specified then it |
221 | is used with PKCS#5 v2.0. For interoperability reasons it is advisable to only | |
222 | use PKCS#12 algorithms. | |
dad666fb DSH |
223 | |
224 | =item B<-keyex|-keysig> | |
225 | ||
226 | specifies that the private key is to be used for key exchange or just signing. | |
227 | This option is only interpreted by MSIE and similar MS software. Normally | |
228 | "export grade" software will only allow 512 bit RSA keys to be used for | |
229 | encryption purposes but arbitrary length keys for signing. The B<-keysig> | |
230 | option marks the key for signing only. Signing only keys can be used for | |
231 | S/MIME signing, authenticode (ActiveX control signing) and SSL client | |
232 | authentication, however due to a bug only MSIE 5.0 and later support | |
233 | the use of signing only keys for SSL client authentication. | |
234 | ||
112161bd DSH |
235 | =item B<-macalg digest> |
236 | ||
237 | specify the MAC digest algorithm. If not included them SHA1 will be used. | |
238 | ||
dad666fb DSH |
239 | =item B<-nomaciter>, B<-noiter> |
240 | ||
241 | these options affect the iteration counts on the MAC and key algorithms. | |
242 | Unless you wish to produce files compatible with MSIE 4.0 you should leave | |
243 | these options alone. | |
244 | ||
245 | To discourage attacks by using large dictionaries of common passwords the | |
246 | algorithm that derives keys from passwords can have an iteration count applied | |
247 | to it: this causes a certain part of the algorithm to be repeated and slows it | |
248 | down. The MAC is used to check the file integrity but since it will normally | |
249 | have the same password as the keys and certificates it could also be attacked. | |
250 | By default both MAC and encryption iteration counts are set to 2048, using | |
251 | these options the MAC and encryption iteration counts can be set to 1, since | |
252 | this reduces the file security you should not use these options unless you | |
253 | really have to. Most software supports both MAC and key iteration counts. | |
254 | MSIE 4.0 doesn't support MAC iteration counts so it needs the B<-nomaciter> | |
255 | option. | |
256 | ||
257 | =item B<-maciter> | |
258 | ||
259 | This option is included for compatibility with previous versions, it used | |
260 | to be needed to use MAC iterations counts but they are now used by default. | |
261 | ||
ec1edeb5 NL |
262 | =item B<-nomac> |
263 | ||
264 | don't attempt to provide the MAC integrity. | |
265 | ||
d13e4eb0 DSH |
266 | =item B<-rand file(s)> |
267 | ||
268 | a file or files containing random data used to seed the random number | |
9b86974e | 269 | generator, or an EGD socket (see L<RAND_egd(3)>). |
a4cfd178 | 270 | Multiple files can be specified separated by a OS-dependent character. |
b87ef946 | 271 | The separator is B<;> for MS-Windows, B<,> for OpenVMS, and B<:> for |
a4cfd178 | 272 | all others. |
d13e4eb0 | 273 | |
ec1edeb5 NL |
274 | =item B<-CAfile file> |
275 | ||
276 | CA storage as a file. | |
277 | ||
278 | =item B<-CApath dir> | |
279 | ||
280 | CA storage as a directory. This directory must be a standard certificate | |
281 | directory: that is a hash of each subject name (using B<x509 -hash>) should be | |
282 | linked to each certificate. | |
283 | ||
284 | =item B<-CSP name> | |
285 | ||
286 | write B<name> as a Microsoft CSP name. | |
287 | ||
dad666fb DSH |
288 | =back |
289 | ||
290 | =head1 NOTES | |
291 | ||
292 | Although there are a large number of options most of them are very rarely | |
293 | used. For PKCS#12 file parsing only B<-in> and B<-out> need to be used | |
294 | for PKCS#12 file creation B<-export> and B<-name> are also used. | |
295 | ||
0cd4498b DSH |
296 | If none of the B<-clcerts>, B<-cacerts> or B<-nocerts> options are present |
297 | then all certificates will be output in the order they appear in the input | |
298 | PKCS#12 files. There is no guarantee that the first certificate present is | |
299 | the one corresponding to the private key. Certain software which requires | |
300 | a private key and certificate and assumes the first certificate in the | |
301 | file is the one corresponding to the private key: this may not always | |
302 | be the case. Using the B<-clcerts> option will solve this problem by only | |
3b80e3aa | 303 | outputting the certificate corresponding to the private key. If the CA |
0cd4498b DSH |
304 | certificates are required then they can be output to a separate file using |
305 | the B<-nokeys -cacerts> options to just output CA certificates. | |
306 | ||
dad666fb DSH |
307 | The B<-keypbe> and B<-certpbe> algorithms allow the precise encryption |
308 | algorithms for private keys and certificates to be specified. Normally | |
309 | the defaults are fine but occasionally software can't handle triple DES | |
310 | encrypted private keys, then the option B<-keypbe PBE-SHA1-RC2-40> can | |
311 | be used to reduce the private key encryption to 40 bit RC2. A complete | |
312 | description of all algorithms is contained in the B<pkcs8> manual page. | |
313 | ||
314 | =head1 EXAMPLES | |
315 | ||
316 | Parse a PKCS#12 file and output it to a file: | |
317 | ||
318 | openssl pkcs12 -in file.p12 -out file.pem | |
319 | ||
320 | Output only client certificates to a file: | |
321 | ||
322 | openssl pkcs12 -in file.p12 -clcerts -out file.pem | |
323 | ||
324 | Don't encrypt the private key: | |
325 | ||
326 | openssl pkcs12 -in file.p12 -out file.pem -nodes | |
327 | ||
328 | Print some info about a PKCS#12 file: | |
329 | ||
330 | openssl pkcs12 -in file.p12 -info -noout | |
331 | ||
332 | Create a PKCS#12 file: | |
333 | ||
334 | openssl pkcs12 -export -in file.pem -out file.p12 -name "My Certificate" | |
335 | ||
336 | Include some extra certificates: | |
337 | ||
338 | openssl pkcs12 -export -in file.pem -out file.p12 -name "My Certificate" \ | |
339 | -certfile othercerts.pem | |
340 | ||
341 | =head1 BUGS | |
342 | ||
343 | Some would argue that the PKCS#12 standard is one big bug :-) | |
344 | ||
02ee8626 DSH |
345 | Versions of OpenSSL before 0.9.6a had a bug in the PKCS#12 key generation |
346 | routines. Under rare circumstances this could produce a PKCS#12 file encrypted | |
347 | with an invalid key. As a result some PKCS#12 files which triggered this bug | |
348 | from other implementations (MSIE or Netscape) could not be decrypted | |
349 | by OpenSSL and similarly OpenSSL could produce PKCS#12 files which could | |
350 | not be decrypted by other implementations. The chances of producing such | |
351 | a file are relatively small: less than 1 in 256. | |
352 | ||
353 | A side effect of fixing this bug is that any old invalidly encrypted PKCS#12 | |
354 | files cannot no longer be parsed by the fixed version. Under such circumstances | |
355 | the B<pkcs12> utility will report that the MAC is OK but fail with a decryption | |
356 | error when extracting private keys. | |
357 | ||
358 | This problem can be resolved by extracting the private keys and certificates | |
359 | from the PKCS#12 file using an older version of OpenSSL and recreating the PKCS#12 | |
360 | file from the keys and certificates using a newer version of OpenSSL. For example: | |
361 | ||
362 | old-openssl -in bad.p12 -out keycerts.pem | |
363 | openssl -in keycerts.pem -export -name "My PKCS#12 file" -out fixed.p12 | |
364 | ||
dad666fb DSH |
365 | =head1 SEE ALSO |
366 | ||
9b86974e | 367 | L<pkcs8(1)> |
dad666fb | 368 |