NAME

PEM_X509_INFO_read, PEM_X509_INFO_read_bio —

PEM and DER decode X.509 certificates, private keys, and revocation lists

SYNOPSIS

#include <openssl/pem.h>

STACK_OF(X509_INFO) *
PEM_X509_INFO_read(FILE *in_fp, STACK_OF(X509_INFO) *sk, pem_password_cb *cb, void *u);

STACK_OF(X509_INFO) *
PEM_X509_INFO_read_bio(BIO *in_bp, STACK_OF(X509_INFO) *sk, pem_password_cb *cb, void *u);

DESCRIPTION

These functions read zero or more objects related to X.509 certificates from in_fp or in_bp, perform both PEM and DER decoding, and wrap the resulting objects in newly allocated X509_INFO containers.

Setting sk to NULL is recommended, in which case a new stack is allocated, populated, and returned. If an existing sk is passed in, the created X509_INFO objects are pushed onto that stack.

For PEM decoding, PEM_read_bio(3) is used internally, implying that any non-PEM data before, between, and after the objects is silently discarded.

For subsequent DER decoding, the decoding function and the field of the X509_INFO structure to store the new object in are selected according to the PEM type name:

PEM type name	decoder	`X509_INFO` field
CERTIFICATE	d2i_X509(3)	certificate
X509 CERTIFICATE	d2i_X509(3)	certificate
TRUSTED CERTIFICATE	d2i_X509_AUX(3)	certificate
X509 CRL	d2i_X509_CRL(3)	revocation list
RSA PRIVATE KEY	d2i_PrivateKey(3)	private key
DSA PRIVATE KEY	d2i_PrivateKey(3)	private key
EC PRIVATE KEY	d2i_PrivateKey(3)	private key

Whenever the selected field is already occupied, another new X509_INFO container is allocated and pushed onto the stack. Depending on the sequence of objects in the input, this can result in several partially populated X509_INFO containers being pushed onto the stack.

PEM objects of types not listed in the above table are silently skipped.

Encrypted certificates and revocation lists are decrypted by calling PEM_do_header(3) internally, passing through the optional arguments cb and u. Encrypted private keys are not decrypted. Instead, the encrypted form is stored as read. All the same, PEM_get_EVP_CIPHER_INFO(3) is called internally to check that PEM headers, if there are any, are valid and specify an encryption the library is prepared to handle.

If any error occurs, objects that had already been read during the same call are deleted again and sk is left unchanged.

RETURN VALUES

These functions return a pointer to the stack the objects read were pushed onto or NULL if an error occurs. They fail if PEM_read_bio(3), PEM_get_EVP_CIPHER_INFO(3), PEM_do_header(3), or DER decoding fails or if memory is exhausted.

ERRORS

Diagnostics that can be retrieved with ERR_get_error(3), ERR_GET_REASON(3), and ERR_reason_error_string(3) include:

ERR_R_ASN1_LIB “ASN1 lib”: DER decoding of a PEM object failed.
ERR_R_BUF_LIB “BUF lib”: PEM_X509_INFO_read() failed to set up a temporary BIO, for example because memory was exhausted.
ERR_R_MALLOC_FAILURE “malloc failure”: PEM_X509_INFO_read_bio() failed to allocate a new X509_INFO, STACK_OF(X509_INFO), or X509_PKEY object.

Additional types of errors can result from PEM_read_bio(3), PEM_get_EVP_CIPHER_INFO(3), and PEM_do_header(3).

After these functions failed due to memory exhaustion, ERR_get_error(3) may sometimes return 0 anyway.

HISTORY

PEM_X509_INFO_read() first appeared in SSLeay 0.5.1 and PEM_X509_INFO_read_bio() in SSLeay 0.6.0. Both functions have been available since OpenBSD 2.4.

CAVEATS

It is not an error if the input does not contain any objects of the desired types. In that case, nothing is added to sk, or if sk is NULL, a newly allocated, empty stack is returned. The only way to detect this situation is by comparing the number of objects on the stack before and after the call.

BUGS

When reaching the end of the input, these functions call ERR_clear_error(3), which may hide errors that occurred before calling these functions.