Regenerate the manual pages after the OpenSSL update to 0.9.7e.
[dragonfly.git] / secure / usr.bin / openssl / man / pkcs12.1
CommitLineData
8b0cefbb
JR
1.\" Automatically generated by Pod::Man v1.37, Pod::Parser v1.14
2.\"
3.\" Standard preamble:
4.\" ========================================================================
5.de Sh \" Subsection heading
984263bc
MD
6.br
7.if t .Sp
8.ne 5
9.PP
10\fB\\$1\fR
11.PP
12..
8b0cefbb 13.de Sp \" Vertical space (when we can't use .PP)
984263bc
MD
14.if t .sp .5v
15.if n .sp
16..
8b0cefbb 17.de Vb \" Begin verbatim text
984263bc
MD
18.ft CW
19.nf
20.ne \\$1
21..
8b0cefbb 22.de Ve \" End verbatim text
984263bc 23.ft R
984263bc
MD
24.fi
25..
8b0cefbb
JR
26.\" Set up some character translations and predefined strings. \*(-- will
27.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
28.\" double quote, and \*(R" will give a right double quote. | will give a
29.\" real vertical bar. \*(C+ will give a nicer C++. Capital omega is used to
30.\" do unbreakable dashes and therefore won't be available. \*(C` and \*(C'
31.\" expand to `' in nroff, nothing in troff, for use with C<>.
984263bc 32.tr \(*W-|\(bv\*(Tr
8b0cefbb 33.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
984263bc 34.ie n \{\
8b0cefbb
JR
35. ds -- \(*W-
36. ds PI pi
37. if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
38. if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch
39. ds L" ""
40. ds R" ""
41. ds C` ""
42. ds C' ""
984263bc
MD
43'br\}
44.el\{\
8b0cefbb
JR
45. ds -- \|\(em\|
46. ds PI \(*p
47. ds L" ``
48. ds R" ''
984263bc 49'br\}
8b0cefbb
JR
50.\"
51.\" If the F register is turned on, we'll generate index entries on stderr for
52.\" titles (.TH), headers (.SH), subsections (.Sh), items (.Ip), and index
53.\" entries marked with X<> in POD. Of course, you'll have to process the
54.\" output yourself in some meaningful fashion.
55.if \nF \{\
56. de IX
57. tm Index:\\$1\t\\n%\t"\\$2"
984263bc 58..
8b0cefbb
JR
59. nr % 0
60. rr F
984263bc 61.\}
8b0cefbb
JR
62.\"
63.\" For nroff, turn off justification. Always turn off hyphenation; it makes
64.\" way too many mistakes in technical documents.
65.hy 0
984263bc 66.if n .na
8b0cefbb
JR
67.\"
68.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
69.\" Fear. Run. Save yourself. No user-serviceable parts.
70. \" fudge factors for nroff and troff
984263bc 71.if n \{\
8b0cefbb
JR
72. ds #H 0
73. ds #V .8m
74. ds #F .3m
75. ds #[ \f1
76. ds #] \fP
984263bc
MD
77.\}
78.if t \{\
8b0cefbb
JR
79. ds #H ((1u-(\\\\n(.fu%2u))*.13m)
80. ds #V .6m
81. ds #F 0
82. ds #[ \&
83. ds #] \&
984263bc 84.\}
8b0cefbb 85. \" simple accents for nroff and troff
984263bc 86.if n \{\
8b0cefbb
JR
87. ds ' \&
88. ds ` \&
89. ds ^ \&
90. ds , \&
91. ds ~ ~
92. ds /
984263bc
MD
93.\}
94.if t \{\
8b0cefbb
JR
95. ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
96. ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
97. ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
98. ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
99. ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
100. ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
984263bc 101.\}
8b0cefbb 102. \" troff and (daisy-wheel) nroff accents
984263bc
MD
103.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
104.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
105.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
106.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
107.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
108.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
109.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
110.ds ae a\h'-(\w'a'u*4/10)'e
111.ds Ae A\h'-(\w'A'u*4/10)'E
8b0cefbb 112. \" corrections for vroff
984263bc
MD
113.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
114.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
8b0cefbb 115. \" for low resolution devices (crt and lpr)
984263bc
MD
116.if \n(.H>23 .if \n(.V>19 \
117\{\
8b0cefbb
JR
118. ds : e
119. ds 8 ss
120. ds o a
121. ds d- d\h'-1'\(ga
122. ds D- D\h'-1'\(hy
123. ds th \o'bp'
124. ds Th \o'LP'
125. ds ae ae
126. ds Ae AE
984263bc
MD
127.\}
128.rm #[ #] #H #V #F C
8b0cefbb
JR
129.\" ========================================================================
130.\"
131.IX Title "PKCS12 1"
132.TH PKCS12 1 "2004-12-18" "0.9.7e" "OpenSSL"
984263bc
MD
133.SH "NAME"
134pkcs12 \- PKCS#12 file utility
135.SH "SYNOPSIS"
8b0cefbb
JR
136.IX Header "SYNOPSIS"
137\&\fBopenssl\fR \fBpkcs12\fR
984263bc
MD
138[\fB\-export\fR]
139[\fB\-chain\fR]
140[\fB\-inkey filename\fR]
141[\fB\-certfile filename\fR]
142[\fB\-name name\fR]
143[\fB\-caname name\fR]
144[\fB\-in filename\fR]
145[\fB\-out filename\fR]
146[\fB\-noout\fR]
147[\fB\-nomacver\fR]
148[\fB\-nocerts\fR]
149[\fB\-clcerts\fR]
150[\fB\-cacerts\fR]
151[\fB\-nokeys\fR]
152[\fB\-info\fR]
153[\fB\-des\fR]
154[\fB\-des3\fR]
155[\fB\-idea\fR]
156[\fB\-nodes\fR]
157[\fB\-noiter\fR]
158[\fB\-maciter\fR]
159[\fB\-twopass\fR]
160[\fB\-descert\fR]
161[\fB\-certpbe\fR]
162[\fB\-keypbe\fR]
163[\fB\-keyex\fR]
164[\fB\-keysig\fR]
165[\fB\-password arg\fR]
166[\fB\-passin arg\fR]
167[\fB\-passout arg\fR]
e3cdf75b 168[\fB\-rand file(s)\fR]
984263bc 169.SH "DESCRIPTION"
8b0cefbb 170.IX Header "DESCRIPTION"
984263bc 171The \fBpkcs12\fR command allows PKCS#12 files (sometimes referred to as
8b0cefbb
JR
172\&\s-1PFX\s0 files) to be created and parsed. PKCS#12 files are used by several
173programs including Netscape, \s-1MSIE\s0 and \s-1MS\s0 Outlook.
984263bc 174.SH "COMMAND OPTIONS"
8b0cefbb 175.IX Header "COMMAND OPTIONS"
984263bc
MD
176There are a lot of options the meaning of some depends of whether a PKCS#12 file
177is being created or parsed. By default a PKCS#12 file is parsed a PKCS#12
178file can be created by using the \fB\-export\fR option (see below).
179.SH "PARSING OPTIONS"
8b0cefbb
JR
180.IX Header "PARSING OPTIONS"
181.IP "\fB\-in filename\fR" 4
182.IX Item "-in filename"
183This specifies filename of the PKCS#12 file to be parsed. Standard input is used
984263bc 184by default.
8b0cefbb
JR
185.IP "\fB\-out filename\fR" 4
186.IX Item "-out filename"
984263bc
MD
187The filename to write certificates and private keys to, standard output by default.
188They are all written in \s-1PEM\s0 format.
8b0cefbb
JR
189.IP "\fB\-pass arg\fR, \fB\-passin arg\fR" 4
190.IX Item "-pass arg, -passin arg"
191the PKCS#12 file (i.e. input file) password source. For more information about the
984263bc 192format of \fBarg\fR see the \fB\s-1PASS\s0 \s-1PHRASE\s0 \s-1ARGUMENTS\s0\fR section in
8b0cefbb
JR
193\&\fIopenssl\fR\|(1).
194.IP "\fB\-passout arg\fR" 4
195.IX Item "-passout arg"
984263bc
MD
196pass phrase source to encrypt any outputed private keys with. For more information
197about the format of \fBarg\fR see the \fB\s-1PASS\s0 \s-1PHRASE\s0 \s-1ARGUMENTS\s0\fR section in
8b0cefbb
JR
198\&\fIopenssl\fR\|(1).
199.IP "\fB\-noout\fR" 4
200.IX Item "-noout"
984263bc 201this option inhibits output of the keys and certificates to the output file version
8b0cefbb
JR
202of the PKCS#12 file.
203.IP "\fB\-clcerts\fR" 4
204.IX Item "-clcerts"
984263bc 205only output client certificates (not \s-1CA\s0 certificates).
8b0cefbb
JR
206.IP "\fB\-cacerts\fR" 4
207.IX Item "-cacerts"
984263bc 208only output \s-1CA\s0 certificates (not client certificates).
8b0cefbb
JR
209.IP "\fB\-nocerts\fR" 4
210.IX Item "-nocerts"
984263bc 211no certificates at all will be output.
8b0cefbb
JR
212.IP "\fB\-nokeys\fR" 4
213.IX Item "-nokeys"
984263bc 214no private keys will be output.
8b0cefbb
JR
215.IP "\fB\-info\fR" 4
216.IX Item "-info"
217output additional information about the PKCS#12 file structure, algorithms used and
984263bc 218iteration counts.
8b0cefbb
JR
219.IP "\fB\-des\fR" 4
220.IX Item "-des"
984263bc 221use \s-1DES\s0 to encrypt private keys before outputting.
8b0cefbb
JR
222.IP "\fB\-des3\fR" 4
223.IX Item "-des3"
984263bc 224use triple \s-1DES\s0 to encrypt private keys before outputting, this is the default.
8b0cefbb
JR
225.IP "\fB\-idea\fR" 4
226.IX Item "-idea"
984263bc 227use \s-1IDEA\s0 to encrypt private keys before outputting.
8b0cefbb
JR
228.IP "\fB\-nodes\fR" 4
229.IX Item "-nodes"
984263bc 230don't encrypt the private keys at all.
8b0cefbb
JR
231.IP "\fB\-nomacver\fR" 4
232.IX Item "-nomacver"
984263bc 233don't attempt to verify the integrity \s-1MAC\s0 before reading the file.
8b0cefbb
JR
234.IP "\fB\-twopass\fR" 4
235.IX Item "-twopass"
984263bc
MD
236prompt for separate integrity and encryption passwords: most software
237always assumes these are the same so this option will render such
8b0cefbb 238PKCS#12 files unreadable.
984263bc 239.SH "FILE CREATION OPTIONS"
8b0cefbb
JR
240.IX Header "FILE CREATION OPTIONS"
241.IP "\fB\-export\fR" 4
242.IX Item "-export"
243This option specifies that a PKCS#12 file will be created rather than
984263bc 244parsed.
8b0cefbb
JR
245.IP "\fB\-out filename\fR" 4
246.IX Item "-out filename"
247This specifies filename to write the PKCS#12 file to. Standard output is used
984263bc 248by default.
8b0cefbb
JR
249.IP "\fB\-in filename\fR" 4
250.IX Item "-in filename"
984263bc
MD
251The filename to read certificates and private keys from, standard input by default.
252They must all be in \s-1PEM\s0 format. The order doesn't matter but one private key and
253its corresponding certificate should be present. If additional certificates are
8b0cefbb
JR
254present they will also be included in the PKCS#12 file.
255.IP "\fB\-inkey filename\fR" 4
256.IX Item "-inkey filename"
984263bc
MD
257file to read private key from. If not present then a private key must be present
258in the input file.
8b0cefbb
JR
259.IP "\fB\-name friendlyname\fR" 4
260.IX Item "-name friendlyname"
984263bc
MD
261This specifies the \*(L"friendly name\*(R" for the certificate and private key. This name
262is typically displayed in list boxes by software importing the file.
8b0cefbb
JR
263.IP "\fB\-certfile filename\fR" 4
264.IX Item "-certfile filename"
984263bc 265A filename to read additional certificates from.
8b0cefbb
JR
266.IP "\fB\-caname friendlyname\fR" 4
267.IX Item "-caname friendlyname"
984263bc
MD
268This specifies the \*(L"friendly name\*(R" for other certificates. This option may be
269used multiple times to specify names for all certificates in the order they
270appear. Netscape ignores friendly names on other certificates whereas \s-1MSIE\s0
271displays them.
8b0cefbb
JR
272.IP "\fB\-pass arg\fR, \fB\-passout arg\fR" 4
273.IX Item "-pass arg, -passout arg"
274the PKCS#12 file (i.e. output file) password source. For more information about
984263bc 275the format of \fBarg\fR see the \fB\s-1PASS\s0 \s-1PHRASE\s0 \s-1ARGUMENTS\s0\fR section in
8b0cefbb
JR
276\&\fIopenssl\fR\|(1).
277.IP "\fB\-passin password\fR" 4
278.IX Item "-passin password"
984263bc
MD
279pass phrase source to decrypt any input private keys with. For more information
280about the format of \fBarg\fR see the \fB\s-1PASS\s0 \s-1PHRASE\s0 \s-1ARGUMENTS\s0\fR section in
8b0cefbb
JR
281\&\fIopenssl\fR\|(1).
282.IP "\fB\-chain\fR" 4
283.IX Item "-chain"
984263bc
MD
284if this option is present then an attempt is made to include the entire
285certificate chain of the user certificate. The standard \s-1CA\s0 store is used
286for this search. If the search fails it is considered a fatal error.
8b0cefbb
JR
287.IP "\fB\-descert\fR" 4
288.IX Item "-descert"
289encrypt the certificate using triple \s-1DES\s0, this may render the PKCS#12
984263bc
MD
290file unreadable by some \*(L"export grade\*(R" software. By default the private
291key is encrypted using triple \s-1DES\s0 and the certificate using 40 bit \s-1RC2\s0.
8b0cefbb
JR
292.IP "\fB\-keypbe alg\fR, \fB\-certpbe alg\fR" 4
293.IX Item "-keypbe alg, -certpbe alg"
984263bc 294these options allow the algorithm used to encrypt the private key and
8b0cefbb
JR
295certificates to be selected. Although any PKCS#5 v1.5 or PKCS#12 algorithms
296can be selected it is advisable only to use PKCS#12 algorithms. See the list
984263bc 297in the \fB\s-1NOTES\s0\fR section for more information.
8b0cefbb
JR
298.IP "\fB\-keyex|\-keysig\fR" 4
299.IX Item "-keyex|-keysig"
984263bc
MD
300specifies that the private key is to be used for key exchange or just signing.
301This option is only interpreted by \s-1MSIE\s0 and similar \s-1MS\s0 software. Normally
8b0cefbb 302\&\*(L"export grade\*(R" software will only allow 512 bit \s-1RSA\s0 keys to be used for
984263bc
MD
303encryption purposes but arbitrary length keys for signing. The \fB\-keysig\fR
304option marks the key for signing only. Signing only keys can be used for
8b0cefbb 305S/MIME signing, authenticode (ActiveX control signing) and \s-1SSL\s0 client
984263bc
MD
306authentication, however due to a bug only \s-1MSIE\s0 5.0 and later support
307the use of signing only keys for \s-1SSL\s0 client authentication.
8b0cefbb
JR
308.IP "\fB\-nomaciter\fR, \fB\-noiter\fR" 4
309.IX Item "-nomaciter, -noiter"
984263bc
MD
310these options affect the iteration counts on the \s-1MAC\s0 and key algorithms.
311Unless you wish to produce files compatible with \s-1MSIE\s0 4.0 you should leave
312these options alone.
313.Sp
314To discourage attacks by using large dictionaries of common passwords the
315algorithm that derives keys from passwords can have an iteration count applied
316to it: this causes a certain part of the algorithm to be repeated and slows it
317down. The \s-1MAC\s0 is used to check the file integrity but since it will normally
318have the same password as the keys and certificates it could also be attacked.
319By default both \s-1MAC\s0 and encryption iteration counts are set to 2048, using
320these options the \s-1MAC\s0 and encryption iteration counts can be set to 1, since
321this reduces the file security you should not use these options unless you
322really have to. Most software supports both \s-1MAC\s0 and key iteration counts.
8b0cefbb 323\&\s-1MSIE\s0 4.0 doesn't support \s-1MAC\s0 iteration counts so it needs the \fB\-nomaciter\fR
984263bc 324option.
8b0cefbb
JR
325.IP "\fB\-maciter\fR" 4
326.IX Item "-maciter"
984263bc
MD
327This option is included for compatibility with previous versions, it used
328to be needed to use \s-1MAC\s0 iterations counts but they are now used by default.
8b0cefbb
JR
329.IP "\fB\-rand file(s)\fR" 4
330.IX Item "-rand file(s)"
984263bc 331a file or files containing random data used to seed the random number
8b0cefbb
JR
332generator, or an \s-1EGD\s0 socket (see \fIRAND_egd\fR\|(3)).
333Multiple files can be specified separated by a OS-dependent character.
334The separator is \fB;\fR for MS\-Windows, \fB,\fR for OpenVMS, and \fB:\fR for
984263bc
MD
335all others.
336.SH "NOTES"
8b0cefbb 337.IX Header "NOTES"
984263bc
MD
338Although there are a large number of options most of them are very rarely
339used. For PKCS#12 file parsing only \fB\-in\fR and \fB\-out\fR need to be used
340for PKCS#12 file creation \fB\-export\fR and \fB\-name\fR are also used.
341.PP
342If none of the \fB\-clcerts\fR, \fB\-cacerts\fR or \fB\-nocerts\fR options are present
343then all certificates will be output in the order they appear in the input
344PKCS#12 files. There is no guarantee that the first certificate present is
345the one corresponding to the private key. Certain software which requires
346a private key and certificate and assumes the first certificate in the
347file is the one corresponding to the private key: this may not always
348be the case. Using the \fB\-clcerts\fR option will solve this problem by only
8b0cefbb 349outputting the certificate corresponding to the private key. If the \s-1CA\s0
984263bc 350certificates are required then they can be output to a separate file using
8b0cefbb 351the \fB\-nokeys \-cacerts\fR options to just output \s-1CA\s0 certificates.
984263bc
MD
352.PP
353The \fB\-keypbe\fR and \fB\-certpbe\fR algorithms allow the precise encryption
354algorithms for private keys and certificates to be specified. Normally
8b0cefbb
JR
355the defaults are fine but occasionally software can't handle triple \s-1DES\s0
356encrypted private keys, then the option \fB\-keypbe \s-1PBE\-SHA1\-RC2\-40\s0\fR can
357be used to reduce the private key encryption to 40 bit \s-1RC2\s0. A complete
984263bc
MD
358description of all algorithms is contained in the \fBpkcs8\fR manual page.
359.SH "EXAMPLES"
8b0cefbb 360.IX Header "EXAMPLES"
984263bc
MD
361Parse a PKCS#12 file and output it to a file:
362.PP
363.Vb 1
364\& openssl pkcs12 -in file.p12 -out file.pem
365.Ve
8b0cefbb 366.PP
984263bc
MD
367Output only client certificates to a file:
368.PP
369.Vb 1
370\& openssl pkcs12 -in file.p12 -clcerts -out file.pem
371.Ve
8b0cefbb 372.PP
984263bc 373Don't encrypt the private key:
8b0cefbb
JR
374.PP
375.Vb 1
376\& openssl pkcs12 -in file.p12 -out file.pem -nodes
377.Ve
984263bc 378.PP
984263bc
MD
379Print some info about a PKCS#12 file:
380.PP
381.Vb 1
382\& openssl pkcs12 -in file.p12 -info -noout
383.Ve
8b0cefbb 384.PP
984263bc
MD
385Create a PKCS#12 file:
386.PP
387.Vb 1
388\& openssl pkcs12 -export -in file.pem -out file.p12 -name "My Certificate"
389.Ve
8b0cefbb 390.PP
984263bc
MD
391Include some extra certificates:
392.PP
393.Vb 2
394\& openssl pkcs12 -export -in file.pem -out file.p12 -name "My Certificate" \e
395\& -certfile othercerts.pem
396.Ve
397.SH "BUGS"
8b0cefbb 398.IX Header "BUGS"
984263bc
MD
399Some would argue that the PKCS#12 standard is one big bug :\-)
400.PP
401Versions of OpenSSL before 0.9.6a had a bug in the PKCS#12 key generation
402routines. Under rare circumstances this could produce a PKCS#12 file encrypted
403with an invalid key. As a result some PKCS#12 files which triggered this bug
8b0cefbb 404from other implementations (\s-1MSIE\s0 or Netscape) could not be decrypted
984263bc
MD
405by OpenSSL and similarly OpenSSL could produce PKCS#12 files which could
406not be decrypted by other implementations. The chances of producing such
407a file are relatively small: less than 1 in 256.
408.PP
409A side effect of fixing this bug is that any old invalidly encrypted PKCS#12
410files cannot no longer be parsed by the fixed version. Under such circumstances
8b0cefbb 411the \fBpkcs12\fR utility will report that the \s-1MAC\s0 is \s-1OK\s0 but fail with a decryption
984263bc
MD
412error when extracting private keys.
413.PP
414This problem can be resolved by extracting the private keys and certificates
415from the PKCS#12 file using an older version of OpenSSL and recreating the PKCS#12
416file from the keys and certificates using a newer version of OpenSSL. For example:
417.PP
418.Vb 2
419\& old-openssl -in bad.p12 -out keycerts.pem
420\& openssl -in keycerts.pem -export -name "My PKCS#12 file" -out fixed.p12
421.Ve
422.SH "SEE ALSO"
e3cdf75b 423.IX Header "SEE ALSO"
8b0cefbb 424\&\fIpkcs8\fR\|(1)