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

FreeBSD Manual Pages

  
 
  

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

NAME
     PEM_X509_INFO_read, PEM_X509_INFO_read_bio	-- PEM and DER decode X.509
     certificates, private keys, and revocation	lists

SYNOPSIS
     #include <openssl/pem.h>

     STACK_OF(X509_INFO) *
     PEM_X509_INFO_read(FILE *in_fp, STACK_OF(X509_INFO) *sk,
	 pem_password_cb *cb, void *u);

     STACK_OF(X509_INFO) *
     PEM_X509_INFO_read_bio(BIO	*in_bp,	STACK_OF(X509_INFO) *sk,
	 pem_password_cb *cb, void *u);

DESCRIPTION
     These functions read zero or more objects releated	to X.509 certificates
     from in_fp	or in_bp, perform both PEM and DER decoding, and wrap the re-
     sulting objects in	newly allocated	X509_INFO containers.

     Setting sk	to NULL	is recommended,	in which case a	new stack is allo-
     cated, populated, and returned.  If an existing sk	is passed in, the cre-
     ated X509_INFO objects are	pushed onto that stack.

     For PEM decoding, PEM_read_bio(3) is used internally, implying that any
     non-PEM data before, between, and after the objects is silently dis-
     carded.

     For subsequent DER	decoding, the decoding function	and the	field of the
     X509_INFO structure to store the new object in are	selected according to
     the PEM type name:

     PEM type name	    decoder		X509_INFO field
     CERTIFICATE	    d2i_X509(3)		certificate
     X509 CERTIFICATE	    d2i_X509(3)		certificate
     TRUSTED CERTIFICATE    d2i_X509_AUX(3)	certificate
     X509 CRL		    d2i_X509_CRL(3)	revocation list
     RSA PRIVATE KEY	    d2i_PrivateKey(3)	private	key
     DSA PRIVATE KEY	    d2i_PrivateKey(3)	private	key
     EC	PRIVATE	KEY	    d2i_PrivateKey(3)	private	key

     Whenever the selected field is already occupied, another new X509_INFO
     container is allocated and	pushed onto the	stack.	Depending on the se-
     quence of objects in the input, this can result in	several	partially pop-
     ulated X509_INFO containers being pushed onto the stack.

     PEM objects of types not listed in	the above table	are silently skipped.

     Encrypted certificates and	revocation lists are decrypted by calling
     PEM_do_header(3) internally, passing through the optional arguments cb
     and u.  Encrypted private keys are	not decrypted.	Instead, the encrypted
     form is stored as read.  All the same, PEM_get_EVP_CIPHER_INFO(3) is
     called internally to check	that PEM headers, if there are any, are	valid
     and specify an encryption the library is prepared to handle.

     If	any error occurs, objects that had already been	read during the	same
     call are deleted again and	sk is left unchanged.

RETURN VALUES
     These functions return a pointer to the stack the objects read were
     pushed onto or NULL if an error occurs.  They fail	if PEM_read_bio(3),
     PEM_get_EVP_CIPHER_INFO(3), PEM_do_header(3), or DER decoding fails or if
     memory is exhausted.

ERRORS
     Diagnostics that can be retrieved with ERR_get_error(3),
     ERR_GET_REASON(3),	and ERR_reason_error_string(3) include:

     ERR_R_ASN1_LIB "ASN1 lib"
	     DER decoding of a PEM object failed.

     ERR_R_BUF_LIB "BUF	lib"
	     PEM_X509_INFO_read() failed to set	up a temporary BIO, for	exam-
	     ple because memory	was exhausted.

     ERR_R_MALLOC_FAILURE "malloc failure"
	     PEM_X509_INFO_read_bio() failed to	allocate a new X509_INFO,
	     STACK_OF(X509_INFO), or X509_PKEY object.

     Additional	types of errors	can result from	PEM_read_bio(3),
     PEM_get_EVP_CIPHER_INFO(3), and PEM_do_header(3).

     After these functions failed due to memory	exhaustion, ERR_get_error(3)
     may sometimes return 0 anyway.

SEE ALSO
     BIO_new(3), d2i_PrivateKey(3), d2i_X509(3), d2i_X509_CRL(3),
     EVP_PKEY_new(3), PEM_read(3), PEM_read_bio_PrivateKey(3), STACK_OF(3),
     X509_CRL_new(3), X509_INFO_new(3),	X509_new(3)

HISTORY
     PEM_X509_INFO_read() first	appeared in SSLeay 0.5.1 and
     PEM_X509_INFO_read_bio() in SSLeay	0.6.0.	Both functions have been
     available since OpenBSD 2.4.

CAVEATS
     It	is not an error	if the input does not contain any objects of the de-
     sired types.  In that case, nothing is added to sk, or if sk is NULL, a
     newly allocated, empty stack is returned.	The only way to	detect this
     situation is by comparing the number of objects on	the stack before and
     after the call.

BUGS
     When reaching the end of the input, these functions call
     ERR_clear_error(3), which may hide	errors that occurred before calling
     these functions.

FreeBSD	13.0			 July 23, 2020			  FreeBSD 13.0

NAME | SYNOPSIS | DESCRIPTION | RETURN VALUES | ERRORS | SEE ALSO | HISTORY | CAVEATS | BUGS

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

home | help