PKCS7_SIGN(3ossl)

📦 version 3.5.0, in opensuse-leap 16.0

✨ PKCS7_SIGN — create a PKCS#7 signedData structure ✨

okay bestie, so this is the OpenSSL manual for PKCS7_sign_ex and PKCS7_sign, from the pkcs7.h corner of the OpenSSL universe. it's giving "cryptographic paperwork" but honestly? kinda iconic. let's get into it 💅

🌸 SYNOPSIS 🌸

#include <openssl/pkcs7.h>

PKCS7 *PKCS7_sign_ex(X509 *signcert, EVP_PKEY *pkey, STACK_OF(X509) *certs,
                     BIO *data, int flags, OSSL_LIB_CTX *libctx,
                     const char *propq);
PKCS7 *PKCS7_sign(X509 *signcert, EVP_PKEY *pkey, STACK_OF(X509) *certs,
                  BIO *data, int flags);

💖 DESCRIPTION 💖

So PKCS7_sign_ex() creates and returns a PKCS#7 signedData structure. That's the whole vibe. 🫶

Here's who's who in the cast:

  • signcert — the certificate you're signing with, our main character 👑
  • pkey — the corresponding private key, the power behind the throne
  • certs — an optional set of extra certificates to include in the PKCS#7 structure (think: any intermediate CAs hanging out in the chain) 🌈
  • data — the data to be signed is read from this BIO. that's where the content comes from, no cap
  • libctx and propq — the library context and property query, used when retrieving algorithms from providers ✨

And flags is an optional set of flags, which we're gonna go through one by one because we're thorough like that.

🎀 the flags (ored together, bestie)

You can pass any of these, ored together, in the flags parameter:

  • PKCS7_TEXT — many S/MIME clients expect the signed content to include valid MIME headers, and if you set this, MIME headers for type "text/plain" get prepended to the data. cute little header bow 🎀
  • PKCS7_NOCERTS — the signer's certificate and the extra certs will not be included in the PKCS7 structure. important caveat though: the signer's certificate must still be supplied in the signcert parameter. this can reduce the size of the signatures if the signer's certs can be obtained by other means — for example, a previously signed message. lowkey efficient 💅
  • PKCS7_DETACHED — the data being signed is included in the PKCS7 structure unless this is set, in which case it's omitted. this is used for PKCS7 detached signatures, which are used in S/MIME plaintext signed messages for example. detached, aloof, mysterious 🦋
  • PKCS7_BINARY — normally the supplied content is translated into MIME canonical format (as required by the S/MIME specifications); if PKCS7_BINARY is set, no translation occurs. > ⚠️ use this option if the supplied data is in binary format, otherwise the translation will corrupt it. like, fr fr, don't skip this one.
  • PKCS7_NOATTR — the signedData structure includes several PKCS#7 authenticatedAttributes including the signing time, the PKCS#7 content type and the supported list of ciphers in an SMIMECapabilities attribute. if PKCS7_NOATTR is set then no authenticatedAttributes will be used. none. zero. ghosted 👻
  • PKCS7_NOSMIMECAP — if this is set then just the SMIMECapabilities are omitted. the rest of the attributes still show up.

🧚 a lil note on SMIMECapabilities

If present, the SMIMECapabilities attribute indicates support for the following algorithms: triple DES, 128 bit RC2, 64 bit RC2, DES and 40 bit RC2. If any of these algorithms is disabled then it will not be included. periodt. ⭐

🔥 the streaming flags

  • PKCS7_STREAM — if this flag is set, then the returned PKCS7 structure is just initialized, ready to perform the signing operation. the signing is however not performed, and the data to be signed is not read from the data parameter. signing is deferred until after the data has been written. in this way data can be signed in a single pass. one pass, one vibe, slay. ✨
🫶 careful bestie: if the flag PKCS7_STREAM is set, the returned PKCS7 structure is not complete, and outputting its contents via a function that does not properly finalize the PKCS7 structure will give unpredictable results. that's the undefined-behaviour warning, we don't play with that.

Several functions — including SMIME_write_PKCS7(), i2d_PKCS7_bio_stream(), PEM_write_bio_PKCS7_stream() — finalize the structure. alternatively, finalization can be performed by obtaining the streaming ASN1 BIO directly using BIO_new_PKCS7(). so many options, all valid 💜

  • PKCS7_PARTIAL — if this flag is set, a partial PKCS7 structure is output, to which additional signers and capabilities can be added before finalization. it's giving "work in progress, but make it cryptographic" 🙈

🌟 digests, NULLs, and the partial life

If a signer is specified, it will use the default digest for the signing algorithm. this is SHA1 for both RSA and DSA keys. yes, SHA1, we know, it's old, but that's what the manpage says and we report the facts 💀

The certs, signcert and pkey parameters can all be NULL if the PKCS7_PARTIAL flag is set. one or more signers can be added using the function PKCS7_sign_add_signer(). PKCS7_final() must also be called to finalize the structure if streaming is not enabled. alternative signing digests can also be specified using this method. so much flexibility, obsessed. 💖

If signcert and pkey are NULL then a certificates only PKCS#7 structure is output. no signing, just certs, living its truth. 🦋

📜 history check: in versions of OpenSSL before 1.0.0, the signcert and pkey parameters must not be NULL. different era, different rules.

And finally, PKCS7_sign() is like PKCS7_sign_ex() except that it uses default values of NULL for the library context libctx and the property query propq. this is retained for API backward compatibility. the classic, the original, the blueprint ✨

💀 BUGS 💀

Some advanced attributes such as counter signatures are not supported. that's it, that's the bug section. we respect the honesty.

🌈 RETURN VALUES 🌈

PKCS7_sign_ex() and PKCS7_sign() return either a valid PKCS7 structure or NULL if an error occurred. the error can be obtained from ERR_get_error(3). so if you get NULL, don't panic — go ask ERR_get_error(3) what happened, it always spills the tea 🍓

🫶 SEE ALSO 🫶

ERR_get_error(3), PKCS7_verify(3)

👑 HISTORY 👑

  • The function PKCS7_sign_ex() was added in OpenSSL 3.0.
  • The PKCS7_PARTIAL flag, and the ability for certs, signcert, and pkey parameters to be NULL, were added in OpenSSL 1.0.0.
  • The PKCS7_STREAM flag was added in OpenSSL 1.0.0.

Copyright 2002-2023 The OpenSSL Project Authors. All Rights Reserved.

Licensed under the Apache License 2.0 (the "License"). You may not use this file except in compliance with the License. You can obtain a copy in the file LICENSE in the source distribution or at <https://www.openssl.org/source/license.html>.

and that's the whole page bestie!! 💅✨ this one's from OpenSSL 3.5.0, dated 2026-09-25 — screenshot it, cite it, live by it. mwah 🫶💖

📦 where this page comes from