Tighten up the warning about RSAES-PKCS1-v1_5
RSAES-PKCS1-v1_5 is broken and should be described as such.
Change-Id: I11f74fbfcef7b44579a333798240147f67cf896c
Reviewed-on: https://boringssl-review.googlesource.com/c/boringssl/+/66107
Commit-Queue: Adam Langley <agl@google.com>
Reviewed-by: Adam Langley <agl@google.com>
Auto-Submit: David Benjamin <davidben@google.com>
Commit-Queue: David Benjamin <davidben@google.com>
diff --git a/include/openssl/rsa.h b/include/openssl/rsa.h
index fd183f7..5bf2b50 100644
--- a/include/openssl/rsa.h
+++ b/include/openssl/rsa.h
@@ -236,6 +236,13 @@
// RSA_PKCS1_PADDING denotes PKCS#1 v1.5 padding. When used with encryption,
// this is RSAES-PKCS1-v1_5. When used with signing, this is RSASSA-PKCS1-v1_5.
+//
+// WARNING: The RSAES-PKCS1-v1_5 encryption scheme is vulnerable to a
+// chosen-ciphertext attack. Decrypting attacker-supplied ciphertext with
+// RSAES-PKCS1-v1_5 may give the attacker control over your private key. This
+// does not impact the RSASSA-PKCS1-v1_5 signature scheme. See "Chosen
+// Ciphertext Attacks Against Protocols Based on the RSA Encryption Standard
+// PKCS #1", Daniel Bleichenbacher, Advances in Cryptology (Crypto '98).
#define RSA_PKCS1_PADDING 1
// RSA_NO_PADDING denotes a raw RSA operation.
@@ -256,8 +263,7 @@
// It returns 1 on success or zero on error.
//
// The |padding| argument must be one of the |RSA_*_PADDING| values. If in
-// doubt, use |RSA_PKCS1_OAEP_PADDING| for new protocols but
-// |RSA_PKCS1_PADDING| is most common.
+// doubt, use |RSA_PKCS1_OAEP_PADDING| for new protocols.
OPENSSL_EXPORT int RSA_encrypt(RSA *rsa, size_t *out_len, uint8_t *out,
size_t max_out, const uint8_t *in, size_t in_len,
int padding);
@@ -271,12 +277,16 @@
// The |padding| argument must be one of the |RSA_*_PADDING| values. If in
// doubt, use |RSA_PKCS1_OAEP_PADDING| for new protocols.
//
-// Passing |RSA_PKCS1_PADDING| into this function is deprecated and insecure. If
-// implementing a protocol using RSAES-PKCS1-V1_5, use |RSA_NO_PADDING| and then
-// check padding in constant-time combined with a swap to a random session key
-// or other mitigation. See "Chosen Ciphertext Attacks Against Protocols Based
-// on the RSA Encryption Standard PKCS #1", Daniel Bleichenbacher, Advances in
-// Cryptology (Crypto '98).
+// WARNING: Passing |RSA_PKCS1_PADDING| into this function is deprecated and
+// insecure. RSAES-PKCS1-v1_5 is vulnerable to a chosen-ciphertext attack.
+// Decrypting attacker-supplied ciphertext with RSAES-PKCS1-v1_5 may give the
+// attacker control over your private key. See "Chosen Ciphertext Attacks
+// Against Protocols Based on the RSA Encryption Standard PKCS #1", Daniel
+// Bleichenbacher, Advances in Cryptology (Crypto '98).
+//
+// In some limited cases, such as TLS RSA key exchange, it is possible to
+// mitigate this flaw with custom, protocol-specific padding logic. This
+// should be implemented with |RSA_NO_PADDING|, not |RSA_PKCS1_PADDING|.
OPENSSL_EXPORT int RSA_decrypt(RSA *rsa, size_t *out_len, uint8_t *out,
size_t max_out, const uint8_t *in, size_t in_len,
int padding);
@@ -285,8 +295,7 @@
// |rsa| and writes the encrypted data to |to|. The |to| buffer must have at
// least |RSA_size| bytes of space. It returns the number of bytes written, or
// -1 on error. The |padding| argument must be one of the |RSA_*_PADDING|
-// values. If in doubt, use |RSA_PKCS1_OAEP_PADDING| for new protocols but
-// |RSA_PKCS1_PADDING| is most common.
+// values. If in doubt, use |RSA_PKCS1_OAEP_PADDING| for new protocols.
//
// WARNING: this function is dangerous because it breaks the usual return value
// convention. Use |RSA_encrypt| instead.
