| blob | 162ff7cf683a260654ad8c4d31f085146e6e09c8 |
1 .\" $OpenBSD: PKCS12_create.3,v 1.4 2016/11/28 22:41:38 schwarze Exp $
2 .\" OpenSSL 05ea606a May 20 20:52:46 2016 -0400
3 .\"
4 .\" This file was written by Dr. Stephen Henson <steve@openssl.org>.
5 .\" Copyright (c) 2002, 2015 The OpenSSL Project. All rights reserved.
6 .\"
7 .\" Redistribution and use in source and binary forms, with or without
8 .\" modification, are permitted provided that the following conditions
9 .\" are met:
10 .\"
11 .\" 1. Redistributions of source code must retain the above copyright
12 .\" notice, this list of conditions and the following disclaimer.
13 .\"
14 .\" 2. Redistributions in binary form must reproduce the above copyright
15 .\" notice, this list of conditions and the following disclaimer in
16 .\" the documentation and/or other materials provided with the
17 .\" distribution.
18 .\"
19 .\" 3. All advertising materials mentioning features or use of this
20 .\" software must display the following acknowledgment:
21 .\" "This product includes software developed by the OpenSSL Project
22 .\" for use in the OpenSSL Toolkit. (http://www.openssl.org/)"
23 .\"
24 .\" 4. The names "OpenSSL Toolkit" and "OpenSSL Project" must not be used to
25 .\" endorse or promote products derived from this software without
26 .\" prior written permission. For written permission, please contact
27 .\" openssl-core@openssl.org.
28 .\"
29 .\" 5. Products derived from this software may not be called "OpenSSL"
30 .\" nor may "OpenSSL" appear in their names without prior written
31 .\" permission of the OpenSSL Project.
32 .\"
33 .\" 6. Redistributions of any form whatsoever must retain the following
34 .\" acknowledgment:
35 .\" "This product includes software developed by the OpenSSL Project
36 .\" for use in the OpenSSL Toolkit (http://www.openssl.org/)"
37 .\"
38 .\" THIS SOFTWARE IS PROVIDED BY THE OpenSSL PROJECT ``AS IS'' AND ANY
39 .\" EXPRESSED OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
40 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
41 .\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE OpenSSL PROJECT OR
42 .\" ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
43 .\" SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT
44 .\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
45 .\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
46 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT,
47 .\" STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
48 .\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED
49 .\" OF THE POSSIBILITY OF SUCH DAMAGE.
50 .\"
51 .Dd $Mdocdate: November 28 2016 $
52 .Dt PKCS12_CREATE 3
53 .Os
54 .Sh NAME
55 .Nm PKCS12_create
56 .Nd create a PKCS#12 structure
57 .Sh SYNOPSIS
58 .In openssl/pkcs12.h
59 .Ft PKCS12 *
60 .Fo PKCS12_create
61 .Fa "char *pass"
62 .Fa "char *name"
63 .Fa "EVP_PKEY *pkey"
64 .Fa "X509 *cert"
65 .Fa "STACK_OF(X509) *ca"
66 .Fa "int nid_key"
67 .Fa "int nid_cert"
68 .Fa "int iter"
69 .Fa "int mac_iter"
70 .Fa "int keytype"
71 .Fc
72 .Sh DESCRIPTION
73 .Fn PKCS12_create
74 creates a PKCS#12 structure.
75 .Pp
76 .Fa pass
77 is the passphrase to use.
78 .Fa name
79 is the
80 .Sy friendlyName
81 to use for the supplied certificate and key.
82 .Fa pkey
83 is the private key to include in the structure and
84 .Fa cert
85 its corresponding certificates.
86 .Fa ca
87 is an optional set of certificates to also include in the structure.
88 .Fa pkey ,
89 .Fa cert ,
90 or both can be
91 .Dv NULL
92 to indicate that no key or certificate is required.
93 .Pp
94 .Fa nid_key
95 and
96 .Fa nid_cert
97 are the encryption algorithms that should be used for the key and
98 certificate, respectively.
99 If either
100 .Fa nid_key
101 or
102 .Fa nid_cert
103 is set to -1, no encryption will be used.
104 .Pp
105 .Fa iter
106 is the encryption algorithm iteration count to use and
107 .Fa mac_iter
108 is the MAC iteration count to use.
109 If
110 .Fa mac_iter
111 is set to -1, the MAC will be omitted entirely.
112 .Pp
113 .Fa keytype
114 is the type of key.
115 .Pp
116 The parameters
117 .Fa nid_key ,
118 .Fa nid_cert ,
119 .Fa iter ,
120 .Fa mac_iter ,
121 and
122 .Fa keytype
123 can all be set to zero and sensible defaults will be used.
124 .Pp
125 These defaults are: 40-bit RC2 encryption for certificates, triple DES
126 encryption for private keys, a key iteration count of
127 PKCS12_DEFAULT_ITER (currently 2048) and a MAC iteration count of 1.
128 .Pp
129 The default MAC iteration count is 1 in order to retain compatibility
130 with old software which did not interpret MAC iteration counts.
131 If such compatibility is not required then
132 .Fa mac_iter
133 should be set to PKCS12_DEFAULT_ITER.
134 .Pp
135 .Fa keytype
136 adds a flag to the store private key.
137 This is a non-standard extension that is only currently interpreted by
138 MSIE.
139 If set to zero the flag is omitted; if set to
140 .Dv KEY_SIG
141 the key can be used for signing only; and if set to
142 .Dv KEY_EX
143 it can be used for signing and encryption.
144 This option was useful for old export grade software which could use
145 signing only keys of arbitrary size but had restrictions on the
146 permissible sizes of keys which could be used for encryption.
147 .Pp
148 If a certificate contains an
149 .Sy alias
150 or
151 .Sy keyid
152 then this will be used for the corresponding
153 .Sy friendlyName
154 or
155 .Sy localKeyID
156 in the PKCS12 structure.
157 .Sh SEE ALSO
158 .Xr d2i_PKCS12 3
159 .Sh HISTORY
160 PKCS12_create was added in OpenSSL 0.9.3.
161 .Pp
162 Before OpenSSL 0.9.8, neither
163 .Fa pkey
164 nor
165 .Fa cert
166 were allowed to be
167 .Dv NULL ,
168 and a value of -1 was not allowed for
169 .Fa nid_key ,
170 .Fa nid_cert ,
171 and
172 .Fa mac_iter .