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

FreeBSD Manual Pages

  
 
  

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

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

SYNOPSIS
     #include <openssl/pkcs7.h>

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

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

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

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

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

SEE ALSO
     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)

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

CAVEATS
     This function does	not support EncryptedData.

FreeBSD	13.0			 June 4, 2020			  FreeBSD 13.0

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

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

home | help