Add HasResidueRepr and ResidueRepr traits to connect integers and residue representations

Author: fjarri

src/modular/boxed_residue.rs

@@ -12,7 +12,7 @@ use super::{
     reduction::{montgomery_reduction_boxed, montgomery_reduction_boxed_mut},
     Retrieve,
 };
-use crate::{BoxedUint, Integer, Limb, NonZero, Word};
+use crate::{BoxedUint, Integer, Limb, NonZero, ResidueRepr, Word};
 use subtle::CtOption;
 
 #[cfg(feature = "std")]
@@ -240,6 +240,27 @@ impl Retrieve for BoxedResidue {
     }
 }
 
+impl ResidueRepr for BoxedResidue {
+    type Raw = BoxedUint;
+    type Precomputed = BoxedResidueParams;
+
+    fn new_precomputed(modulus: Self::Raw) -> CtOption<Self::Precomputed> {
+        BoxedResidueParams::new(modulus)
+    }
+
+    fn new(value: Self::Raw, precomputed: Self::Precomputed) -> Self {
+        BoxedResidue::new(value, precomputed)
+    }
+
+    fn zero(precomputed: Self::Precomputed) -> Self {
+        BoxedResidue::zero(precomputed)
+    }
+
+    fn one(precomputed: Self::Precomputed) -> Self {
+        BoxedResidue::one(precomputed)
+    }
+}
+
 /// Convert the given integer into the Montgomery domain.
 #[inline]
 fn convert_to_montgomery(integer: &mut BoxedUint, residue_params: &BoxedResidueParams) {

src/modular/dyn_residue.rs

@@ -13,7 +13,7 @@ use super::{
     residue::{Residue, ResidueParams},
     Retrieve,
 };
-use crate::{Limb, NonZero, Uint, Word, Zero};
+use crate::{Limb, NonZero, ResidueRepr, Uint, Word, Zero};
 use subtle::{Choice, ConditionallySelectable, ConstantTimeEq, CtOption};
 
 /// Parameters to efficiently go to/from the Montgomery form for an odd modulus provided at runtime.
@@ -208,6 +208,27 @@ impl<const LIMBS: usize> Retrieve for DynResidue<LIMBS> {
     }
 }
 
+impl<const LIMBS: usize> ResidueRepr for DynResidue<LIMBS> {
+    type Raw = Uint<LIMBS>;
+    type Precomputed = DynResidueParams<LIMBS>;
+
+    fn new_precomputed(modulus: Self::Raw) -> CtOption<Self::Precomputed> {
+        DynResidueParams::new(&modulus)
+    }
+
+    fn new(value: Self::Raw, precomputed: Self::Precomputed) -> Self {
+        DynResidue::new(&value, precomputed)
+    }
+
+    fn zero(precomputed: Self::Precomputed) -> Self {
+        DynResidue::zero(precomputed)
+    }
+
+    fn one(precomputed: Self::Precomputed) -> Self {
+        DynResidue::one(precomputed)
+    }
+}
+
 impl<const LIMBS: usize, P: ResidueParams<LIMBS>> From<&Residue<P, LIMBS>> for DynResidue<LIMBS> {
     fn from(residue: &Residue<P, LIMBS>) -> Self {
         Self {

src/traits.rs

@@ -433,3 +433,33 @@ pub trait WideningMul<Rhs = Self>: Sized {
     /// Perform widening multiplication.
     fn widening_mul(&self, rhs: Rhs) -> Self::Output;
 }
+
+/// This integer has a representation optimized for the performance of modular operations.
+pub trait HasResidueRepr {
+    /// The representation type.
+    type Residue: ResidueRepr<Raw = Self>;
+}
+
+/// A representation of an integer optimized for the performance of modular operations.
+pub trait ResidueRepr {
+    /// The original integer type.
+    type Raw: HasResidueRepr<Residue = Self>;
+
+    /// The precomputed data needed for this representation.
+    type Precomputed: Clone;
+
+    /// Create the precomputed data.
+    ///
+    /// Can return `None` if `modulus` is not valid for the representation;
+    /// see the documentation of the specific type for the requirements.
+    fn new_precomputed(modulus: Self::Raw) -> CtOption<Self::Precomputed>;
+
+    /// Convert the value into the representation using precomputed data.
+    fn new(value: Self::Raw, precomputed: Self::Precomputed) -> Self;
+
+    /// Returns zero in this representation.
+    fn zero(precomputed: Self::Precomputed) -> Self;
+
+    /// Returns one in this representation.
+    fn one(precomputed: Self::Precomputed) -> Self;
+}

src/uint.rs

@@ -38,7 +38,10 @@ pub(crate) mod boxed;
 #[cfg(feature = "rand_core")]
 mod rand;
 
-use crate::{Bounded, Constants, Encoding, FixedInteger, Integer, Limb, Word, ZeroConstant};
+use crate::{
+    modular::DynResidue, Bounded, Constants, Encoding, FixedInteger, HasResidueRepr, Integer, Limb,
+    Word, ZeroConstant,
+};
 use core::fmt;
 use subtle::{Choice, ConditionallySelectable};
 
@@ -249,6 +252,10 @@ impl<const LIMBS: usize> Integer for Uint<LIMBS> {
     }
 }
 
+impl<const LIMBS: usize> HasResidueRepr for Uint<LIMBS> {
+    type Residue = DynResidue<LIMBS>;
+}
+
 impl<const LIMBS: usize> ZeroConstant for Uint<LIMBS> {
     const ZERO: Self = Self::ZERO;
 }

src/uint/boxed.rs

@@ -24,7 +24,9 @@ mod neg_mod;
 #[cfg(feature = "rand_core")]
 mod rand;
 
-use crate::{Integer, Limb, NonZero, Uint, Word, Zero, U128, U64};
+use crate::{
+    modular::BoxedResidue, HasResidueRepr, Integer, Limb, NonZero, Uint, Word, Zero, U128, U64,
+};
 use alloc::{boxed::Box, vec, vec::Vec};
 use core::{fmt, mem};
 use subtle::{Choice, ConditionallySelectable, ConstantTimeEq};
@@ -403,6 +405,10 @@ impl Zero for BoxedUint {
     }
 }
 
+impl HasResidueRepr for BoxedUint {
+    type Residue = BoxedResidue;
+}
+
 #[cfg(feature = "zeroize")]
 impl Zeroize for BoxedUint {
     fn zeroize(&mut self) {