CMS_ADD1_RECIPIENT_CERT(3SSL)

📦
version 4.0.3 · 14 versions
, in ubuntu stonking

✨ CMS_ADD1_RECIPIENT_CERT ✨

okay bestie, welcome to the OpenSSL section 3 ssl glow-up 💅 this one's all about slipping extra recipients into a CMS enveloped data structure, and honestly? it's giving main character 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);

(yes the third one got its return type cropped in the original, no we are not fixing it, we reproduce it exactly, periodt 💀)

🎀 DESCRIPTION 🎀

so like, three functions, three vibes:

  • CMS_add1_recipient() — adds recipient recip and hands over the originator pkey originatorPrivKey plus the originator certificate originator to CMS_ContentInfo. 🌟 the originator-related fields are only relevant when the keyAgreement method of providing of the shared key is in use — so if you're doing it any other way, those fields are just sitting there, decorative, iykyk 🙈
  • CMS_add1_recipient_cert() — adds recipient recip to the CMS_ContentInfo enveloped data structure cms, as a KeyTransRecipientInfo or KEMRecipientInfo structure, or as a KeyAgreeRecipientInfo structure with an ephemeral key. three possible fits, one function, she's versatile 💅
  • 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. 👑

and the big rule, bestie: the CMS_ContentInfo structure should be obtained from an initial call to CMS_encrypt() with the flag CMS_PARTIAL set. no CMS_PARTIAL, no party 🎉 no cap.

🦋 NOTES 🦋

the main purpose of this function is to provide finer control over a CMS enveloped data structure — you know, for the situations where the simpler CMS_encrypt() function defaults just aren't the moment. 💅 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.

OpenSSL will by default identify recipient certificates using issuer name and serial number. but if CMS_USE_KEYID is set, it will use the subject key identifier value instead. ⚡ and heads up: an error occurs if all recipient certificates do not have a subject key identifier extension. so check your certs before you come for her, fr fr 😭

currently, only AES based key wrapping algorithms are supported for nid, specifically:

  • NID_id_aes128_wrap
  • NID_id_aes192_wrap
  • NID_id_aes256_wrap

and if nid is set to NID_undef then an AES wrap algorithm will be used consistent with keylen. auto-select, iconic behavior 🌈

👑 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. 💀 if you get NULL, that's your sign to go check things.

🔥 SEE ALSO 🔥

🌈 HISTORY 🌈

CMS_add1_recipient_cert and CMS_add0_recipient_key were added in OpenSSL 3.0. glow-up era ✨

Copyright 2008-2025 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 OpenSSL 4.0.3, dated 2026-09-29, living in the CMS_ADD1_RECIPIENT_CERT(3SSL) manual. slay, go add your recipients 💅💖

📦 where this page comes from