| xf.li | bfc6e71 | 2025-02-07 01:54:34 -0800 | [diff] [blame^] | 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, |
| 12 | STACK_OF(X509) **ca); |
| 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 | |
| 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. |
| 28 | |
| 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 | |
| 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 | |
| 42 | =head1 RETURN VALUES |
| 43 | |
| 44 | PKCS12_parse() returns 1 for success and zero if an error occurred. |
| 45 | |
| 46 | The error can be obtained from L<ERR_get_error(3)> |
| 47 | |
| 48 | =head1 BUGS |
| 49 | |
| 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. |
| 53 | |
| 54 | Only B<friendlyName> and B<localKeyID> attributes are currently stored in |
| 55 | certificates. Other attributes are discarded. |
| 56 | |
| 57 | Attributes currently cannot be stored in the private key B<EVP_PKEY> structure. |
| 58 | |
| 59 | =head1 SEE ALSO |
| 60 | |
| 61 | L<d2i_PKCS12(3)>, |
| 62 | L<passphrase-encoding(7)> |
| 63 | |
| 64 | =head1 COPYRIGHT |
| 65 | |
| 66 | Copyright 2002-2018 The OpenSSL Project Authors. All Rights Reserved. |
| 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 |