- update OpenSSL to 0.9.8
[dragonfly.git] / secure / lib / libcrypto / man / PKCS12_create.3
1 .\" Automatically generated by Pod::Man v1.37, Pod::Parser v1.14
2 .\"
3 .\" Standard preamble:
4 .\" ========================================================================
5 .de Sh \" Subsection heading
6 .br
7 .if t .Sp
8 .ne 5
9 .PP
10 \fB\\$1\fR
11 .PP
12 ..
13 .de Sp \" Vertical space (when we can't use .PP)
14 .if t .sp .5v
15 .if n .sp
16 ..
17 .de Vb \" Begin verbatim text
18 .ft CW
19 .nf
20 .ne \\$1
21 ..
22 .de Ve \" End verbatim text
23 .ft R
24 .fi
25 ..
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<>.
32 .tr \(*W-|\(bv\*(Tr
33 .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
34 .ie n \{\
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' ""
43 'br\}
44 .el\{\
45 .    ds -- \|\(em\|
46 .    ds PI \(*p
47 .    ds L" ``
48 .    ds R" ''
49 'br\}
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"
58 ..
59 .    nr % 0
60 .    rr F
61 .\}
62 .\"
63 .\" For nroff, turn off justification.  Always turn off hyphenation; it makes
64 .\" way too many mistakes in technical documents.
65 .hy 0
66 .if n .na
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
71 .if n \{\
72 .    ds #H 0
73 .    ds #V .8m
74 .    ds #F .3m
75 .    ds #[ \f1
76 .    ds #] \fP
77 .\}
78 .if t \{\
79 .    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
80 .    ds #V .6m
81 .    ds #F 0
82 .    ds #[ \&
83 .    ds #] \&
84 .\}
85 .    \" simple accents for nroff and troff
86 .if n \{\
87 .    ds ' \&
88 .    ds ` \&
89 .    ds ^ \&
90 .    ds , \&
91 .    ds ~ ~
92 .    ds /
93 .\}
94 .if t \{\
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'
101 .\}
102 .    \" troff and (daisy-wheel) nroff accents
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
112 .    \" corrections for vroff
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'
115 .    \" for low resolution devices (crt and lpr)
116 .if \n(.H>23 .if \n(.V>19 \
117 \{\
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
127 .\}
128 .rm #[ #] #H #V #F C
129 .\" ========================================================================
130 .\"
131 .IX Title "PKCS12_create 3"
132 .TH PKCS12_create 3 "2005-07-06" "0.9.8" "OpenSSL"
133 .SH "NAME"
134 PKCS12_create \- create a PKCS#12 structure
135 .SH "SYNOPSIS"
136 .IX Header "SYNOPSIS"
137 .Vb 1
138 \& #include <openssl/pkcs12.h>
139 .Ve
140 .PP
141 .Vb 2
142 \& PKCS12 *PKCS12_create(char *pass, char *name, EVP_PKEY *pkey, X509 *cert, STACK_OF(X509) *ca,
143 \&                                int nid_key, int nid_cert, int iter, int mac_iter, int keytype);
144 .Ve
145 .SH "DESCRIPTION"
146 .IX Header "DESCRIPTION"
147 \&\fIPKCS12_create()\fR creates a PKCS#12 structure.
148 .PP
149 \&\fBpass\fR is the passphrase to use. \fBname\fR is the \fBfriendlyName\fR to use for
150 the supplied certifictate and key. \fBpkey\fR is the private key to include in
151 the structure and \fBcert\fR its corresponding certificates. \fBca\fR, if not \fB\s-1NULL\s0\fR
152 is an optional set of certificates to also include in the structure.
153 .PP
154 \&\fBnid_key\fR and \fBnid_cert\fR are the encryption algorithms that should be used
155 for the key and certificate respectively. \fBiter\fR is the encryption algorithm
156 iteration count to use and \fBmac_iter\fR is the \s-1MAC\s0 iteration count to use.
157 \&\fBkeytype\fR is the type of key.
158 .SH "NOTES"
159 .IX Header "NOTES"
160 The parameters \fBnid_key\fR, \fBnid_cert\fR, \fBiter\fR, \fBmac_iter\fR and \fBkeytype\fR
161 can all be set to zero and sensible defaults will be used.
162 .PP
163 These defaults are: 40 bit \s-1RC2\s0 encryption for certificates, triple \s-1DES\s0
164 encryption for private keys, a key iteration count of \s-1PKCS12_DEFAULT_ITER\s0
165 (currently 2048) and a \s-1MAC\s0 iteration count of 1.
166 .PP
167 The default \s-1MAC\s0 iteration count is 1 in order to retain compatibility with
168 old software which did not interpret \s-1MAC\s0 iteration counts. If such compatibility
169 is not required then \fBmac_iter\fR should be set to \s-1PKCS12_DEFAULT_ITER\s0.
170 .PP
171 \&\fBkeytype\fR adds a flag to the store private key. This is a non standard extension
172 that is only currently interpreted by \s-1MSIE\s0. If set to zero the flag is omitted,
173 if set to \fB\s-1KEY_SIG\s0\fR the key can be used for signing only, if set to \fB\s-1KEY_EX\s0\fR
174 it can be used for signing and encryption. This option was useful for old
175 export grade software which could use signing only keys of arbitrary size but
176 had restrictions on the permissible sizes of keys which could be used for
177 encryption.
178 .SH "NEW FUNCTIONALITY IN OPENSSL 0.9.8"
179 .IX Header "NEW FUNCTIONALITY IN OPENSSL 0.9.8"
180 Some additional functionality was added to \fIPKCS12_create()\fR in OpenSSL
181 0.9.8. These extensions are detailed below.
182 .PP
183 If a certificate contains an \fBalias\fR or \fBkeyid\fR then this will be
184 used for the corresponding \fBfriendlyName\fR or \fBlocalKeyID\fR in the
185 \&\s-1PKCS12\s0 structure.
186 .PP
187 Either \fBpkey\fR, \fBcert\fR or both can be \fB\s-1NULL\s0\fR to indicate that no key or
188 certficate is required. In previous versions both had to be present or
189 a fatal error is returned.
190 .PP
191 \&\fBnid_key\fR or \fBnid_cert\fR can be set to \-1 indicating that no encryption
192 should be used. 
193 .PP
194 \&\fBmac_iter\fR can be set to \-1 and the \s-1MAC\s0 will then be omitted entirely.
195 .SH "SEE ALSO"
196 .IX Header "SEE ALSO"
197 \&\fId2i_PKCS12\fR\|(3)
198 .SH "HISTORY"
199 .IX Header "HISTORY"
200 PKCS12_create was added in OpenSSL 0.9.3