PEM_ASN1_READ(3) | Library Functions Manual | PEM_ASN1_READ(3)

# NAME

`d2i_of_void`, `PEM_ASN1_read`, `PEM_ASN1_read_bio` — PEM and DER decode an arbitrary ASN.1 value

# SYNOPSIS

library “libcrypto”
`#include <openssl/pem.h>`

typedef void *
`d2i_of_void`(void **val_out, const unsigned char **der_in, long length);

void *
`PEM_ASN1_read`(d2i_of_void *d2i, const char *name, FILE *in_fp, void **val_out, pem_password_cb *cb, void *u);

void *
`PEM_ASN1_read_bio`(d2i_of_void *d2i, const char *name, BIO *in_bp, void **val_out, pem_password_cb *cb, void *u);

# DESCRIPTION

These functions read one object from in_fp or in_bp and perform both PEM and DER decoding. They are needed when more specific decoding functions like those documented in PEM_read_bio_PrivateKey(3) and PEM_read_SSL_SESSION(3) are inadequate for the type name.

For PEM decoding, PEM_bytes_read_bio(3) is called internally. Consequently, the first object of type name is returned and preceding objects of other types are discarded. If necessary, data is decrypted, using cb and/or u if they are not `NULL`, as described in the pem_password_cb(3) manual page.

For subsequent DER decoding, pass a d2i callback function that is adequate for the type name, typically returning a pointer of a type more specific than void *. For example, d2i_ASN1_TYPE(3) can always be used and its manual page describes the required behaviour of the callback function to be passed. Normally, passing a more specific function is more useful; candidate functions can be found with ‘`man -k Nm~^d2i_`’.

For the name argument, the `PEM_STRING_*` string constants defined in `<openssl/pem.h>` can be used.

The val_out argument is useless and its many dangers are described in detail in the d2i_ASN1_TYPE(3) manual page. To reduce the risk of bugs, always passing `NULL` is recommended.

# RETURN VALUES

These functions return a pointer to the decoded object or `NULL` if an error occurs. They fail if PEM_bytes_read_bio(3) fails, for example because of invalid syntax in the input, an unknown encryption, or an invalid passphrase entered by the user. They also fail if d2i returns `NULL`, for example due to DER decoding errors.

`PEM_ASN1_read`() may also fail if memory is exhausted.

# EXAMPLES

Typical usage of `PEM_ASN1_read`() is demonstrated by the implementation of the more specific function to PEM and DER decode an X.509 certificate:

    X509 *
    PEM_read_X509(FILE *fp, X509 **val_out, pem_password_cb *cb, void *u)
    {
    	return PEM_ASN1_read((d2i_of_void *)d2i_X509, PEM_STRING_X509,
    	    fp, (void **)val_out, cb, u);
    }

# ERRORS

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

`ERR_R_BUF_LIB` "BUF lib"
  `PEM_ASN1_read`() failed to set up a temporary BIO, for example because memory was exhausted.
`ERR_R_ASN1_LIB` "ASN1 lib"
  d2i returned `NULL`, for example due to a DER syntax error.

Additional types of errors can result from PEM_bytes_read_bio(3).

# SEE ALSO

BIO_new(3), d2i_ASN1_TYPE(3), PEM_bytes_read_bio(3), PEM_read(3), PEM_read_bio_PrivateKey(3), PEM_read_SSL_SESSION(3), PEM_X509_INFO_read_bio(3)

# HISTORY

These functions first appeared in SSLeay 0.5.1 and have been available since OpenBSD 2.4.

July 16, 2025 | Debian