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