CMS_GET0_RECIPIENTINFOS(3)

💖 CMS_GET0_RECIPIENTINFOS(3) 💖

okay so bestie, welcome to the Library Functions Manual page for CMS_GET0_RECIPIENTINFOS(3) — this is the whole CMS EnvelopedData RecipientInfo situation, and it's lowkey iconic because it lets your app do recipient-key detective work by hand instead of just calling the simpler CMS_decrypt(3). no cap, it's giving ✨plumbing✨. Let's go.

🎀 NAME 🎀

CMS_get0_RecipientInfos, CMS_RecipientInfo_type, CMS_RecipientInfo_ktri_get0_signer_id, CMS_RecipientInfo_ktri_cert_cmp, CMS_RecipientInfo_set0_pkey, CMS_RecipientInfo_kekri_get0_id, CMS_RecipientInfo_kekri_id_cmp, CMS_RecipientInfo_set0_key, CMS_RecipientInfo_decrypt, CMS_RecipientInfo_encrypt — CMS EnvelopedData RecipientInfo routines

✨ SYNOPSIS ✨

library “libcrypto” #include <openssl/cms.h>

STACK_OF(CMS_RecipientInfo) *
CMS_get0_RecipientInfos(CMS_ContentInfo *cms);

int
CMS_RecipientInfo_type(CMS_RecipientInfo *ri);

int
CMS_RecipientInfo_ktri_get0_signer_id(CMS_RecipientInfo *ri,
    ASN1_OCTET_STRING **keyid, X509_NAME **issuer, ASN1_INTEGER **sno);

int
CMS_RecipientInfo_ktri_cert_cmp(CMS_RecipientInfo *ri,
    X509 *certificate);

int
CMS_RecipientInfo_set0_pkey(CMS_RecipientInfo *ri, EVP_PKEY *pkey);

int
CMS_RecipientInfo_kekri_get0_id(CMS_RecipientInfo *ri,
    X509_ALGOR **palg, ASN1_OCTET_STRING **pid,
    ASN1_GENERALIZEDTIME **pdate, ASN1_OBJECT **potherid,
    ASN1_TYPE **pothertype);

int
CMS_RecipientInfo_kekri_id_cmp(CMS_RecipientInfo *ri,
    const unsigned char *id, size_t idlen);

int
CMS_RecipientInfo_set0_key(CMS_RecipientInfo *ri, unsigned char *key,
    size_t keylen);

int
CMS_RecipientInfo_decrypt(CMS_ContentInfo *cms, CMS_RecipientInfo *ri);

int
CMS_RecipientInfo_encrypt(CMS_ContentInfo *cms, CMS_RecipientInfo *ri);

💅 DESCRIPTION 💅

Okay so here's the rundown, function by function, and I'm not skipping a single crumb:

• CMS_get0_RecipientInfos() — returns all the RecipientInfo structures associated with the EnvelopedData structure cms. It's giving "gimme the whole stack" 💅.
• CMS_RecipientInfo_type() — returns the type of ri: CMS_RECIPINFO_TRANS for KeyTransRecipientInfo, CMS_RECIPINFO_AGREE for KeyAgreeRecipientInfo, CMS_RECIPINFO_KEK for KEKRecipientInfo, CMS_RECIPINFO_PASS for PasswordRecipientinfo, or CMS_RECIPINFO_OTHER for OtherRecipientInfo.
• CMS_RecipientInfo_ktri_get0_signer_id() — retrieves the certificate RecipientIdentifier associated with the KeyTransRecipientInfo structure ri. Either the SubjectKeyIdentifier will be set in keyid or both issuer name and serial number in issuer and sno.
• CMS_RecipientInfo_ktri_cert_cmp() — compares the certificate against the KeyTransRecipientInfo structure ri.
• CMS_RecipientInfo_set0_pkey() — associates the private key pkey with the KeyTransRecipientInfo structure ri.
• CMS_RecipientInfo_kekri_get0_id() — retrieves the key information from the KEKRecipientInfo structure ri. Fields are copied out as follows: keyEncryptionAlgorithm to *palg, keyIdentifier to *pid, date to *pdate (optional), other.keyAttrId to *potherid (optional), other.keyAttr to *pothertype (optional). Where a field is optional and absent, NULL is written to the corresponding parameter. Parameters the application is not interested in can be set to NULL.
• CMS_RecipientInfo_kekri_id_cmp() — compares the identifier in the id and idlen parameters against the keyIdentifier field of the KEKRecipientInfo structure ri.
• CMS_RecipientInfo_set0_key() — associates the symmetric key of length keylen with the KEKRecipientInfo structure ri.
• CMS_RecipientInfo_decrypt() — attempts to decrypt the RecipientInfo structure ri in cms. A key must have been associated with ri first. 🫶
• CMS_RecipientInfo_encrypt() — attempts to encrypt the RecipientInfo structure ri in cms. A key must have been associated with ri first and the content encryption key must be available, for example by a previous call to CMS_RecipientInfo_decrypt().

The main purpose of these functions is to enable an application to lookup recipient keys using any appropriate technique when the simpler method of CMS_decrypt(3) is not appropriate. Basically: when CMS_decrypt(3) isn't the vibe, you get to do the lookup yourself.

In typical usage, an application retrieves all CMS_RecipientInfo structures using CMS_get0_RecipientInfos() and checks the type of each using CMS_RecipientInfo_type(). Depending on the type, the CMS_RecipientInfo structure can be ignored or its key identifier data retrieved using an appropriate function. If the corresponding secret or private key can be obtained by any appropriate means, it can then be associated with the structure and CMS_RecipientInfo_decrypt() called. If successful, CMS_decrypt(3) can be called with a NULL key to decrypt the enveloped content.

The function CMS_RecipientInfo_encrypt() can be used to add a new recipient to an existing enveloped data structure. Typically an application will first decrypt an appropriate CMS_RecipientInfo structure to make the content encrypt key available. It will then add a new recipient using a function such as CMS_add1_recipient_cert(3) and finally encrypt the content encryption key using CMS_RecipientInfo_encrypt().

🔥 RETURN VALUES 🔥

• CMS_get0_RecipientInfos() — returns an internal pointer to all the CMS_RecipientInfo structures, or NULL if an error occurs.
• CMS_RecipientInfo_type() — returns an integer constant.
• CMS_RecipientInfo_ktri_get0_signer_id(), CMS_RecipientInfo_set0_pkey(), CMS_RecipientInfo_kekri_get0_id(), CMS_RecipientInfo_set0_key(), CMS_RecipientInfo_decrypt(), and CMS_RecipientInfo_encrypt() — return 1 for success or 0 if an error occurs.
• CMS_RecipientInfo_ktri_cert_cmp() and CMS_RecipientInfo_kekri_id_cmp() — return 0 when ri matches or non-zero otherwise.
• Any error can be obtained from ERR_get_error(3).

🦋 SEE ALSO 🦋

• CMS_ContentInfo_new(3)
• CMS_decrypt(3)

🌈 STANDARDS 🌈

RFC 5652 Cryptographic Message Syntax (CMS):

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

🌸 HISTORY 🌸

These functions first appeared in OpenSSL 0.9.8h, except that CMS_RecipientInfo_encrypt() first appeared in OpenSSL 1.0.2. They have been available since OpenBSD 6.7.

---

okay that's the whole page, bestie. this Debian version is dated June 8, 2025, and it's for CMS_GET0_RECIPIENTINFOS(3) — go decrypt something cute 💖✨ periodt.