xref: /freebsd/crypto/openssl/doc/man1/openssl-pkcs12.pod.in (revision 4c9a0adad18263ec8725d9bfc5f560c6ad1da8bd)
1=pod
2{- OpenSSL::safe::output_do_not_edit_headers(); -}
3
4=head1 NAME
5
6openssl-pkcs12 - PKCS#12 file command
7
8=head1 SYNOPSIS
9
10B<openssl> B<pkcs12>
11[B<-help>]
12[B<-passin> I<arg>]
13[B<-passout> I<arg>]
14[B<-password> I<arg>]
15[B<-twopass>]
16[B<-in> I<filename>|I<uri>]
17[B<-out> I<filename>]
18[B<-nokeys>]
19[B<-nocerts>]
20[B<-noout>]
21[B<-legacy>]
22{- $OpenSSL::safe::opt_engine_synopsis -}{- $OpenSSL::safe::opt_provider_synopsis -}
23{- $OpenSSL::safe::opt_r_synopsis -}
24
25PKCS#12 input (parsing) options:
26[B<-info>]
27[B<-nomacver>]
28[B<-clcerts>]
29[B<-cacerts>]
30
31[B<-aes128>]
32[B<-aes192>]
33[B<-aes256>]
34[B<-aria128>]
35[B<-aria192>]
36[B<-aria256>]
37[B<-camellia128>]
38[B<-camellia192>]
39[B<-camellia256>]
40[B<-des>]
41[B<-des3>]
42[B<-idea>]
43[B<-noenc>]
44[B<-nodes>]
45
46PKCS#12 output (export) options:
47
48[B<-export>]
49[B<-inkey> I<filename>|I<uri>]
50[B<-certfile> I<filename>]
51[B<-passcerts> I<arg>]
52[B<-chain>]
53[B<-untrusted> I<filename>]
54{- $OpenSSL::safe::opt_trust_synopsis -}
55[B<-name> I<name>]
56[B<-caname> I<name>]
57[B<-CSP> I<name>]
58[B<-LMK>]
59[B<-keyex>]
60[B<-keysig>]
61[B<-keypbe> I<cipher>]
62[B<-certpbe> I<cipher>]
63[B<-descert>]
64[B<-macalg> I<digest>]
65[B<-iter> I<count>]
66[B<-noiter>]
67[B<-nomaciter>]
68[B<-maciter>]
69[B<-nomac>]
70
71=head1 DESCRIPTION
72
73This command allows PKCS#12 files (sometimes referred to as
74PFX files) to be created and parsed. PKCS#12 files are used by several
75programs including Netscape, MSIE and MS Outlook.
76
77=head1 OPTIONS
78
79There are a lot of options the meaning of some depends of whether a PKCS#12 file
80is being created or parsed. By default a PKCS#12 file is parsed.
81A PKCS#12 file can be created by using the B<-export> option (see below).
82The PKCS#12 export encryption and MAC options such as B<-certpbe> and B<-iter>
83and many further options such as B<-chain> are relevant only with B<-export>.
84Conversely, the options regarding encryption of private keys when outputting
85PKCS#12 input are relevant only when the B<-export> option is not given.
86
87The default encryption algorithm is AES-256-CBC with PBKDF2 for key derivation.
88
89When encountering problems loading legacy PKCS#12 files that involve,
90for example, RC2-40-CBC,
91try using the B<-legacy> option and, if needed, the B<-provider-path> option.
92
93=over 4
94
95=item B<-help>
96
97Print out a usage message.
98
99=item B<-passin> I<arg>
100
101The password source for the input, and for encrypting any private keys that
102are output.
103For more information about the format of B<arg>
104see L<openssl-passphrase-options(1)>.
105
106=item B<-passout> I<arg>
107
108The password source for output files.
109
110=item B<-password> I<arg>
111
112With B<-export>, B<-password> is equivalent to B<-passout>,
113otherwise it is equivalent to B<-passin>.
114
115=item B<-twopass>
116
117Prompt for separate integrity and encryption passwords: most software
118always assumes these are the same so this option will render such
119PKCS#12 files unreadable. Cannot be used in combination with the options
120B<-password>, B<-passin> if importing from PKCS#12, or B<-passout> if exporting.
121
122=item B<-nokeys>
123
124No private keys will be output.
125
126=item B<-nocerts>
127
128No certificates will be output.
129
130=item B<-noout>
131
132This option inhibits all credentials output,
133and so the input is just verified.
134
135=item B<-legacy>
136
137Use legacy mode of operation and automatically load the legacy provider.
138If OpenSSL is not installed system-wide,
139it is necessary to also use, for example, C<-provider-path ./providers>
140or to set the environment variable B<OPENSSL_MODULES>
141to point to the directory where the providers can be found.
142
143In the legacy mode, the default algorithm for certificate encryption
144is RC2_CBC or 3DES_CBC depending on whether the RC2 cipher is enabled
145in the build. The default algorithm for private key encryption is 3DES_CBC.
146If the legacy option is not specified, then the legacy provider is not loaded
147and the default encryption algorithm for both certificates and private keys is
148AES_256_CBC with PBKDF2 for key derivation.
149
150{- $OpenSSL::safe::opt_engine_item -}
151
152{- $OpenSSL::safe::opt_provider_item -}
153
154{- $OpenSSL::safe::opt_r_item -}
155
156=back
157
158=head2 PKCS#12 input (parsing) options
159
160=over 4
161
162=item B<-in> I<filename>|I<uri>
163
164This specifies the input filename or URI.
165Standard input is used by default.
166Without the B<-export> option this must be PKCS#12 file to be parsed.
167For use with the B<-export> option
168see the L</PKCS#12 output (export) options> section.
169
170=item B<-out> I<filename>
171
172The filename to write certificates and private keys to, standard output by
173default.  They are all written in PEM format.
174
175=item B<-info>
176
177Output additional information about the PKCS#12 file structure, algorithms
178used and iteration counts.
179
180=item B<-nomacver>
181
182Don't attempt to verify the integrity MAC.
183
184=item B<-clcerts>
185
186Only output client certificates (not CA certificates).
187
188=item B<-cacerts>
189
190Only output CA certificates (not client certificates).
191
192=item B<-aes128>, B<-aes192>, B<-aes256>
193
194Use AES to encrypt private keys before outputting.
195
196=item B<-aria128>, B<-aria192>, B<-aria256>
197
198Use ARIA to encrypt private keys before outputting.
199
200=item B<-camellia128>, B<-camellia192>, B<-camellia256>
201
202Use Camellia to encrypt private keys before outputting.
203
204=item B<-des>
205
206Use DES to encrypt private keys before outputting.
207
208=item B<-des3>
209
210Use triple DES to encrypt private keys before outputting.
211
212=item B<-idea>
213
214Use IDEA to encrypt private keys before outputting.
215
216=item B<-noenc>
217
218Don't encrypt private keys at all.
219
220=item B<-nodes>
221
222This option is deprecated since OpenSSL 3.0; use B<-noenc> instead.
223
224=back
225
226=head2 PKCS#12 output (export) options
227
228=over 4
229
230=item B<-export>
231
232This option specifies that a PKCS#12 file will be created rather than
233parsed.
234
235=item B<-out> I<filename>
236
237This specifies filename to write the PKCS#12 file to. Standard output is used
238by default.
239
240=item B<-in> I<filename>|I<uri>
241
242This specifies the input filename or URI.
243Standard input is used by default.
244With the B<-export> option this is a file with certificates and a key,
245or a URI that refers to a key accessed via an engine.
246The order of credentials in a file doesn't matter but one private key and
247its corresponding certificate should be present. If additional
248certificates are present they will also be included in the PKCS#12 output file.
249
250=item B<-inkey> I<filename>|I<uri>
251
252The private key input for PKCS12 output.
253If this option is not specified then the input file (B<-in> argument) must
254contain a private key.
255If no engine is used, the argument is taken as a file.
256If the B<-engine> option is used or the URI has prefix C<org.openssl.engine:>
257then the rest of the URI is taken as key identifier for the given engine.
258
259=item B<-certfile> I<filename>
260
261An input file with extra certificates to be added to the PKCS#12 output
262if the B<-export> option is given.
263
264=item B<-passcerts> I<arg>
265
266The password source for certificate input such as B<-certfile>
267and B<-untrusted>.
268For more information about the format of B<arg> see
269L<openssl-passphrase-options(1)>.
270
271=item B<-chain>
272
273If this option is present then the certificate chain of the end entity
274certificate is built and included in the PKCS#12 output file.
275The end entity certificate is the first one read from the B<-in> file
276if no key is given, else the first certificate matching the given key.
277The standard CA trust store is used for chain building,
278as well as any untrusted CA certificates given with the B<-untrusted> option.
279
280=item B<-untrusted> I<filename>
281
282An input file of untrusted certificates that may be used
283for chain building, which is relevant only when a PKCS#12 file is created
284with the B<-export> option and the B<-chain> option is given as well.
285Any certificates that are actually part of the chain are added to the output.
286
287{- $OpenSSL::safe::opt_trust_item -}
288
289=item B<-name> I<friendlyname>
290
291This specifies the "friendly name" for the certificates and private key. This
292name is typically displayed in list boxes by software importing the file.
293
294=item B<-caname> I<friendlyname>
295
296This specifies the "friendly name" for other certificates. This option may be
297used multiple times to specify names for all certificates in the order they
298appear. Netscape ignores friendly names on other certificates whereas MSIE
299displays them.
300
301=item B<-CSP> I<name>
302
303Write I<name> as a Microsoft CSP name.
304The password source for the input, and for encrypting any private keys that
305are output.
306For more information about the format of B<arg>
307see L<openssl-passphrase-options(1)>.
308
309=item B<-LMK>
310
311Add the "Local Key Set" identifier to the attributes.
312
313=item B<-keyex>|B<-keysig>
314
315Specifies that the private key is to be used for key exchange or just signing.
316This option is only interpreted by MSIE and similar MS software. Normally
317"export grade" software will only allow 512 bit RSA keys to be used for
318encryption purposes but arbitrary length keys for signing. The B<-keysig>
319option marks the key for signing only. Signing only keys can be used for
320S/MIME signing, authenticode (ActiveX control signing)  and SSL client
321authentication, however, due to a bug only MSIE 5.0 and later support
322the use of signing only keys for SSL client authentication.
323
324=item B<-keypbe> I<alg>, B<-certpbe> I<alg>
325
326These options allow the algorithm used to encrypt the private key and
327certificates to be selected. Any PKCS#5 v1.5 or PKCS#12 PBE algorithm name
328can be used (see L</NOTES> section for more information). If a cipher name
329(as output by C<openssl list -cipher-algorithms>) is specified then it
330is used with PKCS#5 v2.0. For interoperability reasons it is advisable to only
331use PKCS#12 algorithms.
332
333Special value C<NONE> disables encryption of the private key and certificates.
334
335=item B<-descert>
336
337Encrypt the certificates using triple DES. By default the private
338key and the certificates are encrypted using AES-256-CBC unless
339the '-legacy' option is used. If '-descert' is used with the '-legacy'
340then both, the private key and the certificates are encrypted using triple DES.
341
342=item B<-macalg> I<digest>
343
344Specify the MAC digest algorithm. If not included SHA256 will be used.
345
346=item B<-iter> I<count>
347
348This option specifies the iteration count for the encryption key and MAC. The
349default value is 2048.
350
351To discourage attacks by using large dictionaries of common passwords the
352algorithm that derives keys from passwords can have an iteration count applied
353to it: this causes a certain part of the algorithm to be repeated and slows it
354down. The MAC is used to check the file integrity but since it will normally
355have the same password as the keys and certificates it could also be attacked.
356
357=item B<-noiter>, B<-nomaciter>
358
359By default both encryption and MAC iteration counts are set to 2048, using
360these options the MAC and encryption iteration counts can be set to 1, since
361this reduces the file security you should not use these options unless you
362really have to. Most software supports both MAC and encryption iteration counts.
363MSIE 4.0 doesn't support MAC iteration counts so it needs the B<-nomaciter>
364option.
365
366=item B<-maciter>
367
368This option is included for compatibility with previous versions, it used
369to be needed to use MAC iterations counts but they are now used by default.
370
371=item B<-nomac>
372
373Do not attempt to provide the MAC integrity. This can be useful with the FIPS
374provider as the PKCS12 MAC requires PKCS12KDF which is not an approved FIPS
375algorithm and cannot be supported by the FIPS provider.
376
377=back
378
379=head1 NOTES
380
381Although there are a large number of options most of them are very rarely
382used. For PKCS#12 file parsing only B<-in> and B<-out> need to be used
383for PKCS#12 file creation B<-export> and B<-name> are also used.
384
385If none of the B<-clcerts>, B<-cacerts> or B<-nocerts> options are present
386then all certificates will be output in the order they appear in the input
387PKCS#12 files. There is no guarantee that the first certificate present is
388the one corresponding to the private key.
389Certain software which tries to get a private key and the corresponding
390certificate might assume that the first certificate in the file is the one
391corresponding to the private key, but that may not always be the case.
392Using the B<-clcerts> option will solve this problem by only
393outputting the certificate corresponding to the private key. If the CA
394certificates are required then they can be output to a separate file using
395the B<-nokeys> B<-cacerts> options to just output CA certificates.
396
397The B<-keypbe> and B<-certpbe> algorithms allow the precise encryption
398algorithms for private keys and certificates to be specified. Normally
399the defaults are fine but occasionally software can't handle triple DES
400encrypted private keys, then the option B<-keypbe> I<PBE-SHA1-RC2-40> can
401be used to reduce the private key encryption to 40 bit RC2. A complete
402description of all algorithms is contained in L<openssl-pkcs8(1)>.
403
404Prior 1.1 release passwords containing non-ASCII characters were encoded
405in non-compliant manner, which limited interoperability, in first hand
406with Windows. But switching to standard-compliant password encoding
407poses problem accessing old data protected with broken encoding. For
408this reason even legacy encodings is attempted when reading the
409data. If you use PKCS#12 files in production application you are advised
410to convert the data, because implemented heuristic approach is not
411MT-safe, its sole goal is to facilitate the data upgrade with this
412command.
413
414=head1 EXAMPLES
415
416Parse a PKCS#12 file and output it to a PEM file:
417
418 openssl pkcs12 -in file.p12 -out file.pem
419
420Output only client certificates to a file:
421
422 openssl pkcs12 -in file.p12 -clcerts -out file.pem
423
424Don't encrypt the private key:
425
426 openssl pkcs12 -in file.p12 -out file.pem -noenc
427
428Print some info about a PKCS#12 file:
429
430 openssl pkcs12 -in file.p12 -info -noout
431
432Print some info about a PKCS#12 file in legacy mode:
433
434 openssl pkcs12 -in file.p12 -info -noout -legacy
435
436Create a PKCS#12 file from a PEM file that may contain a key and certificates:
437
438 openssl pkcs12 -export -in file.pem -out file.p12 -name "My PSE"
439
440Include some extra certificates:
441
442 openssl pkcs12 -export -in file.pem -out file.p12 -name "My PSE" \
443  -certfile othercerts.pem
444
445Export a PKCS#12 file with data from a certificate PEM file and from a further
446PEM file containing a key, with default algorithms as in the legacy provider:
447
448 openssl pkcs12 -export -in cert.pem -inkey key.pem -out file.p12 -legacy
449
450=head1 SEE ALSO
451
452L<openssl(1)>,
453L<openssl-pkcs8(1)>,
454L<ossl_store-file(7)>
455
456=head1 HISTORY
457
458The B<-engine> option was deprecated in OpenSSL 3.0.
459The B<-nodes> option was deprecated in OpenSSL 3.0, too; use B<-noenc> instead.
460
461=head1 COPYRIGHT
462
463Copyright 2000-2022 The OpenSSL Project Authors. All Rights Reserved.
464
465Licensed under the Apache License 2.0 (the "License").  You may not use
466this file except in compliance with the License.  You can obtain a copy
467in the file LICENSE in the source distribution or at
468L<https://www.openssl.org/source/license.html>.
469
470=cut
471