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

FreeBSD Manual Pages

  
 
  

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

NAME
     PKCS7_dataInit -- construct a BIO chain for adding	or retrieving content

SYNOPSIS
     #include <openssl/pkcs7.h>

     BIO *
     PKCS7_dataInit(PKCS7 *p7, BIO *indata);

DESCRIPTION
     PKCS7_dataInit() constructs a BIO chain in	preparation for	putting	data
     into or retrieving	data out of p7.	 Depending on the contentType of p7,
     the created chain starts with:

     for SignedData:
	     one or more BIO_f_md(3) message digest filters

     for EnvelopedData:
	     one BIO_f_cipher(3) encryption filter

     for SignedAndEnvelopedData:
	     one or more BIO_f_md(3) message digest filters followed by	one
	     BIO_f_cipher(3) encryption	filter

     for DigestedData:
	     one BIO_f_md(3) message digest filter

     for arbitrary data:
	     no	filter BIO

     One additional BIO	is appended to the end of the chain, depending on the
     first condition that holds	in the following list:

     indata  if	the indata argument is not NULL.  This only makes sense	while
	     verifying a detached signature, in	which case indata is expected
	     to	supply the content associated with the detached	signature.

     BIO_s_null(3)
	     if	the contentType	of p7 is SignedData and	it is configured to
	     contain a detached	signature.  This only makes sense while	creat-
	     ing the detached signature.

     BIO_new_mem_buf(3)
	     when reading from a SignedData or DigestedData object.
	     PKCS7_dataInit() attaches the end of the chain to the nested con-
	     tent of p7.

     BIO_s_mem(3)
	     otherwise.	 This is the most common case while writing data to
	     p7.  PKCS7_dataFinal(3) can later be used to transfer the data
	     from the memory BIO into p7.

   Adding content
     Before calling PKCS7_dataInit() in	order to add content, PKCS7_new(3),
     PKCS7_set_type(3),	and PKCS7_content_new(3) are typically required	to
     create p7,	to choose its desired type, and	to allocate the	nested
     ContentInfo structure.  Alternatively, for	SignedData, PKCS7_sign(3) can
     be	used with the PKCS7_PARTIAL or PKCS7_STREAM flags or for
     EnvelopedData, PKCS7_encrypt(3) with the PKCS7_STREAM flag.

     After calling PKCS7_dataInit(), the desired data can be written into the
     returned BIO, BIO_flush(3)	can be called on it, PKCS7_dataFinal(3)	can be
     used to transfer the processed data from the returned memory BIO to the
     p7	structure, and the chain can finally be	destroyed with
     BIO_free_all(3).

     While PKCS7_dataInit() does support the EnvelopedData and
     SignedAndEnvelopedData types, using it for	these types is awkward and er-
     ror prone except when using PKCS7_encrypt(3) for the setup	because
     PKCS7_content_new(3) does not support these two types.  So	in addition to
     creating p7 itself	and setting its	type, the nested ContentInfo structure
     also needs	to be constructed with PKCS7_new(3) and	PKCS7_set_type(3) and
     manually inserted into the	correct	field of the respective	sub-structure
     of	p7.

   Retrieving content
     PKCS7_dataInit() can also be called on a fully populated object of	type
     SignedData	or DigestedData.  After	that, BIO_read(3) can be used to re-
     trieve data from it.  In this use case, do	not call PKCS7_dataFinal(3);
     simply proceed directly to	BIO_free_all(3)	after reading the data.

RETURN VALUES
     PKCS7_dataInit() returns a	BIO chain on success or	NULL on	failure.  It
     fails if p7 is NULL, if the content field of p7 is	empty, if the
     contentType of p7 is unsupported, if a cipher is required but none	is
     configured, or if any required operation fails, for example due to	lack
     of	memory or for various other reasons.

SEE ALSO
     BIO_new(3), BIO_read(3), PKCS7_content_new(3), PKCS7_dataFinal(3),
     PKCS7_encrypt(3), PKCS7_final(3), PKCS7_new(3), PKCS7_set_type(3),
     PKCS7_sign(3)

HISTORY
     PKCS7_dataInit() first appeared in	SSLeay 0.8.1 and has been available
     since OpenBSD 2.4.

CAVEATS
     This function does	not support EncryptedData.

BUGS
     If	p7 is a	fully populated	structure containing EnvelopedData,
     SignedAndEnvelopedData, or	arbitrary data,	PKCS7_dataInit() returns a BIO
     chain that	ultimately reads from an empty memory BIO, so reading from it
     will instantly return an end-of-file indication rather than reading the
     actual data contained in p7.

FreeBSD	13.0			 June 3, 2020			  FreeBSD 13.0

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

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

home | help