NAME

PKCS7_final — read data from a BIO into a ContentInfo object

SYNOPSIS

library “libcrypto”
#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 arbitrary 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 default, line endings are replaced with two-byte "\r\n" sequences (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 setting 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 finalize 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 usable 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.