CMS_GET0_RECIPIENTINFOS(3ossl)

🌸 NAME 🌸

okay so bestie, welcome to the 3ossl girlies' guide to the CMS envelopedData RecipientInfo routines 💅✨ This page covers, in order:

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

…and together they are the CMS envelopedData RecipientInfo routines. iconic lineup fr fr 🫶

✨ 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);

like, copy-paste it, it's right there, no cap 💀

🦋 DESCRIPTION 🦋

CMS_get0_RecipientInfos() hands you all the CMS_RecipientInfo structures chillin' inside a CMS EnvelopedData structure. the whole squad, in one stack. 🎀

CMS_RecipientInfo_type() tells you what kind of CMS_RecipientInfo structure ri is. right now it will return one of these besties: CMS_RECIPINFO_TRANS, CMS_RECIPINFO_AGREE, CMS_RECIPINFO_KEK, CMS_RECIPINFO_PASS, or CMS_RECIPINFO_OTHER. vibe check complete ✅

CMS_RecipientInfo_ktri_get0_signer_id() retrieves the certificate recipient identifier associated with a specific CMS_RecipientInfo structure ri — and ri must be of type CMS_RECIPINFO_TRANS, no exceptions. Either the keyidentifier gets set in keyid, or both the issuer name and serial number get set in issuer and sno. pick your fighter 💫

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 slays (successful) and non zero if not 🙈

CMS_RecipientInfo_set0_pkey() associates the private key pkey with the CMS_RecipientInfo structure ri, which must be of type CMS_RECIPINFO_TRANS. match made in heaven tbh 💖

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. it's giving plus-one energy 👑

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. solo era 🦋

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 is not interested in the value of a field. Where a field is optional and absent, NULL will be written to the corresponding parameter. Here's the map, bestie 🗺️:

the keyEncryptionAlgorithm field is written to palg
the keyIdentifier field is written to pid
the date field, if present, is written to pdate
if the other field is present, the components keyAttrId and keyAttr are written to the parameters potherid and pothertype

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. returns zero if the comparison is successful and non zero if not. simple as 💅

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 CMS_RecipientInfo structure ri in structure cms. A key must have been associated with the structure first — no key, no decrypt, them's the rules 🚨

CMS_RecipientInfo_encrypt() attempts to encrypt CMS_RecipientInfo structure ri in 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 prerequisites, or it's not happening 😭

🧚 NOTES 🧚

The main purpose of these functions is to enable an application to look up recipient keys using any appropriate technique, for when the simpler method of CMS_decrypt() is just not the move. sometimes you gotta do it yourself, iykyk ✨

In typical usage, an application will retrieve all CMS_RecipientInfo structures using CMS_get0_RecipientInfos() and check 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. Then, 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 that succeeds, CMS_decrypt() can be called with a NULL key to decrypt the enveloped content. whole little pipeline, lowkey elegant 🎀

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().

look at that glow-up sequence 🌈

👑 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. ✅

CMS_RecipientInfo_ktri_cert_cmp() and CMS_RecipientInfo_kekri_cmp() return 0 for a successful comparison and non zero otherwise. 🫶

Any error can be obtained from ERR_get_error(3) — that's your receipts, bestie 🧾

💜 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. glow-up timeline fr fr ✨

🍓 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 one's version 3.5.0, dated 2026-09-25 — CMS_GET0_RECIPIENTINFOS(3ossl), signing off 💅💖

📦 where this page comes from

opensuse-leap 16.0: openssl-3-doc 3.5.0-160000.11.1 · Apache-2.0
💖 girlified by deepseek-ai/DeepSeek-V4.1-Flash-1017 on 2026-11-04: a language model's rewrite of the original, under its terms