Add Bleichenbacher attack warning about PKCS#1 v1.5 (#637)

Notes the long history of repeat attacks, and how the `rsa` crate is
still vulnerable to the Marvin Attack.

Author: tarcieri

src/lib.rs

@@ -45,6 +45,12 @@
 //! ```
 //!
 //! ## PKCS#1 v1.5 encryption
+//!
+//! <div class="warning">
+//! <b>Warning:</b>
+//! See security notes in the <code><a href="./pkcs1v15/index.html">pkcs1v15</a></code> module.
+//! </div>
+//!
 //! ```
 //! use rsa::{RsaPrivateKey, RsaPublicKey, Pkcs1v15Encrypt};
 //!
@@ -66,6 +72,11 @@
 //!
 //! ## PKCS#1 v1.5 signatures
 //!
+//! <div class="warning">
+//! <b>Warning:</b>
+//! See security notes in the <code><a href="./pkcs1v15/index.html">pkcs1v15</a></code> module.
+//! </div>
+//!
 //! Note: requires `sha2` feature of `rsa` crate is enabled.
 //!
 #![cfg_attr(feature = "sha2", doc = "```")]

src/pkcs1v15.rs

@@ -1,5 +1,25 @@
 //! PKCS#1 v1.5 support as described in [RFC8017 § 8.2].
 //!
+//! <div class="warning">
+//! <b>Warning</b>
+//!
+//! PKCS#1 v1.5 padding has a longstanding history of issues generally classed as
+//! [Bleichenbacher Attacks] which were originally discovered in 1998 but keep reappearing in
+//! various forms again and again over the course of decades, including most recently in the 2023
+//! [Marvin Attack], which the `rsa` crate is [still vulnerable] to.
+//!
+//! These attacks can result in complete plaintext recovery for encryption, or signature forgery,
+//! leading to a total failure of either confidentiality or integrity.
+//!
+//! Unless explicitly needed for compatibility reasons, we recommend against using PKCS#1 v1.5,
+//! and suggest using [PSS][`super::pss`] or [OAEP][`super::oaep`] instead (if there is a
+//! requirement to use RSA).
+//! </div>
+//!
+//! [Bleichenbacher Attacks]: https://en.wikipedia.org/wiki/Adaptive_chosen-ciphertext_attack#Practical_attacks
+//! [Marvin Attack]: https://people.redhat.com/~hkario/marvin/
+//! [still vulnerable]: https://github.com/RustCrypto/RSA/issues/626
+//!
 //! # Usage
 //!
 //! See [code example in the toplevel rustdoc](../index.html#pkcs1-v15-signatures).