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