Improve EVP_PKEY_sign documentation

[openssl.git] / doc / crypto / CMS_decrypt.pod

diff --git a/doc/crypto/CMS_decrypt.pod b/doc/crypto/CMS_decrypt.pod
index b6bb3b1188cddf687c62498783bce16e50081fe0..3fa9212af32cf1c93dc50189fa3510c3068bb444 100644 (file)
--- a/doc/crypto/CMS_decrypt.pod
+++ b/doc/crypto/CMS_decrypt.pod
@@ -2,19 +2,19 @@
 
 =head1 NAME
 
-CMS_decrypt - decrypt content from a CMS envelopedData structure
+ CMS_decrypt - decrypt content from a CMS envelopedData structure
 
 =head1 SYNOPSIS
 
  #include <openssl/cms.h>
 
- int CMS_decrypt(CMS_ContentInfo *cms, EVP_PKEY *pkey, X509 *cert, BIO *data, BIO *dcont, unsigned int flags);
+ int CMS_decrypt(CMS_ContentInfo *cms, EVP_PKEY *pkey, X509 *cert, BIO *dcont, BIO *out, unsigned int flags);
 
 =head1 DESCRIPTION
 
-CMS_decrypt() extracts and decrypts the content from a CMS envelopedData
+CMS_decrypt() extracts and decrypts the content from a CMS EnvelopedData
 structure. B<pkey> is the private key of the recipient, B<cert> is the
-recipients certificate, B<data> is a BIO to write the content to and
+recipient's certificate, B<out> is a BIO to write the content to and
 B<flags> is an optional set of flags.
 
 The B<dcont> parameter is used in the rare case where the encrypted content
@@ -27,15 +27,30 @@ function or errors about unknown algorithms will occur.
 
 Although the recipients certificate is not needed to decrypt the data it is
 needed to locate the appropriate (of possible several) recipients in the CMS
-structure. If B<cert> is set to NULL all possible recipients are tried.
+structure.
+
+If B<cert> is set to NULL all possible recipients are tried. This case however
+is problematic. To thwart the MMA attack (Bleichenbacher's attack on
+PKCS #1 v1.5 RSA padding) all recipients are tried whether they succeed or
+not. If no recipient succeeds then a random symmetric key is used to decrypt
+the content: this will typically output garbage and may (but is not guaranteed
+to) ultimately return a padding error only. If CMS_decrypt() just returned an
+error when all recipient encrypted keys failed to decrypt an attacker could
+use this in a timing attack. If the special flag B<CMS_DEBUG_DECRYPT> is set
+then the above behaviour is modified and an error B<is> returned if no
+recipient encrypted key can be decrypted B<without> generating a random
+content encryption key. Applications should use this flag with
+B<extreme caution> especially in automated gateways as it can leave them
+open to attack.
 
 It is possible to determine the correct recipient key by other means (for
 example looking them up in a database) and setting them in the CMS structure
 in advance using the CMS utility functions such as CMS_set1_pkey(). In this
 case both B<cert> and B<pkey> should be set to NULL.
 
-To process KEKRecipientInfo types CMS_set1_key() should be used and B<cert>
-and B<pkey> set to NULL.
+To process KEKRecipientInfo types CMS_set1_key() or CMS_RecipientInfo_set0_key()
+and CMS_ReceipientInfo_decrypt() should be called before CMS_decrypt() and
+B<cert> and B<pkey> set to NULL.
 
 The following flags can be passed in the B<flags> parameter.