Manual Page Result
0
Command: PEM_ASN1_read | Section: 3 | Source: OpenBSD | File: PEM_ASN1_read.3
PEM_ASN1_READ(3) FreeBSD 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
#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.
FreeBSD 14.1-RELEASE-p8 July 23, 2020 FreeBSD 14.1-RELEASE-p8