CMS_GET0_RECIPIENTINFOS(3SSL)

📦

version 4.0.3 · 14 versions

🎀 NAME 🎀

okay bestie, welcome to the CMS_GET0_RECIPIENTINFOS(3SSL) page, aka the OpenSSL girlies' guide to CMS envelopedData RecipientInfo routines 💌

This is the whole squad, no one left behind:

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_kari_get0_ctx
CMS_RecipientInfo_kekri_id_cmp
CMS_RecipientInfo_set0_key
CMS_RecipientInfo_kemri_cert_cmp
CMS_RecipientInfo_kemri_set0_pkey
CMS_RecipientInfo_kemri_get0_ctx
CMS_RecipientInfo_kemri_get0_kdf_alg
CMS_RecipientInfo_kemri_set_ukm
CMS_RecipientInfo_decrypt
CMS_RecipientInfo_encrypt

✨ 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);
EVP_CIPHER_CTX *CMS_RecipientInfo_kari_get0_ctx(CMS_RecipientInfo *ri);
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_kemri_cert_cmp(CMS_RecipientInfo *ri, X509 *cert);
int CMS_RecipientInfo_kemri_set0_pkey(CMS_RecipientInfo *ri, EVP_PKEY *pk);
EVP_CIPHER_CTX *CMS_RecipientInfo_kemri_get0_ctx(CMS_RecipientInfo *ri);
X509_ALGOR *CMS_RecipientInfo_kemri_get0_kdf_alg(CMS_RecipientInfo *ri);
int CMS_RecipientInfo_kemri_set_ukm(CMS_RecipientInfo *ri,
                                    const unsigned char *ukm,
                                    int ukmLength);

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

💖 DESCRIPTION 💖

so basically every single one of these is about poking at one recipient inside an EnvelopedData situation, and here's the tea on each 🍵

CMS_get0_RecipientInfos() — hands you back all the CMS_RecipientInfo structures that are chillin' inside a CMS EnvelopedData structure. the whole group chat, fr fr.
CMS_RecipientInfo_type() — tells you what kind of CMS_RecipientInfo structure ri is. and right now it can return CMS_RECIPINFO_TRANS, CMS_RECIPINFO_AGREE, CMS_RECIPINFO_KEK, CMS_RECIPINFO_PASS, CMS_RECIPINFO_KEM, or CMS_RECIPINFO_OTHER. pick your fighter 💅
CMS_RecipientInfo_ktri_get0_signer_id() — grabs the certificate recipient identifier that belongs to a specific CMS_RecipientInfo structure ri, and ri has got to 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. choose your own adventure.
CMS_RecipientInfo_ktri_cert_cmp() — compares the certificate cert against the CMS_RecipientInfo structure ri, which must be of type CMS_RECIPINFO_TRANS. it returns zero if the comparison slayed (success 🎉) and non zero if not.
CMS_RecipientInfo_set0_pkey() — associates the private key pkey with the CMS_RecipientInfo structure ri, and ri must be of type CMS_RECIPINFO_TRANS. it's giving matchmaker energy 🫶
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. plus one, literally.
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_kari_get0_ctx() — returns the EVP_CIPHER_CTX for the key encryption key, which lets the caller specify the key wrap cipher. the CMS_RecipientInfo structure ri must be of type CMS_RECIPINFO_AGREE. yes bestie you get to pick the fit 🔥
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 the value of a field. where a field is optional and absent, NULL will be written to the corresponding parameter. the keyEncryptionAlgorithm field gets written to palg, the keyIdentifier field gets written to pid, the date field (if present) gets written to pdate, and if the other field is present the components keyAttrId and keyAttr get written to the parameters potherid and pothertype. whew, that's a lot of slots but we're filling them all correctly 💅
CMS_RecipientInfo_kekri_id_cmp() — compares the ID in the id and idlen parameters against the keyIdentifier CMS_RecipientInfo structure ri, which must be of type CMS_RECIPINFO_KEK. it returns zero if the comparison succeeded and non zero if not.
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_kemri_cert_cmp() — compares the certificate cert against the CMS_RecipientInfo structure ri, which must be of type CMS_RECIPINFO_KEM. returns zero if the comparison worked out and non zero if not. we love a successful compare 💖
CMS_RecipientInfo_kemri_set0_pkey() — associates the private key pkey with the CMS_RecipientInfo structure ri, which must be of type CMS_RECIPINFO_KEM.
CMS_RecipientInfo_kemri_get0_ctx() — returns the EVP_CIPHER_CTX for the key encryption key, so the caller can specify the key wrap cipher. the CMS_RecipientInfo structure ri must be of type CMS_RECIPINFO_KEM.
CMS_RecipientInfo_kemri_get0_kdf_alg() — returns the X509_ALGOR for the RecipientInfo's KDF, letting the caller specify the KDF algorithm. the CMS_RecipientInfo structure ri must be of type CMS_RECIPINFO_KEM. and bestie, if the caller doesn't specify a KDF algorithm, HKDF-SHA256 will be used. it's the default for a reason ✨
CMS_RecipientInfo_kemri_set_ukm() — sets the RecipientInfo's optional user keying material (UKM). the UKM gets encoded, along with other information, into the OSSL_KDF_PARAM_INFO parameter of the RecipientInfo's KDF. the CMS_RecipientInfo structure ri must be of type CMS_RECIPINFO_KEM.
CMS_RecipientInfo_decrypt() — attempts to decrypt the CMS_RecipientInfo structure ri in 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 in the structure cms. 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(). both ingredients or it's not happening 🧚

