feat: Implicit rejection api for PKCS#1 v1.5

Author: lubux

.typos.toml

@@ -1,3 +1,8 @@
 [default.extend-identifiers]
 # typ stands for type, but it's a reserved identifier
 typ = "typ"
+
+[files]
+extend-exclude = [
+  "/tests/examples/**",
+]

Cargo.lock

@@ -29,6 +29,7 @@ pkcs8 = { version = "0.11.0-rc.10", optional = true, default-features = false, f
 serdect = { version = "0.4", optional = true }
 sha1 = { version = "0.11.0-rc.5", optional = true, default-features = false, features = ["oid"] }
 sha2 = { version = "0.11.0-rc.5", optional = true, default-features = false, features = ["oid"] }
+hmac = { version = "0.13.0", optional = true, default-features = false }
 spki = { version = "0.8.0-rc.4", optional = true, default-features = false, features = ["alloc"] }
 serde = { version = "1.0.184", optional = true, default-features = false, features = ["derive"] }
 
@@ -58,6 +59,7 @@ getrandom = ["crypto-bigint/getrandom", "crypto-common"]
 serde = ["encoding", "dep:serde", "dep:serdect", "crypto-bigint/serde"]
 pkcs5 = ["pkcs8/encryption"]
 std = ["pkcs1?/std", "pkcs8?/std"]
+implicit_rejection = ["sha2", "dep:hmac"]
 
 [package.metadata.docs.rs]
 features = ["std", "serde", "hazmat", "sha2"]

Cargo.toml

@@ -15,6 +15,15 @@ use zeroize::Zeroizing;
 
 use crate::errors::{Error, Result};
 
+#[cfg(feature = "implicit_rejection")]
+use {
+    crate::algorithms::pad::uint_to_zeroizing_be_pad,
+    crypto_bigint::{BoxedUint, CtGt, CtLt},
+    digest::OutputSizeUser,
+    hmac::{Hmac, KeyInit, Mac},
+    sha2::Sha256,
+};
+
 /// Fills the provided slice with random values, which are guaranteed
 /// to not be zero.
 #[inline]
@@ -116,6 +125,190 @@ fn decrypt_inner(em: Vec<u8>, k: usize) -> Result<(u8, Vec<u8>, u32)> {
     Ok((valid.to_u8(), em, index))
 }
 
+/// Removes PKCS#1 v1.5 encryption padding with implicit rejection.
+///
+/// Unlike [`pkcs1v15_encrypt_unpad`], this function does not return an error if
+/// the padding is invalid. Instead, it deterministically generates and returns
+/// a replacement random message using a key-derivation function.
+/// As a result, callers cannot distinguish between valid and
+/// invalid padding based on the output, thus preventing side-channel attacks.
+///
+/// See
+/// [draft-irtf-cfrg-rsa-guidance-08 § 7.2](https://datatracker.ietf.org/doc/html/draft-irtf-cfrg-rsa-guidance-08#section-7.2)
+#[cfg(feature = "implicit_rejection")]
+pub(crate) fn pkcs1v15_encrypt_unpad_implicit_rejection(
+    em: Vec<u8>,
+    k: usize,
+    kdk: &KeyDerivationKey,
+) -> Result<Vec<u8>> {
+    const LENGTH_LABEL: &[u8] = b"length";
+    const MESSAGE_LABEL: &[u8] = b"message";
+
+    if k < 11 || k != em.len() {
+        return Err(Error::Decryption);
+    }
+
+    // The maximum allowed message size is the modulus size minus 2 bytes
+    // and a minimum of 8 bytes for padding.
+    let max_length = u16::try_from(k - 10).map_err(|_| Error::Decryption)?;
+
+    // CL = IRPRF (KDK, "length", 256).
+    let rejection_lengths = kdk.prf(LENGTH_LABEL, 256)?;
+
+    // AM = IRPRF (KDK, "message", k).
+    let rejection_message = kdk.prf(MESSAGE_LABEL, k)?;
+
+    // Mask with 1s up to the most significant bit set in max_length.
+    // This ensures the mask covers all bits up to the highest bit set.
+    let mut mask = max_length;
+    mask |= mask >> 1;
+    mask |= mask >> 2;
+    mask |= mask >> 4;
+    mask |= mask >> 8;
+
+    // Select the rejection length from the prf output.
+    let rejection_length = rejection_lengths.chunks_exact(2).fold(0u16, |acc, el| {
+        let candidate_length = (u16::from(el[0]) << 8 | u16::from(el[1])) & mask;
+        let less_than_max_length = candidate_length.ct_lt(&max_length);
+        acc.ct_select(&candidate_length, less_than_max_length)
+    });
+
+    let Some(rejection_msg_index) = k.checked_sub(usize::from(rejection_length)) else {
+        return Err(Error::Decryption);
+    };
+
+    let first_byte_is_zero = em[0].ct_eq(&0u8);
+    let second_byte_is_two = em[1].ct_eq(&2u8);
+
+    // Indicates whether the zero byte has been found.
+    let mut found_zero_byte = Choice::FALSE;
+    // Padding | message separation index.
+    let mut zero_index: u32 = 0;
+
+    for (i, el) in em.iter().enumerate().skip(2) {
+        let equals0 = el.ct_eq(&0u8);
+        zero_index.ct_assign(&(i as u32), !found_zero_byte & equals0);
+        found_zero_byte |= equals0;
+    }
+
+    // Padding must be at least 8 bytes long, and it starts two bytes into the message.
+    let index_is_greater_than_prefix = zero_index.ct_gt(&9);
+
+    let valid =
+        first_byte_is_zero & second_byte_is_two & found_zero_byte & index_is_greater_than_prefix;
+
+    let real_message_index = zero_index.wrapping_add(1) as usize;
+
+    // Select either the rejection or real message depending on valid padding.
+    let message_index = rejection_msg_index.ct_select(&real_message_index, valid);
+    // At this stage, message_index does not directly reveal whether the padding check was successful,
+    // thus avoiding leaking information through the message length.
+    let mut output = vec![0u8; usize::from(max_length)];
+    for ((&em_byte, &syn_byte), out_byte) in em[message_index..]
+        .iter()
+        .zip(&rejection_message[message_index..])
+        .zip(output.iter_mut())
+    {
+        *out_byte = syn_byte.ct_select(&em_byte, valid);
+    }
+    output.truncate(em.len() - message_index);
+
+    Ok(output)
+}
+
+#[cfg(feature = "implicit_rejection")]
+pub(crate) struct KeyDerivationKey(Zeroizing<[u8; 32]>);
+
+#[cfg(feature = "implicit_rejection")]
+impl KeyDerivationKey {
+    /// Derives a key derivation key from the private key, the ciphertext, and the key length.
+    ///
+    /// ## Specifications
+    /// ```text
+    ///  
+    /// Input:
+    ///   d - RSA private exponent
+    ///   k - length in octets of the RSA modulus n
+    ///   ciphertext - the ciphertext
+    /// Output:
+    ///   KDK - the key derivation key
+    ///  
+    ///  D = I2OSP (d, k).
+    ///  DH = SHA256 (D)
+    ///  KDK = HMAC (DH, C, SHA256).
+    /// ```
+    ///
+    /// See:
+    /// [draft-irtf-cfrg-rsa-guidance-08 § 7.2.3](https://datatracker.ietf.org/doc/html/draft-irtf-cfrg-rsa-guidance-08#section-7.2)
+    #[inline]
+    pub fn derive(d: &BoxedUint, k: usize, ciphertext: &[u8]) -> Result<Self> {
+        if k < 11 {
+            return Err(Error::Decryption);
+        }
+
+        // D = I2OSP (d, k).
+        let d_padded = Zeroizing::new(uint_to_zeroizing_be_pad(d.clone(), k)?);
+
+        // DH = SHA256 (D).
+        let d_hash: Zeroizing<[u8; 32]> = Zeroizing::new(Sha256::digest(d_padded).into());
+
+        // KDK = HMAC-SHA256 (DH, C).
+        let mut mac =
+            Hmac::<Sha256>::new_from_slice(d_hash.as_ref()).map_err(|_| Error::Decryption)?;
+        if ciphertext.len() < k {
+            mac.update(&vec![0u8; k - ciphertext.len()]);
+        }
+        mac.update(ciphertext);
+        let kdk = mac.finalize();
+
+        Ok(Self(Zeroizing::new(kdk.into_bytes().into())))
+    }
+
+    /// Implements the pseudo-random function (PRF) to derive randomness for implicit rejection.
+    ///
+    /// ## Specifications
+    ///
+    /// ```text
+    /// IRPRF (KDK, label, length)
+    /// Input:
+    ///   KDK - the key derivation key
+    ///   label - a label making the output unique for a given KDK
+    ///   length - requested length of output in octets
+    /// Output: derived key, an octet string
+    /// ```
+    /// See:
+    /// [draft-irtf-cfrg-rsa-guidance-08 § 7.1] (https://datatracker.ietf.org/doc/html/draft-irtf-cfrg-rsa-guidance-08#section-7.1)
+    #[inline]
+    fn prf(&self, label: &[u8], output_len: usize) -> Result<Vec<u8>> {
+        // bitLength = 2 octets
+        // throw an error if the output length bits does not fit into 2 octets
+        let bitlen_bytes = u16::try_from(output_len * 8)
+            .map_err(|_| Error::Decryption)?
+            .to_be_bytes();
+
+        let mut prf_output = vec![0u8; output_len];
+        for (chunk_idx, chunk) in prf_output
+            .chunks_mut(Hmac::<Sha256>::output_size())
+            .enumerate()
+        {
+            // I
+            let index = u16::try_from(chunk_idx).map_err(|_| Error::Decryption)?;
+
+            // P_i = I (2 octets) || label || bitLength (2 octets)
+            let mut hmac =
+                Hmac::<Sha256>::new_from_slice(self.0.as_ref()).map_err(|_| Error::Decryption)?;
+            hmac.update(&index.to_be_bytes());
+            hmac.update(label);
+            hmac.update(&bitlen_bytes);
+
+            // chunk_i = HMAC(KDK, P_i).
+            let chunk_data = hmac.finalize();
+            chunk.copy_from_slice(&chunk_data.as_bytes()[..chunk.len()]);
+        }
+        Ok(prf_output)
+    }
+}
+
 #[inline]
 pub(crate) fn pkcs1v15_sign_pad(prefix: &[u8], hashed: &[u8], k: usize) -> Result<Vec<u8>> {
     let hash_len = hashed.len();

src/algorithms/pkcs1v15.rs

@@ -253,7 +253,7 @@ mod key;
 pub use pkcs1;
 #[cfg(feature = "encoding")]
 pub use pkcs8;
-#[cfg(feature = "sha2")]
+#[cfg(any(feature = "sha2", feature = "implicit_rejection"))]
 pub use sha2;
 
 pub use crate::{
@@ -265,5 +265,8 @@ pub use crate::{
     traits::keys::CrtValue,
 };
 
+#[cfg(feature = "implicit_rejection")]
+pub use pkcs1v15::Pkcs1v15EncryptImplicitRejection;
+
 #[cfg(feature = "hazmat")]
 pub mod hazmat;

src/lib.rs

@@ -37,6 +37,9 @@ pub use self::{
     signing_key::SigningKey, verifying_key::VerifyingKey,
 };
 
+#[cfg(feature = "implicit_rejection")]
+use crate::algorithms::pkcs1v15::{pkcs1v15_encrypt_unpad_implicit_rejection, KeyDerivationKey};
+
 use alloc::{boxed::Box, vec::Vec};
 use const_oid::AssociatedOid;
 use core::fmt::Debug;
@@ -49,6 +52,8 @@ use crate::algorithms::pkcs1v15::*;
 use crate::algorithms::rsa::{rsa_decrypt_and_check, rsa_encrypt};
 use crate::errors::{Error, Result};
 use crate::key::{self, RsaPrivateKey, RsaPublicKey};
+#[cfg(feature = "implicit_rejection")]
+use crate::traits::PrivateKeyParts;
 use crate::traits::{PaddingScheme, PublicKeyParts, SignatureScheme};
 
 /// Encryption using PKCS#1 v1.5 padding.
@@ -75,6 +80,32 @@ impl PaddingScheme for Pkcs1v15Encrypt {
     }
 }
 
+/// Encryption using PKCS#1 v1.5 padding with implicit rejection.
+#[cfg(feature = "implicit_rejection")]
+#[derive(Clone, Copy, Debug, Default, Eq, PartialEq)]
+pub struct Pkcs1v15EncryptImplicitRejection;
+
+#[cfg(feature = "implicit_rejection")]
+impl PaddingScheme for Pkcs1v15EncryptImplicitRejection {
+    fn decrypt<Rng: TryCryptoRng + ?Sized>(
+        self,
+        rng: Option<&mut Rng>,
+        priv_key: &RsaPrivateKey,
+        ciphertext: &[u8],
+    ) -> Result<Vec<u8>> {
+        decrypt_implicit_rejection(rng, priv_key, ciphertext)
+    }
+
+    fn encrypt<Rng: TryCryptoRng + ?Sized>(
+        self,
+        rng: &mut Rng,
+        pub_key: &RsaPublicKey,
+        msg: &[u8],
+    ) -> Result<Vec<u8>> {
+        encrypt(rng, pub_key, msg)
+    }
+}
+
 /// `RSASSA-PKCS1-v1_5`: digital signatures using PKCS#1 v1.5 padding.
 #[derive(Clone, Debug, Eq, PartialEq)]
 pub struct Pkcs1v15Sign {
@@ -183,6 +214,37 @@ fn decrypt<R: TryCryptoRng + ?Sized>(
     pkcs1v15_encrypt_unpad(em, priv_key.size())
 }
 
+/// Decrypts plaintext using RSA and the PKCS#1 v1.5 padding scheme with implicit rejection.
+///
+/// If an `rng` is provided, RSA blinding is used to avoid timing side-channel attacks.
+///
+/// Unlike [`decrypt`], this function does not return an error if
+/// the padding is invalid. Instead, it deterministically generates and returns
+/// a replacement random message using a key-derivation function.
+/// As a result, callers cannot distinguish between valid and
+/// invalid paddings based on the output, thus reducing the risk of side-channel attacks.
+///
+/// See
+/// [draft-irtf-cfrg-rsa-guidance-08](https://datatracker.ietf.org/doc/html/draft-irtf-cfrg-rsa-guidance-08)
+#[cfg(feature = "implicit_rejection")]
+#[inline]
+fn decrypt_implicit_rejection<R: TryCryptoRng + ?Sized>(
+    rng: Option<&mut R>,
+    priv_key: &RsaPrivateKey,
+    ciphertext: &[u8],
+) -> Result<Vec<u8>> {
+    key::check_public(priv_key)?;
+
+    let k = priv_key.size();
+    let ct_boxed = BoxedUint::from_be_slice(ciphertext, priv_key.n_bits_precision())?;
+    let em = rsa_decrypt_and_check(priv_key, rng, &ct_boxed)?;
+    // TODO: Check the timing leakage in this function.
+    let em = uint_to_zeroizing_be_pad(em, k)?;
+
+    let kdk = KeyDerivationKey::derive(priv_key.d(), k, ciphertext)?;
+    pkcs1v15_encrypt_unpad_implicit_rejection(em, k, &kdk)
+}
+
 /// Calculates the signature of hashed using
 /// RSASSA-PKCS1-V1_5-SIGN from RSA PKCS#1 v1.5. Note that `hashed` must
 /// be the result of hashing the input message using the given hash