[WIP] primefield: generic MontyFieldElement type

The previous implementation was written entirely in terms of macros.

Leveraging types from `crypto-bigint`, this provides a generic field
element type with an internal Montgomery form representation.

Author: tarcieri

p256/src/arithmetic/field.rs

@@ -11,6 +11,7 @@ use core::ops::Mul;
 use elliptic_curve::{
     FieldBytesEncoding,
     bigint::U256,
+    consts::U32,
     ff::PrimeField,
     subtle::{Choice, ConstantTimeEq, CtOption},
 };
@@ -26,6 +27,19 @@ const R2: FieldElement = FieldElement(U256::from_be_hex(
     "00000004fffffffdfffffffffffffffefffffffbffffffff0000000000000003",
 ));
 
+primefield::monty_field_params!(
+    MontyFieldParams,
+    MODULUS_HEX,
+    U256,
+    U32,
+    primefield::ByteOrder::BigEndian,
+    "P-256 field modulus"
+);
+
+/// An element in the finite field modulo p = 2^{224}(2^{32} − 1) + 2^{192} + 2^{96} − 1.
+#[allow(dead_code)]
+pub type MontyFieldElement = primefield::MontyFieldElement<MontyFieldParams, { U256::LIMBS }>;
+
 /// An element in the finite field modulo p = 2^{224}(2^{32} − 1) + 2^{192} + 2^{96} − 1.
 ///
 /// The internal representation is in little-endian order. Elements are always in

p256/src/arithmetic/scalar.rs

