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