1238384Sjkim=pod 2238384Sjkim 3238384Sjkim=head1 NAME 4238384Sjkim 5238384Sjkim CMS_encrypt - create a CMS envelopedData structure 6238384Sjkim 7238384Sjkim=head1 SYNOPSIS 8238384Sjkim 9238384Sjkim #include <openssl/cms.h> 10238384Sjkim 11238384Sjkim CMS_ContentInfo *CMS_encrypt(STACK_OF(X509) *certs, BIO *in, const EVP_CIPHER *cipher, unsigned int flags); 12238384Sjkim 13238384Sjkim=head1 DESCRIPTION 14238384Sjkim 15238384SjkimCMS_encrypt() creates and returns a CMS EnvelopedData structure. B<certs> 16238384Sjkimis a list of recipient certificates. B<in> is the content to be encrypted. 17238384SjkimB<cipher> is the symmetric cipher to use. B<flags> is an optional set of flags. 18238384Sjkim 19238384Sjkim=head1 NOTES 20238384Sjkim 21337982SjkimOnly certificates carrying RSA, Diffie-Hellman or EC keys are supported by this 22337982Sjkimfunction. 23238384Sjkim 24238384SjkimEVP_des_ede3_cbc() (triple DES) is the algorithm of choice for S/MIME use 25238384Sjkimbecause most clients will support it. 26238384Sjkim 27238384SjkimThe algorithm passed in the B<cipher> parameter must support ASN1 encoding of 28238384Sjkimits parameters. 29238384Sjkim 30238384SjkimMany browsers implement a "sign and encrypt" option which is simply an S/MIME 31238384SjkimenvelopedData containing an S/MIME signed message. This can be readily produced 32238384Sjkimby storing the S/MIME signed message in a memory BIO and passing it to 33238384SjkimCMS_encrypt(). 34238384Sjkim 35238384SjkimThe following flags can be passed in the B<flags> parameter. 36238384Sjkim 37238384SjkimIf the B<CMS_TEXT> flag is set MIME headers for type B<text/plain> are 38238384Sjkimprepended to the data. 39238384Sjkim 40238384SjkimNormally the supplied content is translated into MIME canonical format (as 41238384Sjkimrequired by the S/MIME specifications) if B<CMS_BINARY> is set no translation 42238384Sjkimoccurs. This option should be used if the supplied data is in binary format 43238384Sjkimotherwise the translation will corrupt it. If B<CMS_BINARY> is set then 44238384SjkimB<CMS_TEXT> is ignored. 45238384Sjkim 46238384SjkimOpenSSL will by default identify recipient certificates using issuer name 47238384Sjkimand serial number. If B<CMS_USE_KEYID> is set it will use the subject key 48238384Sjkimidentifier value instead. An error occurs if all recipient certificates do not 49238384Sjkimhave a subject key identifier extension. 50238384Sjkim 51238384SjkimIf the B<CMS_STREAM> flag is set a partial B<CMS_ContentInfo> structure is 52238384Sjkimreturned suitable for streaming I/O: no data is read from the BIO B<in>. 53238384Sjkim 54238384SjkimIf the B<CMS_PARTIAL> flag is set a partial B<CMS_ContentInfo> structure is 55238384Sjkimreturned to which additional recipients and attributes can be added before 56238384Sjkimfinalization. 57238384Sjkim 58238384SjkimThe data being encrypted is included in the CMS_ContentInfo structure, unless 59238384SjkimB<CMS_DETACHED> is set in which case it is omitted. This is rarely used in 60238384Sjkimpractice and is not supported by SMIME_write_CMS(). 61238384Sjkim 62238384Sjkim=head1 NOTES 63238384Sjkim 64238384SjkimIf the flag B<CMS_STREAM> is set the returned B<CMS_ContentInfo> structure is 65238384SjkimB<not> complete and outputting its contents via a function that does not 66238384Sjkimproperly finalize the B<CMS_ContentInfo> structure will give unpredictable 67238384Sjkimresults. 68238384Sjkim 69238384SjkimSeveral functions including SMIME_write_CMS(), i2d_CMS_bio_stream(), 70238384SjkimPEM_write_bio_CMS_stream() finalize the structure. Alternatively finalization 71238384Sjkimcan be performed by obtaining the streaming ASN1 B<BIO> directly using 72238384SjkimBIO_new_CMS(). 73238384Sjkim 74238384SjkimThe recipients specified in B<certs> use a CMS KeyTransRecipientInfo info 75238384Sjkimstructure. KEKRecipientInfo is also supported using the flag B<CMS_PARTIAL> 76238384Sjkimand CMS_add0_recipient_key(). 77238384Sjkim 78238384SjkimThe parameter B<certs> may be NULL if B<CMS_PARTIAL> is set and recipients 79238384Sjkimadded later using CMS_add1_recipient_cert() or CMS_add0_recipient_key(). 80238384Sjkim 81238384Sjkim=head1 RETURN VALUES 82238384Sjkim 83238384SjkimCMS_encrypt() returns either a CMS_ContentInfo structure or NULL if an error 84238384Sjkimoccurred. The error can be obtained from ERR_get_error(3). 85238384Sjkim 86238384Sjkim=head1 SEE ALSO 87238384Sjkim 88238384SjkimL<ERR_get_error(3)|ERR_get_error(3)>, L<CMS_decrypt(3)|CMS_decrypt(3)> 89238384Sjkim 90238384Sjkim=head1 HISTORY 91238384Sjkim 92238384SjkimCMS_decrypt() was added to OpenSSL 0.9.8 93238384SjkimThe B<CMS_STREAM> flag was first supported in OpenSSL 1.0.0. 94238384Sjkim 95238384Sjkim=cut 96