3.2.1, 3.2.4, 3.2.5. Documentation and tests

crypto/dalek-ff-group/src/field.rs

@@ -13,30 +13,69 @@ use ff::{Field, PrimeField, FieldBits, PrimeFieldBits};
 
 use crate::{constant_time, math, from_uint};
 
-const MODULUS: U256 =
+// 2^255 - 19
-  U256::from_be_hex("7fffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffed");
+// Uses saturating_sub because checked_sub isn't available at compile time
-
+const MODULUS: U256 = U256::from_u8(1).shl_vartime(255).saturating_sub(&U256::from_u8(19));
-const WIDE_MODULUS: U512 = U512::from_be_hex(concat!(
+const WIDE_MODULUS: U512 = U256::ZERO.concat(&MODULUS);
-  "0000000000000000000000000000000000000000000000000000000000000000",
-  "7fffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffed"
-));
 
 #[derive(Clone, Copy, PartialEq, Eq, Default, Debug)]
 pub struct FieldElement(U256);
 
-pub const MOD_3_8: FieldElement =
+/*
-  FieldElement(MODULUS.saturating_add(&U256::from_u8(3)).wrapping_div(&U256::from_u8(8)));
+The following is a valid const definition of sqrt(-1) yet exceeds the const_eval_limit by 24x.
+Accordingly, it'd only be usable on a nightly compiler with the following crate attributes:
+#![feature(const_eval_limit)]
+#![const_eval_limit = "24000000"]
 
-pub const MOD_5_8: FieldElement = FieldElement(MOD_3_8.0.saturating_sub(&U256::ONE));
+const SQRT_M1: FieldElement = {
+  // Formula from RFC-8032 (modp_sqrt_m1/sqrt8k5 z)
+  // 2 ** ((MODULUS - 1) // 4) % MODULUS
+  let base = U256::from_u8(2);
+  let exp = MODULUS.saturating_sub(&U256::from_u8(1)).wrapping_div(&U256::from_u8(4));
 
-pub const EDWARDS_D: FieldElement = FieldElement(U256::from_be_hex(
+  const fn mul(x: U256, y: U256) -> U256 {
-  "52036cee2b6ffe738cc740797779e89800700a4d4141d8ab75eb4dca135978a3",
+    let wide = U256::mul_wide(&x, &y);
-));
+    let wide = U256::concat(&wide.1, &wide.0);
+    wide.wrapping_rem(&WIDE_MODULUS).split().1
+  }
 
-pub const SQRT_M1: FieldElement = FieldElement(U256::from_be_hex(
+  // Perform the pow via multiply and square
+  let mut res = U256::ONE;
+  // Iterate from highest bit to lowest bit
+  let mut bit = 255;
+  loop {
+    if bit != 255 {
+      res = mul(res, res);
+    }
+
+    // Reverse from little endian to big endian
+    if exp.bit_vartime(bit) == 1 {
+      res = mul(res, base);
+    }
+
+    if bit == 0 {
+      break;
+    }
+    bit -= 1;
+  }
+
+  FieldElement(res)
+};
+*/
+
+// Use a constant since we can't calculate it at compile-time without a nightly compiler
+// Even without const_eval_limit, it'd take ~30s to calculate, which isn't worth it
+const SQRT_M1: FieldElement = FieldElement(U256::from_be_hex(
   "2b8324804fc1df0b2b4d00993dfbd7a72f431806ad2fe478c4ee1b274a0ea0b0",
 ));
 
+// Constant useful in calculating square roots (RFC-8032 sqrt8k5's exponent used to calculate y)
+const MOD_3_8: FieldElement =
+  FieldElement(MODULUS.saturating_add(&U256::from_u8(3)).wrapping_div(&U256::from_u8(8)));
+
+// Constant useful in sqrt_ratio_i (sqrt(u / v))
+const MOD_5_8: FieldElement = FieldElement(MOD_3_8.0.saturating_sub(&U256::ONE));
+
 fn reduce(x: U512) -> U256 {
   U256::from_le_slice(&x.reduce(&WIDE_MODULUS).unwrap().to_le_bytes()[.. 32])
 }
@@ -93,6 +132,7 @@ impl Field for FieldElement {
     CtOption::new(self.pow(NEG_2), !self.is_zero())
   }
 
