PKCS7_SIGN_ADD_SIGNER(3SSL)

📦
version 4.0.3 · 11 versions
, in ubuntu stonking

💖 NAME 💖

PKCS7_sign_add_signer, PKCS7_add_certificate, PKCS7_add_crl — okay bestie, these three are the little helpers that add info to a PKCS7 structure. Not the whole assemble-the-thing energy, just the ✨add stuff✨ energy. They live in the OpenSSL manual, section 3SSL, and honestly they're icons.

📜 SYNOPSIS 📜

#include <openssl/pkcs7.h>

PKCS7_SIGNER_INFO *PKCS7_sign_add_signer(PKCS7 *p7, X509 *signcert,
                                         EVP_PKEY *pkey, const EVP_MD *md, int flags);
int PKCS7_add_certificate(PKCS7 *p7, X509 *cert);
int PKCS7_add_crl(PKCS7 *p7, X509_CRL *crl);

🌸 DESCRIPTION 🌸

So PKCS7_sign_add_signer() is the main character here: it adds a signer to a PKCS7 signed data structure p7, using the certificate signcert, the private key pkey, and the message digest md. Three things in, one signer out, slay. 🫶

Where does p7 come from tho? It should come from a first call to PKCS7_sign() where you set the PKCS7_PARTIAL flag — or from the case of re-signing a valid PKCS#7 signed data structure. iykyk. ✨

If md is NULL, then the default digest for the public key algorithm gets used instead. No stress.

And unless the PKCS7_REUSE_DIGEST flag is set, the PKCS7 structure you get back is not complete — it still has to be finalized, either by streaming (if that even applies to you) or by calling PKCS7_final(). Don't forget this part, fr fr, or your structure is just gonna be sitting there half-done. 😭

👑 NOTES 👑

Okay so the whole point of this function is finer control over a PKCS#7 signed data structure for when the simpler PKCS7_sign() function defaults just aren't giving what you need. Like, multiple signers? Non-default digest algorithms? Yeah, that's this function's moment. 💅

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

  • If PKCS7_REUSE_DIGEST is set, it tries to copy the content digest value from the PKCS7 structure — this is how you add a signer to an existing structure. If a matching digest value can't be found to copy, that's an error. When this flag is set, the PKCS7 structure you get back will be valid and finalized. ✅
  • If PKCS7_PARTIAL is set in addition to PKCS7_REUSE_DIGEST, then the PKCS7_SIGNER_INO structure will not be finalized, so you can add extra attributes to it. In that case you need an explicit call to PKCS7_SIGNER_INFO_sign() to finalize it. No skipping that step bestie.
  • If PKCS7_NOCERTS is set, the signer's certificate will not be included in the PKCS7 structure — but you still have to supply the signer's certificate in the signcert parameter anyway. It can shrink the signature size if the signer's cert can be obtained some other way, like from a previously signed message. Work smarter 🧚
  • 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 get used at all. If PKCS7_NOSMIMECAP is set, then just the SMIMECapabilities are omitted.
  • If it's there, the SMIMECapabilities attribute indicates support for these algorithms: triple DES, 128 bit RC2, 64 bit RC2, DES and 40 bit RC2. And if any of these algorithms is disabled, it won't be included. Simple as that. ✨

PKCS7_sign_add_signers() returns an internal pointer to the PKCS7_SIGNER_INFO structure that was just added — you can use it to set extra attributes before it gets finalized. Handy.

Then we have PKCS7_add_certificate(), which adds the certificate cert to the PKCS7 structure p7. That cert can be an end-entity (signer) certificate or a CA certificate useful for chain building. This is done internally by PKCS7_sign_ex(3) and all the similar signing functions. You might have to use it before calling PKCS7_verify(3) to provide any missing certificate(s) needed for verification. 🎀

And PKCS7_add_crl() adds the CRL crl to the PKCS7 structure p7. You can call this to provide certificate status information to be included when signing, or to use it when verifying the PKCS7 structure.

💀 RETURN VALUES 💀

PKCS7_sign_add_signers() returns an internal pointer to the PKCS7_SIGNER_INFO structure that was just added, or NULL if an error happens. 😭

PKCS7_add_certificate() and PKCS7_add_crl() return 1 on success, 0 on error. That's it, that's the vibe check.

🦋 SEE ALSO 🦋

ERR_get_error(3), PKCS7_sign_ex(3), PKCS7_final(3), PKCS7_verify(3)

🌈 HISTORY 🌈

The PPKCS7_sign_add_signer() function was added in OpenSSL 1.0.0. Iconic behavior since day one, honestly.

Copyright 2007-2016 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>.

🎀 aaaand that's the whole page bestie — no cap, you now know this manpage better than the back of your hand. go forth and add signers responsibly 💖✨

version 4.0.3 · dated 2026-09-29 · OpenSSL, obviously 💅

📦 where this page comes from