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