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