DragonFly On-Line Manual Pages
PEM_X509_INFO_READ(3) DragonFly Library Functions Manual
PEM_X509_INFO_read, PEM_X509_INFO_read_bio - PEM and DER decode X.509
certificates, private keys, and revocation lists
PEM_X509_INFO_read(FILE *in_fp, STACK_OF(X509_INFO) *sk,
pem_password_cb *cb, void *u);
PEM_X509_INFO_read_bio(BIO *in_bp, STACK_OF(X509_INFO) *sk,
pem_password_cb *cb, void *u);
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
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.
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.
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.
BIO_new(3), d2i_PrivateKey(3), d2i_X509(3), d2i_X509_CRL(3),
EVP_PKEY_new(3), PEM_read(3), PEM_read_bio_PrivateKey(3), STACK_OF(3),
X509_CRL_new(3), X509_INFO_new(3), X509_new(3)
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.
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.
When reaching the end of the input, these functions call
ERR_clear_error(3), which may hide errors that occurred before calling
DragonFly 6.1-DEVELOPMENT March 12, 2021 DragonFly 6.1-DEVELOPMENT