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