CMS_ENCRYPT(3) | Library Functions Manual | CMS_ENCRYPT(3)

# NAME

`CMS_encrypt` — create a CMS EnvelopedData structure

# SYNOPSIS

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.

The recipient certificates are added as KeyTransRecipientInfo structures by calling the function 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).

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.

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`().

The following flags can be passed in the flags parameter:

`CMS_TEXT`
  MIME headers for type text/plain are prepended to the data.
`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.
`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.
`CMS_PARTIAL`
  Return a partial CMS_ContentInfo structure to which additional recipients and attributes can be added before finalization.
`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).

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

# SEE ALSO

CMS_add0_cert(3), CMS_add1_recipient_cert(3), CMS_ContentInfo_new(3), CMS_decrypt(3)

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

June 8, 2025 | Debian