🌸 NOTES 🌸

the main purpose of all these functions is to let an application look up recipient keys using any appropriate technique, for those times when the simpler method of CMS_decrypt() just isn't appropriate. sometimes the simple route isn't the vibe, yk?

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 the type, the CMS_RecipientInfo structure can either be ignored or have its key identifier data 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 popped off, CMS_decrypt() can be called with a NULL key to decrypt the enveloped content. iconic workflow honestly 👑

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 encryption key available, then it'll add a new recipient using a function such as CMS_add1_recipient_cert(), and finally encrypt the content encryption key using CMS_RecipientInfo_encrypt(). add a friend to the gc, but make it cryptographic 💌

⭐ 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(), CMS_RecipientInfo_kemri_set0_pkey(), CMS_RecipientInfo_kemri_set_ukm(), CMS_RecipientInfo_decrypt() and CMS_RecipientInfo_encrypt() — return 1 for success or 0 if an error occurs.
CMS_RecipientInfo_ktri_cert_cmp(), CMS_RecipientInfo_kemri_cert_cmp() and CMS_RecipientInfo_kekri_cmp() — return 0 for a successful comparison and non zero otherwise. (heads up, zero is the good number here, yes it's confusing, we deal 💀)
CMS_RecipientInfo_kemri_get0_ctx() and CMS_RecipientInfo_kari_get0_ctx — return the RecipientInfo's EVP_CIPHER_CTX or NULL if an error occurred.
CMS_RecipientInfo_kemri_get0_kdf_alg() — returns the RecipientInfo's KDF's X509_ALGOR or NULL if an error occurred.

any error can be obtained from ERR_get_error(3). go check the receipts 👀

👑 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.
CMS_RecipientInfo_kemri_cert_cmp, CMS_RecipientInfo_kemri_set0_pkey, CMS_RecipientInfo_kemri_get0_ctx, CMS_RecipientInfo_kemri_get0_kdf_alg and CMS_RecipientInfo_kemri_set_ukm were added in OpenSSL 3.6.

glow-ups only ✨

💜 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>.

okay that's the whole page bestie, tysm for reading!! this was OpenSSL 4.0.3, dated 2026-09-29, and you can find it filed under CMS_GET0_RECIPIENTINFOS(3SSL) 💖 mwah, go encrypt something cute 🎀🫶

📦 where this page comes from

ubuntu stonking: libssl-doc 4.0.3-1ubuntu1 · Apache-2.0
💖 girlified by deepseek-ai/DeepSeek-V4.1-Flash on 2026-11-03: a language model's rewrite of the original, under its terms