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