From 2beb5ce82359490aaadb3955311325a306ed8728 Mon Sep 17 00:00:00 2001
From: Tony Arcieri <bascule@gmail.com>
Date: Sun, 8 Nov 2026 15:55:39 -0700
Subject: [PATCH] rustdoc: move PSS above PKCS#1 v1.5 docs

Emphasize OAEP and PSS are what you should reach for first, since
PKCS#1 v1.5 is deprecated due to Bleichenbacher attacks.
---
 src/lib.rs | 40 ++++++++++++++++++++--------------------
 1 file changed, 20 insertions(+), 20 deletions(-)

diff --git a/src/lib.rs b/src/lib.rs
index 17683393..5dbe1d5e 100644
--- a/src/lib.rs
+++ b/src/lib.rs
@@ -70,6 +70,26 @@
 //! # }
 //! ```
 //!
+//! ## PSS signatures
+//!
+#![cfg_attr(feature = "getrandom", doc = "```")]
+#![cfg_attr(not(feature = "getrandom"), doc = "```ignore")]
+//! # fn main() -> Result<(), rsa::Error> {
+//! use rsa::{Generate, PrivateKey, sha2::Sha256};
+//!
+//! let private_key = PrivateKey::generate();
+//! let public_key = private_key.to_public_key();
+//!
+//! // Sign
+//! let data = b"hello world";
+//! let signature = private_key.pss_sign::<Sha256>(data)?;
+//!
+//! // Verify
+//! public_key.pss_verify::<Sha256>(data, &signature)?;
+//! # Ok(())
+//! # }
+//! ```
+//!
 //! ## PKCS#1 v1.5 encryption
 //!
 //! <div class="warning">
@@ -129,26 +149,6 @@
 //! # }
 //! ```
 //!
-//! ## PSS signatures
-//!
-#![cfg_attr(feature = "getrandom", doc = "```")]
-#![cfg_attr(not(feature = "getrandom"), doc = "```ignore")]
-//! # fn main() -> Result<(), rsa::Error> {
-//! use rsa::{Generate, PrivateKey, sha2::Sha256};
-//!
-//! let private_key = PrivateKey::generate();
-//! let public_key = private_key.to_public_key();
-//!
-//! // Sign
-//! let data = b"hello world";
-//! let signature = private_key.pss_sign::<Sha256>(data)?;
-//!
-//! // Verify
-//! public_key.pss_verify::<Sha256>(data, &signature)?;
-//! # Ok(())
-//! # }
-//! ```
-//!
 //! ## PKCS#1 RSA Key Encoding
 //!
 //! PKCS#1 supports a legacy format for encoding RSA keys as binary (DER) or