@@ -14,6 +14,7 @@ use core::{
 use elliptic_curve::{
     Curve,
     bigint::{Limb, U256, prelude::*},
+    consts::U32,
     group::ff::{self, Field, PrimeField},
     ops::{Invert, Reduce, ReduceNonZero},
     rand_core::TryRngCore,
@@ -41,6 +42,19 @@ pub(crate) const MODULUS: U256 = NistP256::ORDER;
 /// `MODULUS / 2`
 const FRAC_MODULUS_2: Scalar = Scalar(MODULUS.shr_vartime(1));
 
+primefield::monty_field_params!(
+    MontyScalarParams,
+    ORDER_HEX,
+    U256,
+    U32,
+    primefield::ByteOrder::BigEndian,
+    "P-256 scalar modulus"
+);
+
+/// Scalars are elements in the finite field modulo n.
+#[allow(dead_code)]
+pub type MontyScalar = primefield::MontyFieldElement<MontyScalarParams, { U256::LIMBS }>;
+
 /// Scalars are elements in the finite field modulo n.
 ///
 /// # Trait impls

primefield/Cargo.toml

@@ -14,7 +14,7 @@ edition = "2024"
 rust-version = "1.85"
 
 [dependencies]
-bigint = { package = "crypto-bigint", version = "=0.7.0-pre.7", default-features = false }
+bigint = { package = "crypto-bigint", version = "=0.7.0-pre.7", default-features = false, features = ["hybrid-array"] }
 ff = { version = "=0.14.0-pre.0", default-features = false }
 subtle = { version = "2.6", default-features = false }
 rand_core = { version = "0.9", default-features = false }

primefield/src/lib.rs

@@ -8,13 +8,28 @@
 #![warn(missing_docs, rust_2018_idioms, unused_qualifications)]
 #![doc = include_str!("../README.md")]
 
+pub use array::typenum::consts;
 pub use bigint;
+pub use bigint::hybrid_array as array;
 pub use ff;
 pub use rand_core;
 pub use subtle;
 pub use zeroize;
 
+pub use crate::monty::{MontyFieldElement, MontyFieldParams};
+
 mod fiat;
+mod monty;
+
+/// Byte order used when encoding/decoding field elements as bytestrings.
+#[derive(Debug)]
+pub enum ByteOrder {
+    /// Big endian.
+    BigEndian,
+
+    /// Little endian.
+    LittleEndian,
+}
 
 /// Implements a field element type whose internal representation is in
 /// Montgomery form, providing a combination of trait impls and inherent impls

primefield/src/monty.rs

@@ -0,0 +1,187 @@
+//! Field elements which use an internal Montgomery form representation, implemented using
+//! `crypto-bigint`'s [`MontyForm`].
+
+use crate::ByteOrder;
+use bigint::{
+    ArrayEncoding, ByteArray, Uint,
+    hybrid_array::{Array, ArraySize, typenum::Unsigned},
+    modular::{ConstMontyForm as MontyForm, ConstMontyParams},
+};
+use subtle::{ConstantTimeLess, CtOption};
+
+/// Creates a ZST representing the Montgomery parameters for a given field modulus.
+///
+/// Accepts the following parameters:
+///
+/// - name of the ZST representing the field modulus
+/// - hex serialization of the modulus
+/// - `crypto-bigint` unsigned integer type (e.g. U256)
+/// - number of bytes in an encoded field element
+/// - byte order to use when encoding/decoding field elements
+/// - documentation string for the field modulus type
+///
+/// ```
+/// use primefield::{ByteOrder, bigint::U256, consts::U32};
+///
+/// primefield::monty_field_params!(
+///     FieldParams,
+///     "ffffffff00000001000000000000000000000000ffffffffffffffffffffffff",
+///     U256,
+///     U32,
+///     ByteOrder::BigEndian,
+///     "P-256 field modulus"
+/// );
+/// ```
+#[macro_export]
+macro_rules! monty_field_params {
+    ($name:ident, $modulus_hex:expr, $uint_type:ty, $byte_size:ty, $byte_order:expr, $doc:expr) => {
+        $crate::bigint::const_monty_params!($name, $uint_type, $modulus_hex, $doc);
+
+        impl $crate::MontyFieldParams<{ <$uint_type>::LIMBS }> for $name {
+            type ByteSize = $byte_size;
+            const BYTE_ORDER: $crate::ByteOrder = $byte_order;
+        }
+    };
+}
+
+/// Extension trait for defining additional field parameters beyond the ones provided by
+/// [`ConstMontyParams`].
+pub trait MontyFieldParams<const LIMBS: usize>: ConstMontyParams<LIMBS> {
+    /// Size of a field element when serialized as bytes.
+    type ByteSize: ArraySize;
+
+    /// Byte order to use when serializing a field element as byte.
+    const BYTE_ORDER: ByteOrder;
+}
+
+/// Field element type which uses an internal Montgomery form representation.
+#[derive(Clone, Copy)]
+pub struct MontyFieldElement<MOD: MontyFieldParams<LIMBS>, const LIMBS: usize>(
+    MontyForm<MOD, LIMBS>,
+);
+
+impl<MOD: MontyFieldParams<LIMBS>, const LIMBS: usize> MontyFieldElement<MOD, LIMBS> {
+    /// Zero element (additive identity).
+    pub const ZERO: Self = Self(MontyForm::ZERO);
+
+    /// Multiplicative identity.
+    pub const ONE: Self = Self(MontyForm::ONE);
+
+    /// Number of limbs used by the internal integer representation.
+    pub const LIMBS: usize = LIMBS;
+
+    /// Decode field element from a canonical bytestring representation.
+    #[inline]
+    pub fn from_bytes(repr: &Array<u8, MOD::ByteSize>) -> CtOption<Self>
+    where
+        Uint<LIMBS>: ArrayEncoding,
+    {
+        debug_assert!(repr.len() <= MOD::ByteSize::USIZE);
+        let mut byte_array = ByteArray::<Uint<LIMBS>>::default();
+        let offset = MOD::ByteSize::USIZE.saturating_sub(repr.len());
+
+        let uint = match MOD::BYTE_ORDER {
+            ByteOrder::BigEndian => {
+                byte_array[offset..].copy_from_slice(repr);
+                Uint::from_be_byte_array(byte_array)
+            }
+            ByteOrder::LittleEndian => {
+                byte_array[..offset].copy_from_slice(repr);
+                Uint::from_le_byte_array(byte_array)
+            }
+        };
+
+        Self::from_uint(&uint)
+    }
+
+    /// Decode field element from a canonical byte slice.
+    ///
+    /// Slice is expected to be zero padded to the expected byte size.
+    #[inline]
+    pub fn from_slice(slice: &[u8]) -> Option<Self>
+    where
+        Uint<LIMBS>: ArrayEncoding,
+    {
+        let array = Array::try_from(slice).ok()?;
+        Self::from_bytes(&array).into()
+    }
+
+    /// Decode a field element from hex-encoded bytes.
+    ///
+    /// Does *not* perform a check that the field element does not overflow the order.
+    ///
+    /// This method is primarily intended for defining internal constants.
+    pub const fn from_hex(hex: &str) -> Self {
+        let uint = match MOD::BYTE_ORDER {
+            ByteOrder::BigEndian => Uint::from_be_hex(hex),
+            ByteOrder::LittleEndian => Uint::from_le_hex(hex),
+        };
+
+        // TODO(tarcieri): ensure value does not overflow the modulus (RustCrypto/crypto-bigint#881)
+        // if uint.lt(MOD::PARAMS.modulus().as_ref()).is_false_vartime() {
+        //     panic!("hex encoded field element overflows modulus");
+        // }
+
+        Self::from_uint_unchecked(&uint)
+    }
+
+    /// Convert [`Uint`] into [`MontyFieldElement`], first converting it into Montgomery form:
+    ///
+    /// ```text
+    /// w * R^2 * R^-1 mod p = wR mod p
+    /// ```
+    ///
+    /// Does *NOT* ensure that the input value is within range of the modulus!
+    #[inline]
+    pub const fn from_uint_unchecked(uint: &Uint<LIMBS>) -> Self {
+        Self(MontyForm::new(uint))
+    }
+
+    /// Convert [`Uint`] into [`MontyFieldElement`], first converting it into Montgomery form:
+    ///
+    /// ```text
+    /// w * R^2 * R^-1 mod p = wR mod p
+    /// ```
+    #[inline]
+    pub fn from_uint(uint: &Uint<LIMBS>) -> CtOption<Self> {
+        let is_some = uint.ct_lt(MOD::PARAMS.modulus());
+        CtOption::new(Self::from_uint_unchecked(uint), is_some)
+    }
+
+    /// Convert a `u64` into a [`MontyFieldElement`].
+    ///
+    /// Does *NOT* ensure that the modulus is greater than 64-bits!
+    #[inline]
+    pub const fn from_u64(w: u64) -> Self {
+        if MOD::PARAMS.modulus().as_ref().bits() <= 64 {
+            panic!("modulus is too small to ensure all u64s are in range");
+        }
+
+        Self::from_uint_unchecked(&Uint::from_u64(w))
+    }
+
+    /// Returns the bytestring encoding of this field element.
+    #[inline]
+    pub fn to_bytes(self) -> Array<u8, MOD::ByteSize>
+    where
+        Uint<LIMBS>: ArrayEncoding,
+    {
+        let mut repr = Array::<u8, MOD::ByteSize>::default();
+        debug_assert!(repr.len() <= MOD::ByteSize::USIZE);
+
+        let offset = MOD::ByteSize::USIZE.saturating_sub(repr.len());
+
+        match MOD::BYTE_ORDER {
+            ByteOrder::BigEndian => {
+                let padded = self.0.retrieve().to_be_byte_array();
+                repr.copy_from_slice(&padded[offset..]);
+            }
+            ByteOrder::LittleEndian => {
+                let padded = self.0.retrieve().to_le_byte_array();
+                repr.copy_from_slice(&padded[..offset]);
+            }
+        }
+
+        repr
+    }
+}