1238384Sjkim=pod 2238384Sjkim 3238384Sjkim=head1 NAME 4238384Sjkim 5238384Sjkim CMS_decrypt - decrypt content from a CMS envelopedData structure 6238384Sjkim 7238384Sjkim=head1 SYNOPSIS 8238384Sjkim 9238384Sjkim #include <openssl/cms.h> 10238384Sjkim 11238384Sjkim int CMS_decrypt(CMS_ContentInfo *cms, EVP_PKEY *pkey, X509 *cert, BIO *dcont, BIO *out, unsigned int flags); 12238384Sjkim 13238384Sjkim=head1 DESCRIPTION 14238384Sjkim 15238384SjkimCMS_decrypt() extracts and decrypts the content from a CMS EnvelopedData 16238384Sjkimstructure. B<pkey> is the private key of the recipient, B<cert> is the 17238384Sjkimrecipient's certificate, B<out> is a BIO to write the content to and 18238384SjkimB<flags> is an optional set of flags. 19238384Sjkim 20238384SjkimThe B<dcont> parameter is used in the rare case where the encrypted content 21238384Sjkimis detached. It will normally be set to NULL. 22238384Sjkim 23238384Sjkim=head1 NOTES 24238384Sjkim 25238384SjkimOpenSSL_add_all_algorithms() (or equivalent) should be called before using this 26238384Sjkimfunction or errors about unknown algorithms will occur. 27238384Sjkim 28238384SjkimAlthough the recipients certificate is not needed to decrypt the data it is 29238384Sjkimneeded to locate the appropriate (of possible several) recipients in the CMS 30267258Sjkimstructure. 31238384Sjkim 32267258SjkimIf B<cert> is set to NULL all possible recipients are tried. This case however 33267258Sjkimis problematic. To thwart the MMA attack (Bleichenbacher's attack on 34267258SjkimPKCS #1 v1.5 RSA padding) all recipients are tried whether they succeed or 35267258Sjkimnot. If no recipient succeeds then a random symmetric key is used to decrypt 36267258Sjkimthe content: this will typically output garbage and may (but is not guaranteed 37267258Sjkimto) ultimately return a padding error only. If CMS_decrypt() just returned an 38267258Sjkimerror when all recipient encrypted keys failed to decrypt an attacker could 39267258Sjkimuse this in a timing attack. If the special flag B<CMS_DEBUG_DECRYPT> is set 40267258Sjkimthen the above behaviour is modified and an error B<is> returned if no 41267258Sjkimrecipient encrypted key can be decrypted B<without> generating a random 42267258Sjkimcontent encryption key. Applications should use this flag with 43267258SjkimB<extreme caution> especially in automated gateways as it can leave them 44267258Sjkimopen to attack. 45267258Sjkim 46238384SjkimIt is possible to determine the correct recipient key by other means (for 47238384Sjkimexample looking them up in a database) and setting them in the CMS structure 48238384Sjkimin advance using the CMS utility functions such as CMS_set1_pkey(). In this 49238384Sjkimcase both B<cert> and B<pkey> should be set to NULL. 50238384Sjkim 51238384SjkimTo process KEKRecipientInfo types CMS_set1_key() or CMS_RecipientInfo_set0_key() 52238384Sjkimand CMS_ReceipientInfo_decrypt() should be called before CMS_decrypt() and 53238384SjkimB<cert> and B<pkey> set to NULL. 54238384Sjkim 55238384SjkimThe following flags can be passed in the B<flags> parameter. 56238384Sjkim 57238384SjkimIf the B<CMS_TEXT> flag is set MIME headers for type B<text/plain> are deleted 58238384Sjkimfrom the content. If the content is not of type B<text/plain> then an error is 59238384Sjkimreturned. 60238384Sjkim 61238384Sjkim=head1 RETURN VALUES 62238384Sjkim 63238384SjkimCMS_decrypt() returns either 1 for success or 0 for failure. 64238384SjkimThe error can be obtained from ERR_get_error(3) 65238384Sjkim 66238384Sjkim=head1 BUGS 67238384Sjkim 68238384SjkimThe lack of single pass processing and the need to hold all data in memory as 69238384Sjkimmentioned in CMS_verify() also applies to CMS_decrypt(). 70238384Sjkim 71238384Sjkim=head1 SEE ALSO 72238384Sjkim 73238384SjkimL<ERR_get_error(3)|ERR_get_error(3)>, L<CMS_encrypt(3)|CMS_encrypt(3)> 74238384Sjkim 75238384Sjkim=head1 HISTORY 76238384Sjkim 77238384SjkimCMS_decrypt() was added to OpenSSL 0.9.8 78238384Sjkim 79238384Sjkim=cut 80