CMS_ADD1_RECIPIENT_CERT(3) | Library Functions Manual | CMS_ADD1_RECIPIENT_CERT(3)

# NAME

`CMS_add1_recipient_cert`, `CMS_add0_recipient_key` — add recipients to a CMS EnvelopedData structure

# SYNOPSIS

library “libcrypto”
`#include <openssl/cms.h>`

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

CMS_RecipientInfo *
`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

These functions add a new RecipientInfo structure to the recipientInfos field of the EnvelopedData structure cms, which should have been obtained from an initial call to CMS_encrypt(3) with the flag `CMS_PARTIAL` set.

`CMS_add1_recipient_cert`() adds the recipient certificate as a KeyTransRecipientInfo structure.

`CMS_add0_recipient_key`() adds the symmetric key of length keylen using the wrapping algorithm nid, the identifier id of length idlen, and the optional values date, otherTypeId and otherType as a KEKRecipientInfo structure.

The main purpose of these functions is to provide finer control over a CMS EnvelopedData structure where the simpler CMS_encrypt(3) function defaults are not appropriate, 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.

By default, recipient certificates are identified using issuer name and serial number. If the flag `CMS_USE_KEYID` is set, the subject key identifier value is used instead. An error occurs if all recipient certificates do not have a subject key identifier extension.

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`. If nid is set to `NID_undef`, then an AES wrap algorithm will be used consistent with keylen.

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

# SEE ALSO

CMS_ContentInfo_new(3), CMS_encrypt(3), CMS_final(3), ERR_get_error(3)

# STANDARDS

RFC 5652: Cryptographic Message Syntax

- section 6.1: EnvelopedData Type
- section 6.2.1: KeyTransRecipientInfo Type
- section 6.2.3: KEKRecipientInfo Type

# HISTORY

`CMS_add1_recipient_cert`() and `CMS_add0_recipient_key`() first appeared in OpenSSL 0.9.8h and have been available since OpenBSD 6.7.

June 8, 2025 | Debian