| =pod | |
| =head1 NAME | |
| PKCS12_parse - parse a PKCS#12 structure | |
| =head1 SYNOPSIS | |
| #include <openssl/pkcs12.h> | |
| int PKCS12_parse(PKCS12 *p12, const char *pass, EVP_PKEY **pkey, X509 **cert, | |
| STACK_OF(X509) **ca); | |
| =head1 DESCRIPTION | |
| PKCS12_parse() parses a PKCS12 structure. | |
| B<p12> is the B<PKCS12> structure to parse. B<pass> is the passphrase to use. | |
| If successful the private key will be written to B<*pkey>, the corresponding | |
| certificate to B<*cert> and any additional certificates to B<*ca>. | |
| =head1 NOTES | |
| Each of the parameters B<pkey>, B<cert>, and B<ca> can be NULL in which case | |
| the private key, the corresponding certificate, or the additional certificates, | |
| respectively, will be discarded. | |
| If any of B<pkey> and B<cert> is non-NULL the variable it points to is | |
| initialized. | |
| If B<ca> is non-NULL and B<*ca> is NULL a new STACK will be allocated. | |
| If B<ca> is non-NULL and B<*ca> is a valid STACK | |
| then additional certificates are appended in the given order to B<*ca>. | |
| The B<friendlyName> and B<localKeyID> attributes (if present) on each | |
| certificate will be stored in the B<alias> and B<keyid> attributes of the | |
| B<X509> structure. | |
| The parameter B<pass> is interpreted as a string in the UTF-8 encoding. If it | |
| is not valid UTF-8, then it is assumed to be ISO8859-1 instead. | |
| In particular, this means that passwords in the locale character set | |
| (or code page on Windows) must potentially be converted to UTF-8 before | |
| use. This may include passwords from local text files, or input from | |
| the terminal or command line. Refer to the documentation of | |
| L<UI_OpenSSL(3)>, for example. | |
| =head1 RETURN VALUES | |
| PKCS12_parse() returns 1 for success and zero if an error occurred. | |
| The error can be obtained from L<ERR_get_error(3)> | |
| =head1 BUGS | |
| Only a single private key and corresponding certificate is returned by this | |
| function. More complex PKCS#12 files with multiple private keys will only | |
| return the first match. | |
| Only B<friendlyName> and B<localKeyID> attributes are currently stored in | |
| certificates. Other attributes are discarded. | |
| Attributes currently cannot be stored in the private key B<EVP_PKEY> structure. | |
| =head1 SEE ALSO | |
| L<d2i_PKCS12(3)>, | |
| L<passphrase-encoding(7)> | |
| =head1 COPYRIGHT | |
| Copyright 2002-2020 The OpenSSL Project Authors. All Rights Reserved. | |
| Licensed under the Apache License 2.0 (the "License"). You may not use | |
| this file except in compliance with the License. You can obtain a copy | |
| in the file LICENSE in the source distribution or at | |
| L<https://www.openssl.org/source/license.html>. | |
| =cut |