CMS_ADD1_RECIPIENT_CERT(3ossl)

📦
version 3.5.9 · 8 versions
, in fedora 43, fedora 44

💖 CMS_ADD1_RECIPIENT_CERT 💖

okay bestie, this is the CMS_ADD1_RECIPIENT_CERT(3ossl) page from the OpenSSL fam, and it's literally all about hand-adding recipients to your CMS enveloped data structure. no cap, it's giving "I want finer control than the default" energy. let's get into it 🫶

✨ NAME ✨

CMS_add1_recipient, CMS_add1_recipient_cert, CMS_add0_recipient_key — add recipients to a CMS enveloped data structure 🎀

🌸 SYNOPSIS 🌸

#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 CMS_add1_recipient() adds the recipient recip and also hands over the originator pkey originatorPrivKey plus the originator certificate originator to CMS_ContentInfo. and here's the tea ☕ — those originator-related fields only matter when you're using the keyAgreement method of providing the shared key. otherwise? they're just vibing there.

CMS_add1_recipient_cert() adds the recipient recip to the CMS_ContentInfo enveloped data structure cms as a KeyTransRecipientInfo structure. iconic, straightforward, we love her ✨

CMS_add0_recipient_key() adds the 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. queen behavior honestly 👑

heads up bestie: you should get that CMS_ContentInfo structure from an initial call to CMS_encrypt() with the flag CMS_PARTIAL set. don't skip that step, fr fr.

🦋 NOTES 🦋

the main character purpose of these functions? giving you finer control over a CMS enveloped data structure when the simpler CMS_encrypt() defaults just aren't the vibe. for example, if one or more KEKRecipientInfo structures need to be added. and you can also add new attributes using the returned CMS_RecipientInfo structure plus the CMS attribute utility functions. multi-purpose king 💜

by default, OpenSSL identifies recipient certificates using issuer name and serial number. but if CMS_USE_KEYID is set, it'll use the subject key identifier value instead. and listen — an error occurs if all recipient certificates do not have a subject key identifier extension. so like, check that first bestie 😭

and now the important bit ngl: currently only AES based key wrapping algorithms are supported for nid, specifically:

  • NID_id_aes128_wrap
  • NID_id_aes192_wrap
  • NID_id_aes256_wrap

if nid is set to NID_undef, then an AES wrap algorithm will be used consistent with keylen. slay, adaptive 💅

⭐ RETURN VALUES ⭐

CMS_add1_recipient_cert() and CMS_add0_recipient_key() return an internal pointer to the CMS_RecipientInfo structure that was just added — or NULL if an error occurs. that's it, that's the deal 🌈

🎀 SEE ALSO 🎀

💀 HISTORY 💀

CMS_add1_recipient_cert and CMS_add0_recipient_key were added in OpenSSL 3.0. so they're like, not ancient, but they've been around the block 🧚

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 version 3.5.9, dated 2026-09-29, and it's the CMS_ADD1_RECIPIENT_CERT(3ossl) manual from the OpenSSL girlies. go forth and add those recipients, you've got this ✨🫶🌸

📦 where this page comes from