DragonFly On-Line Manual Pages
PKCS7_FINAL(3) DragonFly Library Functions Manual PKCS7_FINAL(3)
PKCS7_final - read data from a BIO into a ContentInfo object
PKCS7_final(PKCS7 *p7, BIO *data, int flags);
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
PKCS7_TEXT Prepend "Content-Type: text/plain" followed by a blank line
to the data. This flag is ignored if PKCS7_BINARY is also
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).
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
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.
DragonFly 6.1-DEVELOPMENT June 4, 2020 DragonFly 6.1-DEVELOPMENT