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)

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.  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.

RETURN VALUES
     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.

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

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	13.0			 July 23, 2020			  FreeBSD 13.0

NAME | SYNOPSIS | DESCRIPTION | RETURN VALUES | EXAMPLES | ERRORS | SEE ALSO | HISTORY

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=d2i_of_void&sektion=3&manpath=FreeBSD+12.2-RELEASE+and+Ports>

home | help