1=pod 2 3=head1 NAME 4 5CMS_decrypt, CMS_decrypt_set1_pkey_and_peer, 6CMS_decrypt_set1_pkey, CMS_decrypt_set1_password 7- decrypt content from a CMS envelopedData structure 8 9=head1 SYNOPSIS 10 11 #include <openssl/cms.h> 12 13 int CMS_decrypt(CMS_ContentInfo *cms, EVP_PKEY *pkey, X509 *cert, 14 BIO *dcont, BIO *out, unsigned int flags); 15 int CMS_decrypt_set1_pkey_and_peer(CMS_ContentInfo *cms, 16 EVP_PKEY *pk, X509 *cert, X509 *peer); 17 int CMS_decrypt_set1_pkey(CMS_ContentInfo *cms, EVP_PKEY *pk, X509 *cert); 18 int CMS_decrypt_set1_password(CMS_ContentInfo *cms, 19 unsigned char *pass, ossl_ssize_t passlen); 20 21=head1 DESCRIPTION 22 23CMS_decrypt() extracts the decrypted content from a CMS EnvelopedData 24or AuthEnvelopedData structure. 25It uses CMS_decrypt_set1_pkey() to decrypt the content 26with the recipient private key I<pkey> if I<pkey> is not NULL. 27In this case, the associated certificate is recommended to provide in I<cert> - 28see the NOTES below. 29I<out> is a BIO to write the content to and 30I<flags> is an optional set of flags. 31If I<pkey> is NULL the function assumes that decryption was already done 32(e.g., using CMS_decrypt_set1_pkey() or CMS_decrypt_set1_password()) and just 33provides the content unless I<cert>, I<dcont>, and I<out> are NULL as well. 34The I<dcont> parameter is used in the rare case where the encrypted content 35is detached. It will normally be set to NULL. 36 37CMS_decrypt_set1_pkey_and_peer() decrypts the CMS_ContentInfo structure I<cms> 38using the private key I<pkey>, the corresponding certificate I<cert>, which is 39recommended but may be NULL, and the (optional) originator certificate I<peer>. 40On success, it also records in I<cms> the decryption key I<pkey>, and then 41should be followed by C<CMS_decrypt(cms, NULL, NULL, dcont, out, flags)>. 42This call deallocates any decryption key stored in I<cms>. 43 44CMS_decrypt_set1_pkey() is the same as 45CMS_decrypt_set1_pkey_and_peer() with I<peer> being NULL. 46 47CMS_decrypt_set1_password() decrypts the CMS_ContentInfo structure I<cms> 48using the secret I<pass> of length I<passlen>. 49On success, it also records in I<cms> the decryption key used, and then 50should be followed by C<CMS_decrypt(cms, NULL, NULL, dcont, out, flags)>. 51This call deallocates any decryption key stored in I<cms>. 52 53=head1 NOTES 54 55Although the recipients certificate is not needed to decrypt the data it is 56needed to locate the appropriate (of possible several) recipients in the CMS 57structure. 58 59If I<cert> is set to NULL all possible recipients are tried. This case however 60is problematic. To thwart the MMA attack (Bleichenbacher's attack on 61PKCS #1 v1.5 RSA padding) all recipients are tried whether they succeed or 62not. If no recipient succeeds then a random symmetric key is used to decrypt 63the content: this will typically output garbage and may (but is not guaranteed 64to) ultimately return a padding error only. If CMS_decrypt() just returned an 65error when all recipient encrypted keys failed to decrypt an attacker could 66use this in a timing attack. If the special flag B<CMS_DEBUG_DECRYPT> is set 67then the above behaviour is modified and an error B<is> returned if no 68recipient encrypted key can be decrypted B<without> generating a random 69content encryption key. Applications should use this flag with 70B<extreme caution> especially in automated gateways as it can leave them 71open to attack. 72 73It is possible to determine the correct recipient key by other means (for 74example looking them up in a database) and setting them in the CMS structure 75in advance using the CMS utility functions such as CMS_set1_pkey(), 76or use CMS_decrypt_set1_password() if the recipient has a symmetric key. 77In these cases both I<cert> and I<pkey> should be set to NULL. 78 79To process KEKRecipientInfo types CMS_set1_key() or CMS_RecipientInfo_set0_key() 80and CMS_RecipientInfo_decrypt() should be called before CMS_decrypt() and 81I<cert> and I<pkey> set to NULL. 82 83The following flags can be passed in the I<flags> parameter. 84 85If the B<CMS_TEXT> flag is set MIME headers for type C<text/plain> are deleted 86from the content. If the content is not of type C<text/plain> then an error is 87returned. 88 89=head1 RETURN VALUES 90 91CMS_decrypt(), CMS_decrypt_set1_pkey_and_peer(), 92CMS_decrypt_set1_pkey(), and CMS_decrypt_set1_password() 93return either 1 for success or 0 for failure. 94The error can be obtained from ERR_get_error(3). 95 96=head1 BUGS 97 98The B<set1_> part of these function names is misleading 99and should better read: B<with_>. 100 101The lack of single pass processing and the need to hold all data in memory as 102mentioned in CMS_verify() also applies to CMS_decrypt(). 103 104=head1 SEE ALSO 105 106L<ERR_get_error(3)>, L<CMS_encrypt(3)> 107 108=head1 HISTORY 109 110CMS_decrypt_set1_pkey_and_peer() and CMS_decrypt_set1_password() 111were added in OpenSSL 3.0. 112 113=head1 COPYRIGHT 114 115Copyright 2008-2020 The OpenSSL Project Authors. All Rights Reserved. 116 117Licensed under the Apache License 2.0 (the "License"). You may not use 118this file except in compliance with the License. You can obtain a copy 119in the file LICENSE in the source distribution or at 120L<https://www.openssl.org/source/license.html>. 121 122=cut 123
