Add hazmat feature as a replacement for expose-internals (#352)

External access to these functions was removed in #304 when the old
`internals` module and `expose-internals` feature were removed. There
are some valid use cases for them, though (see #351), so let's bring
back a subset of what was in `internals` using the same naming and
documentation conventions that the aes crate uses for its hazardous
functions.

Much of the added or changed documentation is derived from that in
the `aes` crate.

Fixes #351.

CHANGELOG.md

@@ -50,6 +50,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - `PublicKey`/`PrivateKey` traits ([#300])
 - `Zeroize` impl on `RsaPrivateKey`; automatically zeroized on drop ([#311])
 - `Deref<Target=RsaPublicKey>` impl on `RsaPrivateKey`; use `AsRef` instead ([#317])
+- `expose-internals` feature and public access to all functions it gated ([#304])
 
 [#268]: https://github.com/RustCrypto/RSA/pull/268
 [#270]: https://github.com/RustCrypto/RSA/pull/270

Cargo.toml

@@ -51,6 +51,7 @@ name = "key"
 
 [features]
 default = ["std", "pem", "u64_digit"]
+hazmat = []
 getrandom = ["rand_core/getrandom"]
 nightly = ["num-bigint/nightly"]
 serde = ["dep:serde", "num-bigint/serde"]
@@ -60,7 +61,7 @@ u64_digit = ["num-bigint/u64_digit"]
 std = ["digest/std", "pkcs1/std", "pkcs8/std", "rand_core/std", "signature/std"]
 
 [package.metadata.docs.rs]
-features = ["std", "pem", "serde", "sha2"]
+features = ["std", "pem", "serde", "hazmat", "sha2"]
 rustdoc-args = ["--cfg", "docsrs"]
 
 [profile.dev]

src/algorithms/rsa.rs

@@ -10,18 +10,27 @@ use zeroize::Zeroize;
 use crate::errors::{Error, Result};
 use crate::traits::{PrivateKeyParts, PublicKeyParts};
 
-/// Raw RSA encryption of m with the public key. No padding is performed.
+/// ⚠️ Raw RSA encryption of m with the public key. No padding is performed.
+///
+/// # ☢️️ WARNING: HAZARDOUS API ☢️
+///
+/// Use this function with great care! Raw RSA should never be used without an appropriate padding
+/// or signature scheme. See the [module-level documentation][crate::hazmat] for more information.
 #[inline]
-pub(crate) fn rsa_encrypt<K: PublicKeyParts>(key: &K, m: &BigUint) -> Result<BigUint> {
+pub fn rsa_encrypt<K: PublicKeyParts>(key: &K, m: &BigUint) -> Result<BigUint> {
     Ok(m.modpow(key.e(), key.n()))
 }
 
-/// Performs raw RSA decryption with no padding, resulting in a plaintext `BigUint`.
-/// Peforms RSA blinding if an `Rng` is passed.
-/// WARNING! Raw RSA MUST NOT be used. Instead a proper padding or
-/// signature scheme should be used as implemented by the `rsa` crate.
+/// ⚠️ Performs raw RSA decryption with no padding or error checking.
+///
+/// Returns a plaintext `BigUint`. Performs RSA blinding if an `Rng` is passed.
+///
+/// # ☢️️ WARNING: HAZARDOUS API ☢️
+///
+/// Use this function with great care! Raw RSA should never be used without an appropriate padding
+/// or signature scheme. See the [module-level documentation][crate::hazmat] for more information.
 #[inline]
-fn rsa_decrypt<R: CryptoRngCore + ?Sized>(
+pub fn rsa_decrypt<R: CryptoRngCore + ?Sized>(
     mut rng: Option<&mut R>,
     priv_key: &impl PrivateKeyParts,
     c: &BigUint,
@@ -112,13 +121,17 @@ fn rsa_decrypt<R: CryptoRngCore + ?Sized>(
     }
 }
 
-/// Performs RSA decryption, resulting in a plaintext `BigUint`.
-/// Peforms RSA blinding if an `Rng` is passed.
-/// This will also check for errors in the CRT computation.
-/// WARNING! Raw RSA MUST NOT be used. Instead a proper padding or
-/// signature scheme should be used as implemented by the `rsa` crate.
+/// ⚠️ Performs raw RSA decryption with no padding.
+///
+/// Returns a plaintext `BigUint`. Performs RSA blinding if an `Rng` is passed.  This will also
+/// check for errors in the CRT computation.
+///
+/// # ☢️️ WARNING: HAZARDOUS API ☢️
+///
+/// Use this function with great care! Raw RSA should never be used without an appropriate padding
+/// or signature scheme. See the [module-level documentation][crate::hazmat] for more information.
 #[inline]
-pub(crate) fn rsa_decrypt_and_check<R: CryptoRngCore + ?Sized>(
+pub fn rsa_decrypt_and_check<R: CryptoRngCore + ?Sized>(
     priv_key: &impl PrivateKeyParts,
     rng: Option<&mut R>,
     c: &BigUint,

src/hazmat.rs

@@ -0,0 +1,14 @@
+//! ⚠️ Low-level "hazmat" RSA functions.
+//!
+//! # ☢️️ WARNING: HAZARDOUS API ☢️
+//!
+//! This module holds functions that apply RSA's core encryption and decryption
+//! primitives to raw data without adding or removing appropriate padding. A
+//! well-reviewed padding scheme is crucial to the security of RSA, so there are
+//! very few valid uses cases for this API. It's intended to be used for
+//! implementing well-reviewed higher-level constructions.
+//!
+//! We do NOT recommend using it to implement any algorithm which has not
+//! received extensive peer review by cryptographers.
+
+pub use crate::algorithms::rsa::{rsa_decrypt, rsa_decrypt_and_check, rsa_encrypt};

src/lib.rs

@@ -246,3 +246,6 @@ pub use crate::{
     pss::Pss,
     traits::keys::CrtValue,
 };
+
+#[cfg(feature = "hazmat")]
+pub mod hazmat;