113d40330Schristos=pod 213d40330Schristos 313d40330Schristos=head1 NAME 413d40330Schristos 513d40330SchristosPKCS12_parse - parse a PKCS#12 structure 613d40330Schristos 713d40330Schristos=head1 SYNOPSIS 813d40330Schristos 913d40330Schristos #include <openssl/pkcs12.h> 1013d40330Schristos 11b88c74d5Schristos int PKCS12_parse(PKCS12 *p12, const char *pass, EVP_PKEY **pkey, X509 **cert, 12b88c74d5Schristos STACK_OF(X509) **ca); 1313d40330Schristos 1413d40330Schristos=head1 DESCRIPTION 1513d40330Schristos 1613d40330SchristosPKCS12_parse() parses a PKCS12 structure. 1713d40330Schristos 1813d40330SchristosB<p12> is the B<PKCS12> structure to parse. B<pass> is the passphrase to use. 1913d40330SchristosIf successful the private key will be written to B<*pkey>, the corresponding 2013d40330Schristoscertificate to B<*cert> and any additional certificates to B<*ca>. 2113d40330Schristos 2213d40330Schristos=head1 NOTES 2313d40330Schristos 24*b0d17251SchristosEach of the parameters B<pkey>, B<cert>, and B<ca> can be NULL in which case 25*b0d17251Schristosthe private key, the corresponding certificate, or the additional certificates, 26*b0d17251Schristosrespectively, will be discarded. 27*b0d17251SchristosIf any of B<pkey> and B<cert> is non-NULL the variable it points to is 28*b0d17251Schristosinitialized. 29*b0d17251SchristosIf B<ca> is non-NULL and B<*ca> is NULL a new STACK will be allocated. 30*b0d17251SchristosIf B<ca> is non-NULL and B<*ca> is a valid STACK 31*b0d17251Schristosthen additional certificates are appended in the given order to B<*ca>. 3213d40330Schristos 3313d40330SchristosThe B<friendlyName> and B<localKeyID> attributes (if present) on each 3413d40330Schristoscertificate will be stored in the B<alias> and B<keyid> attributes of the 3513d40330SchristosB<X509> structure. 3613d40330Schristos 3713d40330SchristosThe parameter B<pass> is interpreted as a string in the UTF-8 encoding. If it 3813d40330Schristosis not valid UTF-8, then it is assumed to be ISO8859-1 instead. 3913d40330Schristos 4013d40330SchristosIn particular, this means that passwords in the locale character set 4113d40330Schristos(or code page on Windows) must potentially be converted to UTF-8 before 4213d40330Schristosuse. This may include passwords from local text files, or input from 4313d40330Schristosthe terminal or command line. Refer to the documentation of 4413d40330SchristosL<UI_OpenSSL(3)>, for example. 4513d40330Schristos 4613d40330Schristos=head1 RETURN VALUES 4713d40330Schristos 4813d40330SchristosPKCS12_parse() returns 1 for success and zero if an error occurred. 4913d40330Schristos 5013d40330SchristosThe error can be obtained from L<ERR_get_error(3)> 5113d40330Schristos 5213d40330Schristos=head1 BUGS 5313d40330Schristos 5413d40330SchristosOnly a single private key and corresponding certificate is returned by this 5513d40330Schristosfunction. More complex PKCS#12 files with multiple private keys will only 5613d40330Schristosreturn the first match. 5713d40330Schristos 5813d40330SchristosOnly B<friendlyName> and B<localKeyID> attributes are currently stored in 5913d40330Schristoscertificates. Other attributes are discarded. 6013d40330Schristos 6113d40330SchristosAttributes currently cannot be stored in the private key B<EVP_PKEY> structure. 6213d40330Schristos 6313d40330Schristos=head1 SEE ALSO 6413d40330Schristos 6513d40330SchristosL<d2i_PKCS12(3)>, 6613d40330SchristosL<passphrase-encoding(7)> 6713d40330Schristos 6813d40330Schristos=head1 COPYRIGHT 6913d40330Schristos 70*b0d17251SchristosCopyright 2002-2020 The OpenSSL Project Authors. All Rights Reserved. 7113d40330Schristos 72*b0d17251SchristosLicensed under the Apache License 2.0 (the "License"). You may not use 7313d40330Schristosthis file except in compliance with the License. You can obtain a copy 7413d40330Schristosin the file LICENSE in the source distribution or at 7513d40330SchristosL<https://www.openssl.org/source/license.html>. 7613d40330Schristos 7713d40330Schristos=cut 78