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