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.