NAME

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

SYNOPSIS

#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(3)

HISTORY

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