1*4724848cSchristos=pod 2*4724848cSchristos 3*4724848cSchristos=head1 NAME 4*4724848cSchristos 5*4724848cSchristosPKCS7_encrypt - create a PKCS#7 envelopedData structure 6*4724848cSchristos 7*4724848cSchristos=head1 SYNOPSIS 8*4724848cSchristos 9*4724848cSchristos #include <openssl/pkcs7.h> 10*4724848cSchristos 11*4724848cSchristos PKCS7 *PKCS7_encrypt(STACK_OF(X509) *certs, BIO *in, const EVP_CIPHER *cipher, 12*4724848cSchristos int flags); 13*4724848cSchristos 14*4724848cSchristos=head1 DESCRIPTION 15*4724848cSchristos 16*4724848cSchristosPKCS7_encrypt() creates and returns a PKCS#7 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 RSA keys are supported in PKCS#7 and envelopedData so the recipient 23*4724848cSchristoscertificates supplied to this function must all contain RSA public keys, though 24*4724848cSchristosthey do not have to be signed using the RSA algorithm. 25*4724848cSchristos 26*4724848cSchristosEVP_des_ede3_cbc() (triple DES) is the algorithm of choice for S/MIME use 27*4724848cSchristosbecause most clients will support it. 28*4724848cSchristos 29*4724848cSchristosSome old "export grade" clients may only support weak encryption using 40 or 64 30*4724848cSchristosbit RC2. These can be used by passing EVP_rc2_40_cbc() and EVP_rc2_64_cbc() 31*4724848cSchristosrespectively. 32*4724848cSchristos 33*4724848cSchristosThe algorithm passed in the B<cipher> parameter must support ASN1 encoding of 34*4724848cSchristosits parameters. 35*4724848cSchristos 36*4724848cSchristosMany browsers implement a "sign and encrypt" option which is simply an S/MIME 37*4724848cSchristosenvelopedData containing an S/MIME signed message. This can be readily produced 38*4724848cSchristosby storing the S/MIME signed message in a memory BIO and passing it to 39*4724848cSchristosPKCS7_encrypt(). 40*4724848cSchristos 41*4724848cSchristosThe following flags can be passed in the B<flags> parameter. 42*4724848cSchristos 43*4724848cSchristosIf the B<PKCS7_TEXT> flag is set MIME headers for type B<text/plain> are 44*4724848cSchristosprepended to the data. 45*4724848cSchristos 46*4724848cSchristosNormally the supplied content is translated into MIME canonical format (as 47*4724848cSchristosrequired by the S/MIME specifications) if B<PKCS7_BINARY> is set no translation 48*4724848cSchristosoccurs. This option should be used if the supplied data is in binary format 49*4724848cSchristosotherwise the translation will corrupt it. If B<PKCS7_BINARY> is set then 50*4724848cSchristosB<PKCS7_TEXT> is ignored. 51*4724848cSchristos 52*4724848cSchristosIf the B<PKCS7_STREAM> flag is set a partial B<PKCS7> structure is output 53*4724848cSchristossuitable for streaming I/O: no data is read from the BIO B<in>. 54*4724848cSchristos 55*4724848cSchristos=head1 NOTES 56*4724848cSchristos 57*4724848cSchristosIf the flag B<PKCS7_STREAM> is set the returned B<PKCS7> structure is B<not> 58*4724848cSchristoscomplete and outputting its contents via a function that does not 59*4724848cSchristosproperly finalize the B<PKCS7> structure will give unpredictable 60*4724848cSchristosresults. 61*4724848cSchristos 62*4724848cSchristosSeveral functions including SMIME_write_PKCS7(), i2d_PKCS7_bio_stream(), 63*4724848cSchristosPEM_write_bio_PKCS7_stream() finalize the structure. Alternatively finalization 64*4724848cSchristoscan be performed by obtaining the streaming ASN1 B<BIO> directly using 65*4724848cSchristosBIO_new_PKCS7(). 66*4724848cSchristos 67*4724848cSchristos=head1 RETURN VALUES 68*4724848cSchristos 69*4724848cSchristosPKCS7_encrypt() returns either a PKCS7 structure or NULL if an error occurred. 70*4724848cSchristosThe error can be obtained from ERR_get_error(3). 71*4724848cSchristos 72*4724848cSchristos=head1 SEE ALSO 73*4724848cSchristos 74*4724848cSchristosL<ERR_get_error(3)>, L<PKCS7_decrypt(3)> 75*4724848cSchristos 76*4724848cSchristos=head1 HISTORY 77*4724848cSchristos 78*4724848cSchristosThe B<PKCS7_STREAM> flag was added in OpenSSL 1.0.0. 79*4724848cSchristos 80*4724848cSchristos=head1 COPYRIGHT 81*4724848cSchristos 82*4724848cSchristosCopyright 2002-2016 The OpenSSL Project Authors. All Rights Reserved. 83*4724848cSchristos 84*4724848cSchristosLicensed under the OpenSSL license (the "License"). You may not use 85*4724848cSchristosthis file except in compliance with the License. You can obtain a copy 86*4724848cSchristosin the file LICENSE in the source distribution or at 87*4724848cSchristosL<https://www.openssl.org/source/license.html>. 88*4724848cSchristos 89*4724848cSchristos=cut 90