NAME

X509_keyid_set1, X509_keyid_get0, X509_alias_set1, X509_alias_get0 — auxiliary certificate data for PKCS#12

SYNOPSIS

#include <openssl/x509.h>

int
X509_keyid_set1(X509 *x, const unsigned char *data, int len);

unsigned char *
X509_keyid_get0(X509 *x, int *plen);

int
X509_alias_set1(X509 *x, const unsigned char *data, int len);

unsigned char *
X509_alias_get0(X509 *x, int *plen);

DESCRIPTION

These functions store non-standard auxiliary data in x and retrieve it.

The len bytes of data stored using X509_keyid_set1() will be written to the localKeyID attribute of the PKCS#12 structure if PKCS12_create(3) is later called on x, and the data stored using X509_alias_set1() will be written to the friendlyName attribute. If data points to a NUL-terminated string, -1 can be passed as the len argument to let len be calculated internally using strlen(3). If a NULL pointer is passed as the data argument, the respective auxiliary data stored in x, if any, is removed from x and freed.

Conversely, PKCS12_parse(3) retrieves these attributes from a PKCS#12 structure such that they can subsequently be accessed with X509_keyid_get0() and X509_alias_get0(). Unless NULL is passed for the plen argument, these functions store the size of the returned buffer in bytes in *plen. After the call, the returned buffer is not necessarily NUL-terminated, but it may contain internal NUL bytes.

API design is very incomplete; given the complexity of PKCS#12, that's probably an asset rather than a defect. The PKCS#12 standard defines many attributes that cannot be stored in X509 objects.

To associate certificates with alternative names and key identifiers, X.509 certificate extensions are more commonly used than PKCS#12 attributes, for example using X509_EXTENSION_create_by_NID(3) with NID_subject_alt_name or NID_subject_key_identifier.

RETURN VALUES

X509_keyid_set1() and X509_alias_set1() return 1 if data is NULL or if the input data was successfully copied into x, or 0 if data is not NULL but could not be copied because x is NULL or memory allocation failed.

X509_keyid_get0() and X509_alias_get0() return an internal pointer to an array of bytes or NULL if x does not contain auxiliary data of the requested kind.

SEE ALSO

ASN1_STRING_set(3), X509_CERT_AUX_new(3), X509_EXTENSION_new(3), X509_new(3), X509V3_get_d2i(3)

HISTORY

X509_alias_set1() and X509_alias_get0() first appeared in OpenSSL 0.9.5 and have been available since OpenBSD 2.7.

X509_keyid_set1() first appeared in OpenSSL 0.9.6 and has been available since OpenBSD 2.9.

X509_keyid_get0() first appeared in OpenSSL 0.9.8 and has been available since OpenBSD 4.5.