1*4724848cSchristos=pod 2*4724848cSchristos 3*4724848cSchristos=head1 NAME 4*4724848cSchristos 5*4724848cSchristosCMS_encrypt - create a CMS envelopedData structure 6*4724848cSchristos 7*4724848cSchristos=head1 SYNOPSIS 8*4724848cSchristos 9*4724848cSchristos #include <openssl/cms.h> 10*4724848cSchristos 11*4724848cSchristos CMS_ContentInfo *CMS_encrypt(STACK_OF(X509) *certs, BIO *in, 12*4724848cSchristos const EVP_CIPHER *cipher, unsigned int flags); 13*4724848cSchristos 14*4724848cSchristos=head1 DESCRIPTION 15*4724848cSchristos 16*4724848cSchristosCMS_encrypt() creates and returns a CMS EnvelopedData structure. B<certs> 17*4724848cSchristosis a list of recipient certificates. B<in> is the content to be encrypted. 18*4724848cSchristosB<cipher> is the symmetric cipher to use. B<flags> is an optional set of flags. 19*4724848cSchristos 20*4724848cSchristos=head1 NOTES 21*4724848cSchristos 22*4724848cSchristosOnly certificates carrying RSA, Diffie-Hellman or EC keys are supported by this 23*4724848cSchristosfunction. 24*4724848cSchristos 25*4724848cSchristosEVP_des_ede3_cbc() (triple DES) is the algorithm of choice for S/MIME use 26*4724848cSchristosbecause most clients will support it. 27*4724848cSchristos 28*4724848cSchristosThe algorithm passed in the B<cipher> parameter must support ASN1 encoding of 29*4724848cSchristosits parameters. 30*4724848cSchristos 31*4724848cSchristosMany browsers implement a "sign and encrypt" option which is simply an S/MIME 32*4724848cSchristosenvelopedData containing an S/MIME signed message. This can be readily produced 33*4724848cSchristosby storing the S/MIME signed message in a memory BIO and passing it to 34*4724848cSchristosCMS_encrypt(). 35*4724848cSchristos 36*4724848cSchristosThe following flags can be passed in the B<flags> parameter. 37*4724848cSchristos 38*4724848cSchristosIf the B<CMS_TEXT> flag is set MIME headers for type B<text/plain> are 39*4724848cSchristosprepended to the data. 40*4724848cSchristos 41*4724848cSchristosNormally the supplied content is translated into MIME canonical format (as 42*4724848cSchristosrequired by the S/MIME specifications) if B<CMS_BINARY> is set no translation 43*4724848cSchristosoccurs. This option should be used if the supplied data is in binary format 44*4724848cSchristosotherwise the translation will corrupt it. If B<CMS_BINARY> is set then 45*4724848cSchristosB<CMS_TEXT> is ignored. 46*4724848cSchristos 47*4724848cSchristosOpenSSL will by default identify recipient certificates using issuer name 48*4724848cSchristosand serial number. If B<CMS_USE_KEYID> is set it will use the subject key 49*4724848cSchristosidentifier value instead. An error occurs if all recipient certificates do not 50*4724848cSchristoshave a subject key identifier extension. 51*4724848cSchristos 52*4724848cSchristosIf the B<CMS_STREAM> flag is set a partial B<CMS_ContentInfo> structure is 53*4724848cSchristosreturned suitable for streaming I/O: no data is read from the BIO B<in>. 54*4724848cSchristos 55*4724848cSchristosIf the B<CMS_PARTIAL> flag is set a partial B<CMS_ContentInfo> structure is 56*4724848cSchristosreturned to which additional recipients and attributes can be added before 57*4724848cSchristosfinalization. 58*4724848cSchristos 59*4724848cSchristosThe data being encrypted is included in the CMS_ContentInfo structure, unless 60*4724848cSchristosB<CMS_DETACHED> is set in which case it is omitted. This is rarely used in 61*4724848cSchristospractice and is not supported by SMIME_write_CMS(). 62*4724848cSchristos 63*4724848cSchristos=head1 NOTES 64*4724848cSchristos 65*4724848cSchristosIf the flag B<CMS_STREAM> is set the returned B<CMS_ContentInfo> structure is 66*4724848cSchristosB<not> complete and outputting its contents via a function that does not 67*4724848cSchristosproperly finalize the B<CMS_ContentInfo> structure will give unpredictable 68*4724848cSchristosresults. 69*4724848cSchristos 70*4724848cSchristosSeveral functions including SMIME_write_CMS(), i2d_CMS_bio_stream(), 71*4724848cSchristosPEM_write_bio_CMS_stream() finalize the structure. Alternatively finalization 72*4724848cSchristoscan be performed by obtaining the streaming ASN1 B<BIO> directly using 73*4724848cSchristosBIO_new_CMS(). 74*4724848cSchristos 75*4724848cSchristosThe recipients specified in B<certs> use a CMS KeyTransRecipientInfo info 76*4724848cSchristosstructure. KEKRecipientInfo is also supported using the flag B<CMS_PARTIAL> 77*4724848cSchristosand CMS_add0_recipient_key(). 78*4724848cSchristos 79*4724848cSchristosThe parameter B<certs> may be NULL if B<CMS_PARTIAL> is set and recipients 80*4724848cSchristosadded later using CMS_add1_recipient_cert() or CMS_add0_recipient_key(). 81*4724848cSchristos 82*4724848cSchristos=head1 RETURN VALUES 83*4724848cSchristos 84*4724848cSchristosCMS_encrypt() returns either a CMS_ContentInfo structure or NULL if an error 85*4724848cSchristosoccurred. The error can be obtained from ERR_get_error(3). 86*4724848cSchristos 87*4724848cSchristos=head1 SEE ALSO 88*4724848cSchristos 89*4724848cSchristosL<ERR_get_error(3)>, L<CMS_decrypt(3)> 90*4724848cSchristos 91*4724848cSchristos=head1 HISTORY 92*4724848cSchristos 93*4724848cSchristosThe B<CMS_STREAM> flag was first supported in OpenSSL 1.0.0. 94*4724848cSchristos 95*4724848cSchristos=head1 COPYRIGHT 96*4724848cSchristos 97*4724848cSchristosCopyright 2008-2018 The OpenSSL Project Authors. All Rights Reserved. 98*4724848cSchristos 99*4724848cSchristosLicensed under the OpenSSL license (the "License"). You may not use 100*4724848cSchristosthis file except in compliance with the License. You can obtain a copy 101*4724848cSchristosin the file LICENSE in the source distribution or at 102*4724848cSchristosL<https://www.openssl.org/source/license.html>. 103*4724848cSchristos 104*4724848cSchristos=cut 105