PKCS7_FINAL(3) | Library Functions Manual | PKCS7_FINAL(3)

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

June 8, 2025 | Debian