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.
SEE ALSO
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_LOOKUP_new(3), X509_new(3)
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.