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