NAME

SYNOPSIS

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

DESCRIPTION

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

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

HISTORY

CAVEATS