PKCS7_DATAINIT(3)

📦 version 4.1.0, in opensuse-leap 16.0

💅 PKCS7_dataInit 💅

okay bestie, this little icon lives in the Library Functions Manual, and it’s giving “build me a BIO chain so I can put content into p7 or pull content out of p7” energy. no cap. 🫶

🌸 NAME 🌸

PKCS7_dataInit — construct a BIO chain for adding or retrieving content, periodt.

✨ SYNOPSIS ✨

#include <openssl/pkcs7.h>

BIO *
PKCS7_dataInit(PKCS7 *p7, BIO *indata);

💖 DESCRIPTION 💖

PKCS7_dataInit() constructs a BIO chain in preparation for putting data into p7 or retrieving data out of p7. Depending on the contentType of p7, the created chain starts with:

  • for SignedData: one or more BIO_f_md(3) message digest filters
  • for EnvelopedData: one BIO_f_cipher(3) encryption filter
  • for SignedAndEnvelopedData: one or more BIO_f_md(3) message digest filters followed by one BIO_f_cipher(3) encryption filter
  • for DigestedData: one BIO_f_md(3) message digest filter
  • for arbitrary data: no filter BIO

Then one extra BIO gets appended to the end of the chain — and it’s the first condition that holds in this list that wins:

  • indata — if the indata argument is not NULL. This only makes sense while verifying a detached signature, in which case indata is expected to supply the content associated with the detached signature.
  • BIO_s_null(3) — if the contentType of p7 is SignedData and it is configured to contain a detached signature. This only makes sense while creating the detached signature.
  • BIO_new_mem_buf(3) — when reading from a SignedData or DigestedData object. PKCS7_dataInit() attaches the end of the chain to the nested content of p7.
  • BIO_s_mem(3) — otherwise. This is the most common case while writing data to p7. PKCS7_dataFinal(3) can later be used to transfer the data from the memory BIO into p7.

🎀 Adding content 🎀

Before calling PKCS7_dataInit() in order to add content, PKCS7_new(3), PKCS7_set_type(3), and PKCS7_content_new(3) are typically required to create p7, to choose its desired type, and to allocate the nested ContentInfo structure. Alternatively, for SignedData, PKCS7_sign(3) can be used with the PKCS7_PARTIAL or PKCS7_STREAM flags — or for EnvelopedData, PKCS7_encrypt(3) with the PKCS7_STREAM flag. slay. ✨

After calling PKCS7_dataInit(), the desired data can be written into the returned BIO, BIO_flush(3) can be called on it, PKCS7_dataFinal(3) can be used to transfer the processed data from the returned memory BIO to the p7 structure, and the chain can finally be destroyed with BIO_free_all(3). cute, clean, done. 💅

While PKCS7_dataInit() does support the EnvelopedData and SignedAndEnvelopedData types, using it for these types is awkward and error prone except when using PKCS7_encrypt(3) for the setup because PKCS7_content_new(3) does not support these two types. So in addition to creating p7 itself and setting its type, the nested ContentInfo structure also needs to be constructed with PKCS7_new(3) and PKCS7_set_type(3) and manually inserted into the correct field of the respective sub-structure of p7. yes, it’s giving manual-labour era. 😭

🦋 Retrieving content 🦋

PKCS7_dataInit() can also be called on a fully populated object of type SignedData or DigestedData. After that, BIO_read(3) can be used to retrieve data from it. In this use case, do not call PKCS7_dataFinal(3); simply proceed directly to BIO_free_all(3) after reading the data. that’s the whole vibe. 🫶

🔥 RETURN VALUES 🔥

PKCS7_dataInit() returns a BIO chain on success or NULL on failure. It fails if p7 is NULL, if the content field of p7 is empty, if the contentType of p7 is unsupported, if a cipher is required but none is configured, or if any required operation fails — for example due to lack of memory or for various other reasons. so yeah, it can absolutely fold. 💀

🌈 SEE ALSO 🌈

BIO_new(3), BIO_read(3), PKCS7_content_new(3), PKCS7_dataFinal(3), PKCS7_encrypt(3), PKCS7_final(3), PKCS7_new(3), PKCS7_set_type(3), PKCS7_sign(3)

⭐ HISTORY ⭐

PKCS7_dataInit() first appeared in SSLeay 0.8.1 and has been available since OpenBSD 2.4. vintage but make it useful. 👑

💀 CAVEATS 💀

🚨 this function does not support EncryptedData. not me finding out the hard way. 🙈

🙈 BUGS 🙈

😭 if p7 is a fully populated structure containing EnvelopedData, SignedAndEnvelopedData, or arbitrary data, PKCS7_dataInit() returns a BIO chain that ultimately reads from an empty memory BIO, so reading from it will instantly return an end-of-file indication rather than reading the actual data contained in p7.

source/version: Debian 💖 — date: June 3, 2020 🎀 — and that’s the cute little sign-off, bestie. periodt. ✨

📦 where this page comes from