PKCS7_DATAFINAL(3) | Library Functions Manual | PKCS7_DATAFINAL(3) |
NAME
PKCS7_dataFinal
—
move data from a BIO chain to a ContentInfo
object
SYNOPSIS
#include
<openssl/pkcs7.h>
int
PKCS7_dataFinal
(PKCS7 *p7,
BIO *chain);
DESCRIPTION
PKCS7_dataFinal
()
transfers the data from the memory BIO at the end of the given
chain into the appropriate content field of
p7 itself or of its appropriate substructure. It is
typically used as the final step of populating p7,
after creating the chain with
PKCS7_dataInit(3) and
after writing the data into it.
After calling
PKCS7_dataFinal
(),
the program can call
BIO_free_all(3) on the
chain because such chains are not designed for
reuse.
Depending on the
contentType of p7,
PKCS7_dataFinal
()
sets the following fields:
- for SignedData or DigestedData:
- in substructures of the content field of p7: the content field in the ContentInfo structure (unless p7 is configured to store a detached signature) and the encryptedDigest fields in all the SignerInfo structures
- for EnvelopedData or SignedAndEnvelopedData:
- the encryptedContent field in the EncryptedContentInfo structure contained in the content field of p7
- for arbitrary data:
- the content field of p7 itself
RETURN VALUES
PKCS7_dataFinal
() 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.
- The chain does not contain the expected memory BIO.
- 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.
- Signing or digesting fails.
- Memory allocation fails.
Signers lacking private keys do not cause failure but are silently skipped.
SEE ALSO
BIO_new(3), PKCS7_dataInit(3), PKCS7_final(3), PKCS7_new(3), PKCS7_sign(3)
HISTORY
PKCS7_dataFinal
() first appeared in SSLeay
0.9.1 and has been available since OpenBSD 2.6.
CAVEATS
This function does not support EncryptedData.
Even though this function is typically used after
PKCS7_dataInit(3) and even
though PKCS7_dataInit(3)
also supports reading from ContentInfo structures that
are already fully populated, do not use
PKCS7_dataFinal
() on fully populated structures. It
is only intended for putting data into new structures and it is neither
needed nor suitable for reading.
December 26, 2022 | Linux 6.8.2-arch2-1 |