CMS_GET0_RECIPIENTINFOS(3ossl)

📦

version 15.1 · 3 versions

15.1 · freebsd 15.1 (latest)
14.5 · freebsd 14.5
nixpkgs unstable

✨ CMS_GET0_RECIPIENTINFOS(3ossl) ✨

okay so this is the OpenSSL manpage for the CMS envelopedData RecipientInfo routines — it's filed under CMS_GET0_RECIPIENTINFOS(3ossl) in case you were wondering, and bestie, it's literally all about how you find, poke at, and unlock the recipient info blobs inside a CMS EnvelopedData structure. no cap, it's giving "backstage pass to the encryption key" energy 💅

🌸 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 — CMS envelopedData RecipientInfo routines 🎀

🦋 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 here's the whole cast, one by one 👑

CMS_get0_RecipientInfos() — hands you all the CMS_RecipientInfo structures chillin' inside a CMS EnvelopedData structure. the whole squad. 🫶
CMS_RecipientInfo_type() — tells you what kind of CMS_RecipientInfo structure ri actually is. right now it'll return one of CMS_RECIPINFO_TRANS, CMS_RECIPINFO_AGREE, CMS_RECIPINFO_KEK, CMS_RECIPINFO_PASS, or CMS_RECIPINFO_OTHER. vibe check, basically. ✨
CMS_RecipientInfo_ktri_get0_signer_id() — pulls out the certificate recipient identifier that goes with a specific CMS_RecipientInfo structure ri, which must be of type CMS_RECIPINFO_TRANS. either the key identifier gets set in keyid, or both the issuer name and serial number get set in issuer and sno. it's one or the other, not both, iykyk.
CMS_RecipientInfo_ktri_cert_cmp() — compares the certificate cert against the CMS_RecipientInfo structure ri, which must be of type CMS_RECIPINFO_TRANS. returns zero if the comparison is successful and non zero if not. yes bestie, zero = slay here, non zero = not it. 🙈
CMS_RecipientInfo_set0_pkey() — associates the private key pkey with the CMS_RecipientInfo structure ri, which must be of type CMS_RECIPINFO_TRANS. matching them up like a group chat admin 💅
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, we love to see it.
CMS_RecipientInfo_kari_set0_pkey() — associates just the private key pkey with the CMS_RecipientInfo structure ri, which must be of type CMS_RECIPINFO_AGREE. the solo version. still iconic.
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 isn't interested in that field's value — no pressure to take them all. where a field is optional and absent, NULL gets 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 keyAttrId and keyAttr components get written 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 deal as before: zero is the good 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 key, no decrypt, periodt.
CMS_RecipientInfo_encrypt() — attempts to encrypt the CMS_RecipientInfo structure ri inside the structure cms. a key must have been associated with the structure first, and the content encryption key must be available — like, for example, from a previous call to CMS_RecipientInfo_decrypt(). both conditions, bestie, it's not optional. 😭

🧚 NOTES 🧚

the main purpose of these functions is literally to let an application look up recipient keys using whatever technique fits, for when the simpler method of CMS_decrypt() just isn't appropriate. it's the "I'll handle this myself" route. 🔥

in typical usage, an application will retrieve all the CMS_RecipientInfo structures using CMS_get0_RecipientInfos() and then check the type of each one using CMS_RecipientInfo_type(). depending on that type, the CMS_RecipientInfo structure can either 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() can be called. if that works out, CMS_decrypt() can be called with a NULL key to decrypt the enveloped content. 🌈

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(). it's a whole three-step glow-up routine ✨

⭐ RETURN VALUES ⭐

CMS_get0_RecipientInfos() — returns all the 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() also returns 1 for success or 0 if an error occurs. (yes, it says that twice, and we're keeping it, that's the original's whole thing 🫶)
CMS_RecipientInfo_ktri_cert_cmp() and CMS_RecipientInfo_kekri_cmp() — return 0 for a successful comparison and non zero otherwise. remember: zero is the win here 👑
any error can be obtained from ERR_get_error(3). go check there if something's acting up.

🌈 SEE ALSO 🌈

ERR_get_error(3), CMS_decrypt(3)

🎀 HISTORY 🎀

CMS_RecipientInfo_kari_set0_pkey_and_peer and CMS_RecipientInfo_kari_set0_pkey were added in OpenSSL 3.0. newer arrivals, but already main characters 💅

👑 COPYRIGHT 👑

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 CMS_GET0_RECIPIENTINFOS(3ossl) from OpenSSL version 3.5.6, dated 2026-04-07 — go decrypt something iconic 💖✨🍓

📦 where this page comes from

freebsd 15.1: base 15.1
💖 girlified by deepseek-ai/DeepSeek-V4.1-Flash-1017 on 2026-11-04: a language model's rewrite of the original, under its terms