GSP
Quick Navigator

Search Site

Unix VPS
A - Starter
B - Basic
C - Preferred
D - Commercial
MPS - Dedicated
Previous VPSs
* Sign Up! *

Support
Contact Us
Online Help
Handbooks
Domain Status
Man Pages

FAQ
Virtual Servers
Pricing
Billing
Technical

Network
Facilities
Connectivity
Topology Map

Miscellaneous
Server Agreement
Year 2038
Credits
 

USA Flag

 

 

Man Pages
PEM_X509_INFO_READ(3) FreeBSD Library Functions Manual PEM_X509_INFO_READ(3)

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

#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);

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.

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:
“ASN1 lib”
DER decoding of a PEM object failed.
“BUF lib”
PEM_X509_INFO_read() failed to set up a temporary BIO, for example because memory was exhausted.
“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_LOOKUP_new(3), X509_new(3), X509_PKEY_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 these functions.
October 19, 2021 FreeBSD 13.1-RELEASE

Search for    or go to Top of page |  Section 3 |  Main Index

Powered by GSP Visit the GSP FreeBSD Man Page Interface.
Output converted with ManDoc.