PKCS12_parse¶

NAME¶

PKCS12_parse_ex, PKCS12_PARSE_CTX_new, PKCS12_PARSE_CTX_free, PKCS12_PARSE_CTX_set_pkey, PKCS12_PARSE_CTX_set_cert, PKCS12_PARSE_CTX_set_ca, PKCS12_PARSE_CTX_set_skeys, PKCS12_parse - parse a PKCS#12 structure

SYNOPSIS¶

#include <openssl/pkcs12.h>

PKCS12_PARSE_CTX *PKCS12_PARSE_CTX_new(void);
void PKCS12_PARSE_CTX_free(PKCS12_PARSE_CTX *ctx);
void PKCS12_PARSE_CTX_set_pkey(PKCS12_PARSE_CTX *ctx, EVP_PKEY **pkey);
void PKCS12_PARSE_CTX_set_cert(PKCS12_PARSE_CTX *ctx, X509 **cert);
void PKCS12_PARSE_CTX_set_ca(PKCS12_PARSE_CTX *ctx, STACK_OF(X509) **ca);
void PKCS12_PARSE_CTX_set_skeys(PKCS12_PARSE_CTX *ctx, STACK_OF(EVP_SKEY) **skeys);

int PKCS12_parse_ex(PKCS12 *p12, const char *pass, PKCS12_PARSE_CTX *ctx,
                    OSSL_LIB_CTX *libctx, const char *propq);
int PKCS12_parse(PKCS12 *p12, const char *pass, EVP_PKEY **pkey, X509 **cert,
                 STACK_OF(X509) **ca);

DESCRIPTION¶

PKCS12_parse_ex() parses a PKCS12 structure, extracting the components specified by the parse context ctx.

p12 is the PKCS12 structure to parse. pass is the passphrase to use. ctx is a PKCS12_PARSE_CTX that specifies which components to extract. libctx and propq specify the library context and property query string for algorithm lookups.

PKCS12_PARSE_CTX_new() allocates a new parse context. All output pointers are initially NULL, meaning no components will be extracted until configured via the setter functions.

PKCS12_PARSE_CTX_free() frees the parse context. It does not free any extracted objects.

PKCS12_PARSE_CTX_set_pkey() configures the context to extract the private key into *pkey.

PKCS12_PARSE_CTX_set_cert() configures the context to extract the matching certificate into *cert.

PKCS12_PARSE_CTX_set_ca() configures the context to extract additional certificates into *ca.

PKCS12_PARSE_CTX_set_skeys() configures the context to extract symmetric secret keys into *skeys as a STACK_OF(EVP_SKEY). All SecretBag structures found in the PKCS#12 file will be decrypted and added to the stack. This is used for PKCS#12 files containing SecretBag structures, such as those created by Java's keytool utility.

PKCS12_parse() is a wrapper around PKCS12_parse_ex() that extracts the private key, certificate, and CA certificates. It does not support symmetric key extraction or custom library contexts.

NOTES¶

Each of the parameters pkey, cert, and ca can be NULL in which case the private key, the corresponding certificate, or the additional certificates, respectively, will not be returned to the caller. If any of pkey and cert is non-NULL the variable it points to is initialized. If ca is non-NULL and *ca is NULL a new STACK will be allocated. If ca is non-NULL and *ca is a valid STACK then additional certificates are appended in the given order to *ca.

The corresponding certificate is identified by matching it against the private key. This means that *cert is only set when both pkey and cert are non-NULL and a private key was found. When pkey is NULL or cert is NULL, no matching is performed and the certificate that would have been the corresponding one is treated as an additional certificate: it is added to *ca if ca is non-NULL, or freed otherwise.

The friendlyName and localKeyID attributes (if present) on each certificate will be stored in the alias and keyid attributes of the X509 structure.

If parsing fails *pkey, *cert are set to NULL. If ca is non-NULL then *ca is left unchanged. If skeys is configured in the parse context then *skeys is also left unchanged on failure.

The parameter 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 UI_OpenSSL(3), for example.

RETURN VALUES¶

PKCS12_parse_ex() and PKCS12_parse() return 1 for success and zero if an error occurred.

The error can be obtained from ERR_get_error(3)

EXAMPLES¶

Extract all components including symmetric keys from a PKCS#12 file:

PKCS12_PARSE_CTX *ctx = PKCS12_PARSE_CTX_new();
EVP_PKEY *pkey = NULL;
X509 *cert = NULL;
STACK_OF(X509) *ca = NULL;
STACK_OF(EVP_SKEY) *skeys = NULL;

PKCS12_PARSE_CTX_set_pkey(ctx, &pkey);
PKCS12_PARSE_CTX_set_cert(ctx, &cert);
PKCS12_PARSE_CTX_set_ca(ctx, &ca);
PKCS12_PARSE_CTX_set_skeys(ctx, &skeys);

if (PKCS12_parse_ex(p12, password, ctx, NULL, NULL)) {
    /* use pkey, cert, ca, skeys */
}

EVP_PKEY_free(pkey);
X509_free(cert);
OSSL_STACK_OF_X509_free(ca);
sk_EVP_SKEY_pop_free(skeys, EVP_SKEY_free);
PKCS12_PARSE_CTX_free(ctx);

BUGS¶

Only a single private key and corresponding certificate is returned by PKCS12_parse() and PKCS12_parse_ex(). More complex PKCS#12 files with multiple private keys will only return the first match.

Only friendlyName and localKeyID attributes are currently stored in certificates. Other attributes are discarded.

Attributes currently cannot be stored in the private key EVP_PKEY structure.

HISTORY¶

PKCS12_parse_ex(), PKCS12_PARSE_CTX_new(), PKCS12_PARSE_CTX_free(), PKCS12_PARSE_CTX_set_pkey(), PKCS12_PARSE_CTX_set_cert(), PKCS12_PARSE_CTX_set_ca(), and PKCS12_PARSE_CTX_set_skeys() were added in OpenSSL 4.2.

COPYRIGHT¶

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 https://www.openssl.org/source/license.html.