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