+  // RFC-8032 sqrt8k5
   fn sqrt(&self) -> CtOption<Self> {
     let tv1 = self.pow(MOD_3_8);
     let tv2 = tv1 * SQRT_M1;
@@ -113,14 +153,20 @@ impl PrimeField for FieldElement {
     self.0.to_le_bytes()
   }
 
+  // This was set per the specification in the ff crate docs
+  // The number of leading zero bits in the little-endian bit representation of (modulus - 1)
   const S: u32 = 2;
   fn is_odd(&self) -> Choice {
     self.0.is_odd()
   }
   fn multiplicative_generator() -> Self {
+    // This was calculated with the method from the ff crate docs
+    // SageMath GF(modulus).primitive_element()
     2u64.into()
   }
   fn root_of_unity() -> Self {
+    // This was calculated via the formula from the ff crate docs
+    // Self::multiplicative_generator() ** ((modulus - 1) >> Self::S)
     FieldElement(U256::from_be_hex(
       "2b8324804fc1df0b2b4d00993dfbd7a72f431806ad2fe478c4ee1b274a0ea0b0",
     ))
@@ -172,27 +218,67 @@ impl FieldElement {
     res
   }
 
+  /// The square root of u/v, as used for Ed25519 point decoding (RFC 8032 5.1.3) and within
+  /// Ristretto (5.1 Extracting an Inverse Square Root).
+  ///
+  /// The result is only a valid square root if the Choice is true.
+  /// RFC 8032 simply fails if there isn't a square root, leaving any return value undefined.
+  /// Ristretto explicitly returns 0 or sqrt((SQRT_M1 * u) / v).
   pub fn sqrt_ratio_i(u: FieldElement, v: FieldElement) -> (Choice, FieldElement) {
     let i = SQRT_M1;
 
     let v3 = v.square() * v;
     let v7 = v3.square() * v;
+    // Candidate root
     let mut r = (u * v3) * (u * v7).pow(MOD_5_8);
 
+    // 8032 3.1
     let check = v * r.square();
     let correct_sign = check.ct_eq(&u);
-    let flipped_sign = check.ct_eq(&(-u));
+    // 8032 3.2 conditional
-    let flipped_sign_i = check.ct_eq(&((-u) * i));
+    let neg_u = -u;
+    let flipped_sign = check.ct_eq(&neg_u);
+    // Ristretto Step 5
+    let flipped_sign_i = check.ct_eq(&(neg_u * i));
 
+    // 3.2 set
     r.conditional_assign(&(r * i), flipped_sign | flipped_sign_i);
 
-    let r_is_negative = r.is_odd();
+    // Always return the even root, per Ristretto
-    r.conditional_negate(r_is_negative);
+    // This doesn't break Ed25519 point decoding as that doesn't expect these steps to return a
+    // specific root
+    // Ed25519 points include a dedicated sign bit to determine which root to use, so at worst
+    // this is a pointless inefficiency
+    r.conditional_negate(r.is_odd());
 
     (correct_sign | flipped_sign, r)
   }
 }
 
+#[test]
+fn test_wide_modulus() {
+  let mut wide = [0; 64];
+  wide[.. 32].copy_from_slice(&MODULUS.to_le_bytes());
+  assert_eq!(wide, WIDE_MODULUS.to_le_bytes());
+}
+
+#[test]
+fn test_sqrt_m1() {
+  // Test equivalence against the known constant value
+  const SQRT_M1_MAGIC: U256 =
+    U256::from_be_hex("2b8324804fc1df0b2b4d00993dfbd7a72f431806ad2fe478c4ee1b274a0ea0b0");
+  assert_eq!(SQRT_M1.0, SQRT_M1_MAGIC);
+
+  // Also test equivalence against the result of the formula from RFC-8032 (modp_sqrt_m1/sqrt8k5 z)
+  // 2 ** ((MODULUS - 1) // 4) % MODULUS
+  assert_eq!(
+    SQRT_M1,
+    FieldElement::from(2u8).pow(FieldElement(
+      (FieldElement::zero() - FieldElement::one()).0.wrapping_div(&U256::from(4u8))
+    ))
+  );
+}
+
 #[test]
 fn test_field() {
   ff_group_tests::prime_field::test_prime_field_bits::<FieldElement>();

crypto/dalek-ff-group/src/lib.rs

@@ -177,6 +177,7 @@ constant_time!(Scalar, DScalar);
 math_neg!(Scalar, Scalar, DScalar::add, DScalar::sub, DScalar::mul);
 from_uint!(Scalar, DScalar);
 
+// Ed25519 order/scalar modulus
 const MODULUS: U256 =
   U256::from_be_hex("1000000000000000000000000000000014def9dea2f79cd65812631a5cf5d3ed");
 
@@ -272,19 +273,25 @@ impl PrimeField for Scalar {
     self.0.to_bytes()
   }
 
+  // This was set per the specification in the ff crate docs
+  // The number of leading zero bits in the little-endian bit representation of (modulus - 1)
   const S: u32 = 2;
   fn is_odd(&self) -> Choice {
     choice(self.to_le_bits()[0])
   }
   fn multiplicative_generator() -> Self {
+    // This was calculated with the method from the ff crate docs
+    // SageMath GF(modulus).primitive_element()
     2u64.into()
   }
   fn root_of_unity() -> Self {
-    const ROOT: [u8; 32] = [
+    // This was calculated via the formula from the ff crate docs
+    // Self::multiplicative_generator() ** ((modulus - 1) >> Self::S)
+    Scalar::from_repr([
       212, 7, 190, 235, 223, 117, 135, 190, 254, 131, 206, 66, 83, 86, 240, 14, 122, 194, 193, 171,
       96, 109, 61, 125, 231, 129, 121, 224, 16, 115, 74, 9,
-    ];
+    ])
-    Scalar::from_repr(ROOT).unwrap()
+    .unwrap()
   }
 }
 
@@ -433,6 +440,11 @@ dalek_group!(
   RISTRETTO_BASEPOINT_TABLE
 );
 
+#[test]
+fn test_scalar_modulus() {
+  assert_eq!(MODULUS.to_le_bytes(), curve25519_dalek::constants::BASEPOINT_ORDER.to_bytes());
+}
+
 #[test]
 fn test_ed25519_group() {
   ff_group_tests::group::test_prime_group_bits::<EdwardsPoint>();