1=pod 2 3=head1 NAME 4 5 CMS_decrypt - decrypt content from a CMS envelopedData structure 6 7=head1 SYNOPSIS 8 9 #include <openssl/cms.h> 10 11 int CMS_decrypt(CMS_ContentInfo *cms, EVP_PKEY *pkey, X509 *cert, BIO *dcont, BIO *out, unsigned int flags); 12 13=head1 DESCRIPTION 14 15CMS_decrypt() extracts and decrypts the content from a CMS EnvelopedData 16structure. B<pkey> is the private key of the recipient, B<cert> is the 17recipient's certificate, B<out> is a BIO to write the content to and 18B<flags> is an optional set of flags. 19 20The B<dcont> parameter is used in the rare case where the encrypted content 21is detached. It will normally be set to NULL. 22 23=head1 NOTES 24 25OpenSSL_add_all_algorithms() (or equivalent) should be called before using this 26function or errors about unknown algorithms will occur. 27 28Although the recipients certificate is not needed to decrypt the data it is 29needed to locate the appropriate (of possible several) recipients in the CMS 30structure. 31 32If B<cert> is set to NULL all possible recipients are tried. This case however 33is problematic. To thwart the MMA attack (Bleichenbacher's attack on 34PKCS #1 v1.5 RSA padding) all recipients are tried whether they succeed or 35not. If no recipient succeeds then a random symmetric key is used to decrypt 36the content: this will typically output garbage and may (but is not guaranteed 37to) ultimately return a padding error only. If CMS_decrypt() just returned an 38error when all recipient encrypted keys failed to decrypt an attacker could 39use this in a timing attack. If the special flag B<CMS_DEBUG_DECRYPT> is set 40then the above behaviour is modified and an error B<is> returned if no 41recipient encrypted key can be decrypted B<without> generating a random 42content encryption key. Applications should use this flag with 43B<extreme caution> especially in automated gateways as it can leave them 44open to attack. 45 46It is possible to determine the correct recipient key by other means (for 47example looking them up in a database) and setting them in the CMS structure 48in advance using the CMS utility functions such as CMS_set1_pkey(). In this 49case both B<cert> and B<pkey> should be set to NULL. 50 51To process KEKRecipientInfo types CMS_set1_key() or CMS_RecipientInfo_set0_key() 52and CMS_ReceipientInfo_decrypt() should be called before CMS_decrypt() and 53B<cert> and B<pkey> set to NULL. 54 55The following flags can be passed in the B<flags> parameter. 56 57If the B<CMS_TEXT> flag is set MIME headers for type B<text/plain> are deleted 58from the content. If the content is not of type B<text/plain> then an error is 59returned. 60 61=head1 RETURN VALUES 62 63CMS_decrypt() returns either 1 for success or 0 for failure. 64The error can be obtained from ERR_get_error(3) 65 66=head1 BUGS 67 68The lack of single pass processing and the need to hold all data in memory as 69mentioned in CMS_verify() also applies to CMS_decrypt(). 70 71=head1 SEE ALSO 72 73L<ERR_get_error(3)|ERR_get_error(3)>, L<CMS_encrypt(3)|CMS_encrypt(3)> 74 75=head1 HISTORY 76 77CMS_decrypt() was added to OpenSSL 0.9.8 78 79=cut 80