1=pod
2
3=head1 NAME
4
5PKCS12_parse - parse a PKCS#12 structure
6
7=head1 SYNOPSIS
8
9 #include <openssl/pkcs12.h>
10
11int PKCS12_parse(PKCS12 *p12, const char *pass, EVP_PKEY **pkey, X509 **cert, STACK_OF(X509) **ca);
12
13=head1 DESCRIPTION
14
15PKCS12_parse() parses a PKCS12 structure.
16
17B<p12> is the B<PKCS12> structure to parse. B<pass> is the passphrase to use.
18If successful the private key will be written to B<*pkey>, the corresponding
19certificate to B<*cert> and any additional certificates to B<*ca>.
20
21=head1 NOTES
22
23The parameters B<pkey> and B<cert> cannot be B<NULL>. B<ca> can be <NULL> in
24which case additional certificates will be discarded. B<*ca> can also be a
25valid STACK in which case additional certificates are appended to B<*ca>. If
26B<*ca> is B<NULL> a new STACK will be allocated.
27
28The B<friendlyName> and B<localKeyID> attributes (if present) on each
29certificate will be stored in the B<alias> and B<keyid> attributes of the
30B<X509> structure.
31
32The parameter B<pass> is interpreted as a string in the UTF-8 encoding. If it
33is not valid UTF-8, then it is assumed to be ISO8859-1 instead.
34
35In particular, this means that passwords in the locale character set
36(or code page on Windows) must potentially be converted to UTF-8 before
37use. This may include passwords from local text files, or input from
38the terminal or command line. Refer to the documentation of
39L<UI_OpenSSL(3)>, for example.
40
41=head1 RETURN VALUES
42
43PKCS12_parse() returns 1 for success and zero if an error occurred.
44
45The error can be obtained from L<ERR_get_error(3)>
46
47=head1 BUGS
48
49Only a single private key and corresponding certificate is returned by this
50function. More complex PKCS#12 files with multiple private keys will only
51return the first match.
52
53Only B<friendlyName> and B<localKeyID> attributes are currently stored in
54certificates. Other attributes are discarded.
55
56Attributes currently cannot be stored in the private key B<EVP_PKEY> structure.
57
58=head1 SEE ALSO
59
60L<d2i_PKCS12(3)>,
61L<passphrase-encoding(7)>
62
63=head1 COPYRIGHT
64
65Copyright 2002-2018 The OpenSSL Project Authors. All Rights Reserved.
66
67Licensed under the OpenSSL license (the "License").  You may not use
68this file except in compliance with the License.  You can obtain a copy
69in the file LICENSE in the source distribution or at
70L<https://www.openssl.org/source/license.html>.
71
72=cut
73