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