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 <filippo@golang.org>
Reviewed-by: Roland Shoemaker <roland@golang.org>
TryBot-Result: Gopher Robot <gobot@golang.org>
Run-TryBot: Roland Shoemaker <roland@golang.org>
Auto-Submit: Roland Shoemaker <roland@golang.org>
Reviewed-by: David Chase <drchase@google.com>

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.
+// DecryptPKCS1v15SessionKey decrypts a session key using RSA and the padding
-// The random parameter is legacy and ignored, and it can be as nil.
+// scheme from PKCS #1 v1.5. The random parameter is legacy and ignored, and it
-// It returns an error if the ciphertext is the wrong length or if the
+// can be nil.
-// ciphertext is greater than the public modulus. Otherwise, no error is
+//
-// returned. If the padding is valid, the resulting plaintext message is copied
+// DecryptPKCS1v15SessionKey returns an error if the ciphertext is the wrong
-// into key. Otherwise, key is unchanged. These alternatives occur in constant
+// length or if the ciphertext is greater than the public modulus. Otherwise, no
-// time. It is intended that the user of this function generate a random
+// error is returned. If the padding is valid, the resulting plaintext message
-// session key beforehand and continue the protocol with the resulting value.
+// is copied into key. Otherwise, key is unchanged. These alternatives occur in
-// This will remove any possibility that an attacker can learn any information
+// constant time. It is intended that the user of this function generate a
-// about the plaintext.
+// random session key beforehand and continue the protocol with the resulting
-// See “Chosen Ciphertext Attacks Against Protocols Based on the RSA
+// value.
-// Encryption Standard PKCS #1”, Daniel Bleichenbacher, Advances in Cryptology
-// (Crypto '98).
 //
 // 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
+// attacker to brute-force it. If they can do that then they can learn whether a
-// a random value was used (because it'll be different for the same ciphertext)
+// 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
+// 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