CMS_GET0_RECIPIENTINFOS(3ossl)

💖 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_kari_set0_pkey_and_peer, CMS_RecipientInfo_kari_set0_pkey, CMS_RecipientInfo_kekri_id_cmp, CMS_RecipientInfo_set0_key, CMS_RecipientInfo_decrypt, CMS_RecipientInfo_encrypt — bestie, these are the CMS envelopedData RecipientInfo routines. This is 3ossl erasure, we are in the OpenSSL manual, and yes it's giving ✨cryptography✨.

---

🌸 SYNOPSIS 🌸

#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 *cert);
int CMS_RecipientInfo_set0_pkey(CMS_RecipientInfo *ri, EVP_PKEY *pkey);
int CMS_RecipientInfo_kari_set0_pkey_and_peer(CMS_RecipientInfo *ri,
                                              EVP_PKEY *pk, X509 *peer);
int CMS_RecipientInfo_kari_set0_pkey(CMS_RecipientInfo *ri, EVP_PKEY *pk);
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, story time. Here's what every single one of these does, no skips, no summarising, we're doing the full read 💅

• CMS_get0_RecipientInfos() — hands you all the CMS_RecipientInfo structures that are associated with a CMS EnvelopedData structure. The whole squad. Every recipient, front to back.
• CMS_RecipientInfo_type() — tells you what kind of CMS_RecipientInfo structure ri is. rn it will return one of CMS_RECIPINFO_TRANS, CMS_RECIPINFO_AGREE, CMS_RECIPINFO_KEK, CMS_RECIPINFO_PASS, or CMS_RECIPINFO_OTHER. Vibe check for recipient infos, basically.
• CMS_RecipientInfo_ktri_get0_signer_id() — pulls out the certificate recipient identifier attached to a specific CMS_RecipientInfo structure ri, and ri must be of type CMS_RECIPINFO_TRANS. Either the keyidentifier gets set in keyid, or both the issuer name and serial number land in issuer and sno. One or the other, bestie.
• CMS_RecipientInfo_ktri_cert_cmp() — compares the certificate cert against the CMS_RecipientInfo structure ri, and ri must be of type CMS_RECIPINFO_TRANS. Returns zero if the comparison slays (successful) and non zero if it does not.
• CMS_RecipientInfo_set0_pkey() — associates the private key pkey with the CMS_RecipientInfo structure ri, which must be of type CMS_RECIPINFO_TRANS. It's giving "here's the key, go off".
• CMS_RecipientInfo_kari_set0_pkey_and_peer() — associates the private key pkey and the peer certificate peer with the CMS_RecipientInfo structure ri, which must be of type CMS_RECIPINFO_AGREE. Two-for-one, iconic.
• CMS_RecipientInfo_kari_set0_pkey() — associates the private key pkey with the CMS_RecipientInfo structure ri, which must be of type CMS_RECIPINFO_AGREE.
• CMS_RecipientInfo_kekri_get0_id() — retrieves the key information from the CMS_RecipientInfo structure ri, which must be of type CMS_RECIPINFO_KEK. Any of the remaining parameters can be NULL if the application simply does not care about the value of that field, and that's fine, we respect it. Where a field is optional and absent, NULL will be written to the corresponding parameter. So: the keyEncryptionAlgorithm field goes to palg, the keyIdentifier field goes to pid, the date field if present goes to pdate, and if the other field is present, its components keyAttrId and keyAttr go to the parameters potherid and pothertype.
• CMS_RecipientInfo_kekri_id_cmp() — compares the ID in the id and idlen parameters against the keyIdentifier of the CMS_RecipientInfo structure ri, which must be of type CMS_RECIPINFO_KEK. Returns zero if the comparison is successful and non zero if not. Same energy as the cert one.
• CMS_RecipientInfo_set0_key() — associates the symmetric key key of length keylen with the CMS_RecipientInfo structure ri, which must be of type CMS_RECIPINFO_KEK.
• CMS_RecipientInfo_decrypt() — attempts to decrypt the CMS_RecipientInfo structure ri inside the structure cms. A key must have been associated with the structure first, no shortcuts 🫶
• CMS_RecipientInfo_encrypt() — attempts to encrypt the CMS_RecipientInfo structure ri inside the structure cms. Again, a key must have been associated with the structure first, and the content encryption key must be available: for example by a previous call to CMS_RecipientInfo_decrypt().

---

🎀 NOTES 🎀

The main purpose of these functions, the whole reason they exist, is to let an application look up recipient keys using literally any appropriate technique, for the situations where the simpler method of CMS_decrypt() is just not appropriate. Sometimes the simple way isn't the move, and that's okay.

In typical usage, an application will retrieve all CMS_RecipientInfo structures using CMS_get0_RecipientInfos() and check the type of each one using CMS_RecipientInfo_type(). Depending on the type, the CMS_RecipientInfo structure can be ignored, or its key identifier data can be retrieved using an appropriate function. Then, if the corresponding secret or private key can be obtained by any appropriate means, it can be associated with the structure and CMS_RecipientInfo_decrypt() called. If that succeeds, CMS_decrypt() can be called with a NULL key to decrypt the enveloped content. A whole pipeline, and honestly? she ate.

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, then add a new recipient using a function such as CMS_add1_recipient_cert(), and finally encrypt the content encryption key using CMS_RecipientInfo_encrypt(). Three steps, no notes.

---

✨ RETURN VALUES ✨

• CMS_get0_RecipientInfos() returns all CMS_RecipientInfo structures, or NULL if an error occurs. 😭
• CMS_RecipientInfo_ktri_get0_signer_id(), CMS_RecipientInfo_set0_pkey(), CMS_RecipientInfo_kekri_get0_id(), CMS_RecipientInfo_set0_key() and CMS_RecipientInfo_decrypt() return 1 for success or 0 if an error occurs. CMS_RecipientInfo_encrypt() returns 1 for success or 0 if an error occurs. Yes, same numbers, we're consistent like that.
• CMS_RecipientInfo_ktri_cert_cmp() and CMS_RecipientInfo_kekri_cmp() return 0 for a successful comparison and non zero otherwise. (careful bestie, 0 means good here, not bad — flipped from the usual vibe check 💀)
• Any error can be obtained from ERR_get_error(3).

---

🌈 SEE ALSO 🌈

ERR_get_error(3), CMS_decrypt(3)

iykyk, go read those next.

---

👑 HISTORY 👑

CMS_RecipientInfo_kari_set0_pkey_and_peer and CMS_RecipientInfo_kari_set0_pkey were added in OpenSSL 3.0. New girls on the block, but they've been here a minute.

---

💜 COPYRIGHT 💜

Copyright 2008-2020 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 was OpenSSL 3.5.9, dated 2026-09-29, for CMS_GET0_RECIPIENTINFOS(3ossl) — go forth and decrypt responsibly, mwah 💖✨