CMS_ADD1_RECIPIENT_CERT(3ossl)

📦
version 15.1 · 3 versions
, in freebsd 15.1

💅 CMS_ADD1_RECIPIENT_CERT — like, the OpenSSL 3ossl era ✨

okay so bestie, this is the 3ossl girlies' guide to three whole functions that all live together in one page: CMS_add1_recipient, CMS_add1_recipient_cert, and CMS_add0_recipient_key. Their whole personality? Adding recipients to a CMS enveloped data structure. That's it, that's the vibe. 🎀

✨ SYNOPSIS ✨

like, first you gotta let it know you're coming:

#include <openssl/cms.h>

CMS_RecipientInfo *CMS_add1_recipient(CMS_ContentInfo *cms, X509 *recip,
                                      EVP_PKEY *originatorPrivKey,
                                      X509 *originator, unsigned int flags);

CMS_RecipientInfo *CMS_add1_recipient_cert(CMS_ContentInfo *cms,
                                           X509 *recip, unsigned int flags);

CMS_add0_recipient_key(CMS_ContentInfo *cms, int nid,
                       unsigned char *key, size_t keylen,
                       unsigned char *id, size_t idlen,
                       ASN1_GENERALIZEDTIME *date,
                       ASN1_OBJECT *otherTypeId,
                       ASN1_TYPE *otherType);

🌸 DESCRIPTION 🌸

So. Three functions, three little personalities. Let me introduce you 🫶

  • CMS_add1_recipient() — adds recipient recip, and also hands over the originator pkey originatorPrivKey plus the originator certificate originator to the CMS_ContentInfo. Real "and my plus-one" energy. 💅 Now, the originator-related fields? They only matter when the keyAgreement method of providing the shared key is the one in use — otherwise they're just, like, standing there. 🙈
  • CMS_add1_recipient_cert() — adds recipient recip to the CMS_ContentInfo enveloped data structure cms as a KeyTransRecipientInfo structure. Simple, iconic, no notes. ✨
  • CMS_add0_recipient_key() — adds symmetric key key of length keylen using wrapping algorithm nid, identifier id of length idlen, and the optional values date, otherTypeId and otherType to the CMS_ContentInfo enveloped data structure cms as a KEKRecipientInfo structure. Lowkey the most extra of the three and we stan. 👑
💖 okay but like — the CMS_ContentInfo structure should be obtained from an initial call to CMS_encrypt() with the flag CMS_PARTIAL set. Don't skip that step, bestie, it's giving prerequisites.

🦋 NOTES 🦋

The main purpose of these functions is finer control over a CMS enveloped data structure — you know, for when the simpler CMS_encrypt() function defaults are just not appropriate. Very "I'll take it from here, thanks." 💅 For example, if one or more KEKRecipientInfo structures need to be added. New attributes can also be added using the returned CMS_RecipientInfo structure and the CMS attribute utility functions. Obsessed with the flexibility, honestly.

OpenSSL will by default identify recipient certificates using issuer name and serial number. But if CMS_USE_KEYID is set, it'll use the subject key identifier value instead. ✨

⚠️ An error occurs if all recipient certificates do not have a subject key identifier extension. Not a vibe. Check your certs, fr fr.

Currently only AES based key wrapping algorithms are supported for nid, specifically: NID_id_aes128_wrap, NID_id_aes192_wrap and NID_id_aes256_wrap. And if nid is set to NID_undef, then an AES wrap algorithm will be used consistent with keylen. Cute little auto-pick situation. 🎀

🔥 RETURN VALUES 🔥

CMS_add1_recipient_cert() and CMS_add0_recipient_key() return an internal pointer to the CMS_RecipientInfo structure just added — or NULL if an error occurs. So like, always check. NULL is the villain of this story. 😭

💀 SEE ALSO 💀

ERR_get_error(3), CMS_decrypt(3), CMS_final(3),

🌈 HISTORY 🌈

CMS_add1_recipient_cert and CMS_add0_recipient_key were added in OpenSSL 3.0. Babygirl era. 🌸

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

okay that's the whole page, bestie, you ate that 💅✨ — this was version 3.5.6, dated 2026-04-07, and it lives under the name CMS_ADD1_RECIPIENT_CERT(3ossl). mwah, go forth and add some recipients 🎀🦋💖

📦 where this page comes from