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