OpenBSD manual page server

Manual Page Search Parameters

PKCS7_FINAL(3) Library Functions Manual PKCS7_FINAL(3)

PKCS7_finalread data from a BIO into a ContentInfo object

#include <openssl/pkcs7.h>

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

() 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:

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

() 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, () can be used to finalize a p7 object returned from a call to PKCS7_encrypt(3) that used flags including PKCS7_STREAM.

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

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

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

Possible reasons for failure include:

Signers lacking private keys do not cause failure but are silently skipped.

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.

December 26, 2022 OpenBSD-current