Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages


home | help
PEM_ASN1_READ(3)       FreeBSD Library Functions Manual	      PEM_ASN1_READ(3)

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

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

     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.  Conse-
     quently, 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 ade-
     quate 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 de-
     tail in the d2i_ASN1_TYPE(3) manual page.	To reduce the risk of bugs,
     always passing NULL is recommended.

     These functions return a pointer to the decoded object or NULL if an er-
     ror occurs.  They fail if PEM_bytes_read_bio(3) fails, for	example	be-
     cause of invalid syntax in	the input, an unknown encryption, or an	in-
     valid 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.

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

     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 be-
	     cause 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).

     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),

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

FreeBSD	13.0			 July 23, 2020			  FreeBSD 13.0


Want to link to this manual page? Use this URL:

home | help