crypto/rsa: make DecryptPKCS1v15SessionKey warning more dire

Updates the DecryptPKCS1v15SessionKey function comment to be less cut
and dry about its protections against Bleichenbacher attacks. In
particular note that the protocol using this method must be explicitly
designed with these mitigations in mind, and call out usages which
may cause the migiations to be useless.

Change-Id: I06fd25157f12a3afb401bb08dff4faef7fb0a9b0
Reviewed-on: https://go-review.googlesource.com/c/go/+/469235
Reviewed-by: Filippo Valsorda <[email protected]>
Reviewed-by: Roland Shoemaker <[email protected]>
TryBot-Result: Gopher Robot <[email protected]>
Run-TryBot: Roland Shoemaker <[email protected]>
Auto-Submit: Roland Shoemaker <[email protected]>
Reviewed-by: David Chase <[email protected]>

Author: rolandshoemaker

src/crypto/rsa/pkcs1v15.go

@@ -113,25 +113,40 @@ func DecryptPKCS1v15(random io.Reader, priv *PrivateKey, ciphertext []byte) ([]b
 	return out[index:], nil
 }
 
-// DecryptPKCS1v15SessionKey decrypts a session key using RSA and the padding scheme from PKCS #1 v1.5.
-// The random parameter is legacy and ignored, and it can be as nil.
-// It returns an error if the ciphertext is the wrong length or if the
-// ciphertext is greater than the public modulus. Otherwise, no error is
-// returned. If the padding is valid, the resulting plaintext message is copied
-// into key. Otherwise, key is unchanged. These alternatives occur in constant
-// time. It is intended that the user of this function generate a random
-// session key beforehand and continue the protocol with the resulting value.
-// This will remove any possibility that an attacker can learn any information
-// about the plaintext.
-// See “Chosen Ciphertext Attacks Against Protocols Based on the RSA
-// Encryption Standard PKCS #1”, Daniel Bleichenbacher, Advances in Cryptology
-// (Crypto '98).
+// DecryptPKCS1v15SessionKey decrypts a session key using RSA and the padding
+// scheme from PKCS #1 v1.5. The random parameter is legacy and ignored, and it
+// can be nil.
+//
+// DecryptPKCS1v15SessionKey returns an error if the ciphertext is the wrong
+// length or if the ciphertext is greater than the public modulus. Otherwise, no
+// error is returned. If the padding is valid, the resulting plaintext message
+// is copied into key. Otherwise, key is unchanged. These alternatives occur in
+// constant time. It is intended that the user of this function generate a
+// random session key beforehand and continue the protocol with the resulting
+// value.
 //
 // Note that if the session key is too small then it may be possible for an
-// attacker to brute-force it. If they can do that then they can learn whether
-// a random value was used (because it'll be different for the same ciphertext)
-// and thus whether the padding was correct. This defeats the point of this
+// attacker to brute-force it. If they can do that then they can learn whether a
+// random value was used (because it'll be different for the same ciphertext)
+// and thus whether the padding was correct. This also defeats the point of this
 // function. Using at least a 16-byte key will protect against this attack.
+//
+// This method implements protections against Bleichenbacher chosen ciphertext
+// attacks [0] described in RFC 3218 Section 2.3.2 [1]. While these protections
+// make a Bleichenbacher attack significantly more difficult, the protections
+// are only effective if the rest of the protocol which uses
+// DecryptPKCS1v15SessionKey is designed with these considerations in mind. In
+// particular, if any subsequent operations which use the decrypted session key
+// leak any information about the key (e.g. whether it is a static or random
+// key) then the mitigations are defeated. This method must be used extremely
+// carefully, and typically should only be used when absolutely necessary for
+// compatibility with an existing protocol (such as TLS) that is designed with
+// these properties in mind.
+//
+//   - [0] “Chosen Ciphertext Attacks Against Protocols Based on the RSA Encryption
+//     Standard PKCS #1”, Daniel Bleichenbacher, Advances in Cryptology (Crypto '98)
+//   - [1] RFC 3218, Preventing the Million Message Attack on CMS,
+//     https://www.rfc-editor.org/rfc/rfc3218.html
 func DecryptPKCS1v15SessionKey(random io.Reader, priv *PrivateKey, ciphertext []byte, key []byte) error {
 	if err := checkPub(&priv.PublicKey); err != nil {
 		return err