3691a9b25436c3d7ac2a0eee4c752d3d1efed8b2
[openssl.git] / doc / crypto / PKCS12_parse.pod
1 =pod
2
3 =head1 NAME
4
5 PKCS12_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, STACK_OF(X509) **ca);
12
13 =head1 DESCRIPTION
14
15 PKCS12_parse() parses a PKCS12 structure.
16
17 B<p12> is the B<PKCS12> structure to parse. B<pass> is the passphrase to use.
18 If successful the private key will be written to B<*pkey>, the corresponding
19 certificate to B<*cert> and any additional certificates to B<*ca>.
20
21 =head1 NOTES
22
23 The parameters B<pkey> and B<cert> cannot be B<NULL>. B<ca> can be <NULL> in
24 which case additional certificates will be discarded. B<*ca> can also be a
25 valid STACK in which case additional certificates are appended to B<*ca>. If
26 B<*ca> is B<NULL> a new STACK will be allocated.
27
28 The B<friendlyName> and B<localKeyID> attributes (if present) on each
29 certificate will be stored in the B<alias> and B<keyid> attributes of the
30 B<X509> structure.
31
32 =head1 RETURN VALUES
33
34 PKCS12_parse() returns 1 for success and zero if an error occurred.
35
36 The error can be obtained from L<ERR_get_error(3)>
37
38 =head1 BUGS
39
40 Only a single private key and corresponding certificate is returned by this
41 function. More complex PKCS#12 files with multiple private keys will only
42 return the first match.
43
44 Only B<friendlyName> and B<localKeyID> attributes are currently stored in
45 certificates. Other attributes are discarded.
46
47 Attributes currently cannot be stored in the private key B<EVP_PKEY> structure.
48
49 =head1 SEE ALSO
50
51 L<d2i_PKCS12(3)>
52
53 =head1 HISTORY
54
55 PKCS12_parse was added in OpenSSL 0.9.3
56
57 =cut