Add div_by_2() to Monty trait (#490)

Author: fjarri

src/modular/boxed_monty_form.rs

@@ -220,11 +220,7 @@ impl BoxedMontyForm {
         self.montgomery_form.clone()
     }
 
-    /// Performs the modular division by 2, that is for given `x` returns `y`
-    /// such that `y * 2 = x mod p`. This means:
-    /// - if `x` is even, returns `x / 2`,
-    /// - if `x` is odd, returns `(x + p) / 2`
-    ///   (since the modulus `p` in Montgomery form is always odd, this divides entirely).
+    /// Performs division by 2, that is returns `x` such that `x + x = self`.
     pub fn div_by_2(&self) -> Self {
         Self {
             montgomery_form: div_by_2::div_by_2_boxed(&self.montgomery_form, &self.params.modulus),
@@ -259,6 +255,10 @@ impl Monty for BoxedMontyForm {
     fn one(params: Self::Params) -> Self {
         BoxedMontyForm::one(params)
     }
+
+    fn div_by_2(&self) -> Self {
+        BoxedMontyForm::div_by_2(self)
+    }
 }
 
 /// Convert the given integer into the Montgomery domain.

src/modular/const_monty_form.rs

@@ -143,12 +143,8 @@ impl<MOD: ConstMontyParams<LIMBS>, const LIMBS: usize> ConstMontyForm<MOD, LIMBS
         self.montgomery_form
     }
 
-    /// Performs the modular division by 2, that is for given `x` returns `y`
-    /// such that `y * 2 = x mod p`. This means:
-    /// - if `x` is even, returns `x / 2`,
-    /// - if `x` is odd, returns `(x + p) / 2`
-    ///   (since the modulus `p` in Montgomery form is always odd, this divides entirely).
-    pub fn div_by_2(&self) -> Self {
+    /// Performs division by 2, that is returns `x` such that `x + x = self`.
+    pub const fn div_by_2(&self) -> Self {
         Self {
             montgomery_form: div_by_2(&self.montgomery_form, &MOD::MODULUS),
             phantom: PhantomData,

src/modular/div_by_2.rs

@@ -1,27 +1,26 @@
-use crate::Uint;
 #[cfg(feature = "alloc")]
 use crate::{BoxedUint, ConstantTimeSelect};
+use crate::{Odd, Uint};
 
-pub(crate) fn div_by_2<const LIMBS: usize>(a: &Uint<LIMBS>, modulus: &Uint<LIMBS>) -> Uint<LIMBS> {
-    // We are looking for such `x` that `x * 2 = y mod modulus`,
-    // where the given `a = M(y)` is the Montgomery representation of some `y`.
-    // This means that in Montgomery representation it would still apply:
-    // `M(x) + M(x) = a mod modulus`.
-    // So we can just forget about Montgomery representation, and return whatever is
-    // `a` divided by 2, and this will be the Montgomery representation of `x`.
-    // (Which means that this function works regardless of whether `a`
-    // is in Montgomery representation or not, but the algorithm below
-    // does need `modulus` to be odd)
-
+pub(crate) const fn div_by_2<const LIMBS: usize>(
+    a: &Uint<LIMBS>,
+    modulus: &Odd<Uint<LIMBS>>,
+) -> Uint<LIMBS> {
+    // We are looking for such `b` that `b + b = a mod modulus`.
     // Two possibilities:
     // - if `a` is even, we can just divide by 2;
     // - if `a` is odd, we divide `(a + modulus)` by 2.
     // To stay within the modulus we open the parentheses turning it into `a / 2 + modulus / 2 + 1`
     // ("+1" because both `a` and `modulus` are odd, we lose 0.5 in each integer division).
     // This will not overflow, so we can just use wrapping operations.
 
+    // Note that this also works if `a` is a Montgomery representation modulo `modulus`
+    // of some integer `x`.
+    // If `b + b = a mod modulus` it means that `y + y = x mod modulus` where `y` is the integer
+    // whose Mongtgomery representation is `b`.
+
     let (half, is_odd) = a.shr1_with_carry();
-    let half_modulus = modulus.shr1();
+    let half_modulus = modulus.0.shr1();
 
     let if_even = half;
     let if_odd = half
@@ -32,7 +31,7 @@ pub(crate) fn div_by_2<const LIMBS: usize>(a: &Uint<LIMBS>, modulus: &Uint<LIMBS
 }
 
 #[cfg(feature = "alloc")]
-pub(crate) fn div_by_2_boxed(a: &BoxedUint, modulus: &BoxedUint) -> BoxedUint {
+pub(crate) fn div_by_2_boxed(a: &BoxedUint, modulus: &Odd<BoxedUint>) -> BoxedUint {
     debug_assert_eq!(a.bits_precision(), modulus.bits_precision());
 
     let (mut half, is_odd) = a.shr1_with_carry();

src/modular/monty_form.rs

@@ -180,12 +180,8 @@ impl<const LIMBS: usize> MontyForm<LIMBS> {
         self.montgomery_form
     }
 
-    /// Performs the modular division by 2, that is for given `x` returns `y`
-    /// such that `y * 2 = x mod p`. This means:
-    /// - if `x` is even, returns `x / 2`,
-    /// - if `x` is odd, returns `(x + p) / 2`
-    ///   (since the modulus `p` in Montgomery form is always odd, this divides entirely).
-    pub fn div_by_2(&self) -> Self {
+    /// Performs division by 2, that is returns `x` such that `x + x = self`.
+    pub const fn div_by_2(&self) -> Self {
         Self {
             montgomery_form: div_by_2(&self.montgomery_form, &self.params.modulus),
             params: self.params,
@@ -219,6 +215,10 @@ impl<const LIMBS: usize> Monty for MontyForm<LIMBS> {
     fn one(params: Self::Params) -> Self {
         MontyForm::one(params)
     }
+
+    fn div_by_2(&self) -> Self {
+        MontyForm::div_by_2(self)
+    }
 }
 
 impl<const LIMBS: usize, P: ConstMontyParams<LIMBS>> From<&ConstMontyForm<P, LIMBS>>

src/traits.rs

@@ -563,4 +563,7 @@ pub trait Monty:
 
     /// Returns one in this representation.
     fn one(params: Self::Params) -> Self;
+
+    /// Performs division by 2, that is returns `x` such that `x + x = self`.
+    fn div_by_2(&self) -> Self;
 }