CMS_ENCRYPT(3)

📦 version 4.4.0, in alpine 3.24, arch rolling

💅 CMS_ENCRYPT(3) 💅

okay bestie, welcome to the Library Functions Manual entry for CMS_encrypt — yes, the header says CMS_ENCRYPT(3), and we are folding that manual-name energy right in here. ✨

🌸 NAME 🌸

CMS_encrypt — create a CMS EnvelopedData structure. That's the whole assignment. 💖

✨ SYNOPSIS ✨

call it like this, bestie:

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

CMS_ContentInfo *
CMS_encrypt(STACK_OF(X509) *certificates, BIO *in,
    const EVP_CIPHER *cipher, unsigned int flags);

💖 DESCRIPTION 💖

CMS_encrypt() creates a CMS EnvelopedData structure, encrypting the content provided by in. It's giving “wrap it up and keep it safe” energy. 🎀

The recipient certificates are added as KeyTransRecipientInfo structures by calling CMS_add1_recipient_cert(3) internally. Only certificates carrying RSA, Diffie-Hellman or EC keys are supported by this function. The certificates argument can be set to NULL if the CMS_PARTIAL flag is set and recipients are added later using CMS_add1_recipient_cert(3) or CMS_add0_recipient_key(3). iykyk. 🦋

cipher is the symmetric cipher to use. It must support ASN.1 encoding of its parameters. EVP_des_ede3_cbc(3) (triple DES) is the algorithm of choice for S/MIME use because most clients support it. yes, triple DES is out here being the popular one — periodt. 💅

Many browsers implement a “sign and encrypt” option which is simply an S/MIME EnvelopedData containing an S/MIME signed message. This can be readily produced by storing the S/MIME signed message in a memory BIO and passing it to CMS_encrypt(). literally iconic. 🔥

The following flags can be passed in the flags parameter:

  • CMS_TEXT — MIME headers for type text/plain are prepended to the data. cute little header moment. 🎀
  • CMS_BINARY — Do not translate the supplied content into MIME canonical format even though that is required by the S/MIME specifications. This option should be used if the supplied data is in binary format. Otherwise, the translation will corrupt it. If CMS_BINARY is set, then CMS_TEXT is ignored. ⚠️ no cap, this one matters.
  • CMS_USE_KEYID — Use the subject key identifier value to identify recipient certificates. An error occurs if all recipient certificates do not have a subject key identifier extension. By default, issuer name and serial number are used instead. 🔑
  • CMS_STREAM — Return a partial CMS_ContentInfo structure suitable for streaming I/O: no data is read from the BIO in. Several functions including SMIME_write_CMS(3), i2d_CMS_bio_stream(3), or PEM_write_bio_CMS_stream(3) can be used to finalize the structure. Alternatively, finalization can be performed by obtaining the streaming ASN1 BIO directly using BIO_new_CMS(3). Outputting the content of the returned CMS_ContentInfo structure via a function that does not properly finalize it will give unpredictable results. 💀 bestie, finalize it properly or chaos.
  • CMS_PARTIAL — Return a partial CMS_ContentInfo structure to which additional recipients and attributes can be added before finalization. build-a-bear but make it crypto. 🧸
  • CMS_DETACHED — Omit the data being encrypted from the CMS_ContentInfo structure. This is rarely used in practice and is not supported by SMIME_write_CMS(3). rare and not supported — noted. 🙈

🌈 RETURN VALUES 🌈

CMS_encrypt() returns either a CMS_ContentInfo structure or NULL if an error occurred. The error can be obtained from ERR_get_error(3). so if it's NULL, go ask ERR_get_error(3) what happened. 🫶

👑 SEE ALSO 👑

go read these too, bestie:

⭐ STANDARDS ⭐

RFC 5652: Cryptographic Message Syntax (CMS)

  • section 6.1: EnvelopedData Type
  • section 6.2.1: KeyTransRecipientInfo Type

🦋 HISTORY 🦋

CMS_encrypt() first appeared in OpenSSL 0.9.8h and has been available since OpenBSD 6.7.

The CMS_STREAM flag first appeared in OpenSSL 1.0.0.

source/version: Debian · date: June 8, 2025 · CMS_ENCRYPT(3) — bye bestie, go encrypt something slay 💅🫶✨

📦 where this page comes from