CMS_ADD1_RECIPIENT_CERT(3)

📦 version 4.4.0, in alpine 3.24, arch rolling

🌸 NAME 🌸

okay bestie, this is CMS_ADD1_RECIPIENT_CERT(3), and it's all about CMS_add1_recipient_cert and CMS_add0_recipient_key — literally the functions that add recipients to a CMS EnvelopedData structure. 💖

✨ SYNOPSIS ✨

You're linking the library “libcrypto”, and the include is exactly:

#include <openssl/cms.h>

CMS_RecipientInfo *
CMS_add1_recipient_cert(CMS_ContentInfo *cms, X509 *certificate,
    unsigned int flags);

CMS_RecipientInfo *
CMS_add0_recipient_key(CMS_ContentInfo *cms, int nid,
    unsigned char *key, size_t keylen, unsigned char *id, size_t idlen,
    ASN1_GENERALIZEDTIME *date, ASN1_OBJECT *otherTypeId,
    ASN1_TYPE *otherType);

🦋 DESCRIPTION 🦋

These functions add a new RecipientInfo structure to the recipientInfos field of the EnvelopedData structure cms, and that cms should have come from an initial call to CMS_encrypt(3) with the flag CMS_PARTIAL set. no cap. ✨

  • CMS_add1_recipient_cert() — adds the recipient certificate as a KeyTransRecipientInfo structure. 🎀
  • CMS_add0_recipient_key() — adds the symmetric key of length keylen using the wrapping algorithm nid, the identifier id of length idlen, and the optional values date, otherTypeId, and otherType as a KEKRecipientInfo structure. 🫶

The main purpose of these functions is to provide finer control over a CMS EnvelopedData structure where the simpler CMS_encrypt(3) function defaults are not appropriate, for example if one or more KEKRecipientInfo structures need to be added. New attributes can also be added using the returned CMS_RecipientInfo structure and the CMS attribute utility functions. 💅

By default, recipient certificates are identified using issuer name and serial number. If the flag CMS_USE_KEYID is set, the subject key identifier value is used instead. An error occurs if all recipient certificates do not have a subject key identifier extension. ⚠️

Currently only AES based key wrapping algorithms are supported for nid, specifically NID_id_aes128_wrap, NID_id_aes192_wrap, and NID_id_aes256_wrap. If nid is set to NID_undef, then an AES wrap algorithm will be used consistent with keylen. slay. 🔥

🥺 RETURN VALUES 🥺

CMS_add1_recipient_cert() and CMS_add0_recipient_key() return an internal pointer to the CMS_RecipientInfo structure just added or NULL if an error occurs. 💀

👀 SEE ALSO 👀

📚 STANDARDS 📚

RFC 5652: Cryptographic Message Syntax

  • section 6.1: EnvelopedData Type
  • section 6.2.1: KeyTransRecipientInfo Type
  • section 6.2.3: KEKRecipientInfo Type

🌈 HISTORY 🌈

CMS_add1_recipient_cert() and CMS_add0_recipient_key() first appeared in OpenSSL 0.9.8h and have been available since OpenBSD 6.7. iconic. 👑

okay that's the whole page, bestie. this one is from Debian, dated June 8, 2025 — CMS_ADD1_RECIPIENT_CERT(3), periodt. 💖✨

📦 where this page comes from