jcs.org
jcs's openbsd hax
openbsd
1.\" $OpenBSD: PKCS12_parse.3,v 1.8 2025/06/08 22:40:30 schwarze Exp $
2.\" OpenSSL 99d63d46 Oct 26 13:56:48 2016 -0400
3.\"
4.\" This file was written by Dr. Stephen Henson <steve@openssl.org>.
5.\" Copyright (c) 2002, 2009 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: June 8 2025 $
52.Dt PKCS12_PARSE 3
53.Os
54.Sh NAME
55.Nm PKCS12_parse
56.Nd parse a PKCS#12 structure
57.Sh SYNOPSIS
58.Lb libcrypto
59.In openssl/pkcs12.h
60.Ft int
61.Fo PKCS12_parse
62.Fa "PKCS12 *p12"
63.Fa "const char *pass"
64.Fa "EVP_PKEY **pkey"
65.Fa "X509 **cert"
66.Fa "STACK_OF(X509) **ca"
67.Fc
68.Sh DESCRIPTION
69.Fn PKCS12_parse
70parses a PKCS12 structure.
71.Pp
72.Fa p12
73is the
74.Vt PKCS12
75structure to parse.
76.Fa pass
77is the passphrase to use.
78If successful, the private key will be written to
79.Pf * Fa pkey ,
80the corresponding certificate to
81.Pf * Fa cert ,
82and any additional certificates to
83.Pf * Fa ca .
84.Pp
85The parameters
86.Fa pkey
87and
88.Fa cert
89cannot be
90.Dv NULL .
91.Fa ca
92can be
93.Dv NULL ,
94in which case additional certificates will be discarded.
95.Pf * Fa ca
96can also be a valid STACK, in which case additional certificates are
97appended to
98.Pf * Fa ca .
99If
100.Pf * Fa ca
101is
102.Dv NULL ,
103a new STACK will be allocated.
104.Pp
105The
106.Sy friendlyName
107and
108.Sy localKeyID
109attributes (if present) of each certificate will be stored in the
110.Fa alias
111and
112.Fa keyid
113attributes of the
114.Vt X509
115structure.
116.Sh RETURN VALUES
117.Fn PKCS12_parse
118returns 1 for success and 0 if an error occurred.
119.Pp
120The error can be obtained from
121.Xr ERR_get_error 3 .
122.Sh SEE ALSO
123.Xr d2i_PKCS12 3 ,
124.Xr PKCS12_create 3 ,
125.Xr PKCS12_new 3 ,
126.Xr X509_keyid_set1 3
127.Sh HISTORY
128.Fn PKCS12_parse
129first appeared in OpenSSL 0.9.3 and has been available since
130.Ox 2.6 .
131.Sh BUGS
132Only a single private key and corresponding certificate is returned by
133this function.
134More complex PKCS#12 files with multiple private keys will only return
135the first match.
136.Pp
137Only
138.Sy friendlyName
139and
140.Sy localKeyID
141attributes are currently stored in certificates.
142Other attributes are discarded.
143.Pp
144Attributes currently cannot be stored in the private key
145.Vt EVP_PKEY
146structure.