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

FreeBSD Manual Pages


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

     PKCS7_final -- read data from a BIO into a	ContentInfo object

     #include <openssl/pkcs7.h>

     PKCS7_final(PKCS7 *p7, BIO	*data, int flags);

     PKCS7_final() reads data and puts it into the appropriate content field
     of	p7 itself or of	its appropriate	substructure, which can	be of type
     SignedData, EnvelopedData,	SignedAndEnvelopedData,	DigestedData, or arbi-
     trary data.  The PKCS7_dataFinal(3) manual	explains which field exactly
     the data is put into.

     The following flags are recognized:

     PKCS7_BINARY  Copy	the data verbatim without changing any bytes.  By de-
		   fault, line endings are replaced with two-byte "\r\n" se-
		   quences (ASCII CR+LF).  If this flag	is set,	PKCS7_TEXT is

     PKCS7_TEXT	   Prepend "Content-Type: text/plain" followed by a blank line
		   to the data.	 This flag is ignored if PKCS7_BINARY is also

     If	any other bits are set in flags, for example PKCS7_STREAM or
     PKCS7_PARTIAL, they are ignored, allowing to pass the same	flags argument
     that was already passed to	PKCS7_sign(3) or PKCS7_encrypt(3).

     PKCS7_final() is most commonly used to finalize a p7 object returned from
     a call to PKCS7_sign(3) that used flags including PKCS7_PARTIAL or
     PKCS7_STREAM.  With these flags, PKCS7_sign(3) ignores its	data argument.
     The partial p7 object returned can	then be	customized, for	example	set-
     ting up multiple signers or non-default digest algorithms with
     PKCS7_sign_add_signer(3), before calling PKCS7_final().

     Similarly,	PKCS7_final() can be used to finalize a	p7 object returned
     from a call to PKCS7_encrypt(3) that used flags including PKCS7_STREAM.

     Since PKCS7_final() starts	by calling PKCS7_dataInit(3) internally, using
     it	to finalize a p7 object	containing SignedAndEnvelopedData,
     DigestedData, or arbitrary	data requires the setup	described in the
     PKCS7_dataInit(3) manual.	For SignedData and EnvelopedData, such manual
     setup is also feasible, but it is more easily performed with
     PKCS7_sign(3) or PKCS7_encrypt(3),	respectively.

     PKCS7_final() is only one among several functions that can	be used	to fi-
     nalize p7;	alternatives include SMIME_write_PKCS7(3),
     PEM_write_bio_PKCS7_stream(3), and	i2d_PKCS7_bio_stream(3).

     PKCS7_final() returns 1 on	success	or 0 on	failure.

     Possible reasons for failure include:

       -  p7 is	NULL.
       -  The content field of p7 is empty.
       -  The contentType of p7	is unsupported.
       -  Signing or digesting is requested and	p7 is not configured to	store
	  a detached signature,	but does not contain the required field	to
	  store	the content either.
       -  At least one signer lacks a useable digest algorithm.
       -  A cipher is required but none	is configured.
       -  Any required operation fails,	for example signing or digesting.
       -  Memory allocation fails.

     Signers lacking private keys do not cause failure but are silently

     BIO_new(3), i2d_PKCS7_bio_stream(3), PEM_write_bio_PKCS7_stream(3),
     PKCS7_add_attribute(3), PKCS7_dataFinal(3), PKCS7_dataInit(3),
     PKCS7_encrypt(3), PKCS7_new(3), PKCS7_sign(3), SMIME_write_PKCS7(3)

     PKCS7_final() first appeared in OpenSSL 1.0.0 and has been	available
     since OpenBSD 4.9.

     This function does	not support EncryptedData.

FreeBSD	13.0			 June 4, 2020			  FreeBSD 13.0


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

home | help