clock_curve_math/extensible/
field_parameters.rs

1//! Field parameters and operation definitions for extensible arithmetic.
2//!
3//! This module defines the traits and types needed to specify field
4//! parameters for different cryptographic curves and arithmetic systems.
5
6use crate::bigint::BigInt;
7
8/// Generic field parameters for extensible arithmetic.
9///
10/// This trait defines the mathematical parameters needed for field arithmetic
11/// with different moduli and limb configurations. It provides the essential
12/// constants and metadata required for finite field operations.
13pub trait FieldParameters {
14    /// Returns the prime modulus that defines this finite field.
15    ///
16    /// This is the prime number p such that all field elements are in ℤ/pℤ.
17    /// The modulus determines the size and properties of the field.
18    ///
19    /// # Returns
20    /// The field modulus as a BigInt
21    fn modulus() -> BigInt;
22
23    /// Returns the number of 64-bit limbs needed to represent field elements.
24    ///
25    /// Field elements are stored as multi-precision integers using a fixed number
26    /// of 64-bit limbs. This determines the memory layout and affects performance
27    /// characteristics of arithmetic operations.
28    ///
29    /// # Returns
30    /// The number of limbs required for field element representation
31    fn limb_count() -> usize;
32
33    /// Returns the Montgomery radix R = 2^(limb_count * 64).
34    ///
35    /// In Montgomery arithmetic, R is a power of 2 larger than the modulus,
36    /// chosen so that R and the modulus are coprime. This constant is used
37    /// in Montgomery multiplication and reduction algorithms.
38    ///
39    /// # Returns
40    /// The Montgomery radix R as a BigInt
41    fn montgomery_r() -> BigInt;
42
43    /// Returns R² mod modulus, the Montgomery multiplication constant.
44    ///
45    /// This precomputed constant is used to convert regular integers to
46    /// Montgomery form. To convert a value x to Montgomery form, compute
47    /// x * R² mod modulus. This constant enables efficient Montgomery arithmetic.
48    ///
49    /// # Returns
50    /// The Montgomery R² constant as a BigInt
51    fn montgomery_r2() -> BigInt;
52
53    /// Returns the Montgomery inverse N' = -modulus⁻¹ mod R.
54    ///
55    /// This constant is the modular inverse of the modulus with respect to R,
56    /// negated and reduced modulo R. It's used in the Montgomery reduction
57    /// algorithm to efficiently compute (x * R⁻¹) mod modulus.
58    ///
59    /// # Returns
60    /// The Montgomery inverse constant N' as a BigInt
61    fn montgomery_n_prime() -> BigInt;
62
63    /// Check if this field supports a given operation
64    fn supports_operation(&self, operation: FieldOperation) -> bool {
65        // Default implementation - all operations supported
66        let _ = operation;
67        true
68    }
69}
70
71/// Operations that may or may not be supported by different field implementations.
72///
73/// This enum defines the various mathematical operations that field implementations
74/// can support. Some operations may not be available for certain moduli (e.g.,
75/// square root may not exist for all elements in some fields), while others
76/// may be computationally expensive or have specialized implementations.
77#[derive(Clone, Copy, Debug, PartialEq, Eq)]
78pub enum FieldOperation {
79    /// Basic arithmetic operations: addition, subtraction, and multiplication.
80    ///
81    /// These are the fundamental operations that all field implementations
82    /// should support. They include modular addition, subtraction, and
83    /// multiplication with proper reduction modulo the field prime.
84    BasicArithmetic,
85
86    /// Modular inversion: finding x such that (a * x) ≡ 1 mod p.
87    ///
88    /// Not all elements have multiplicative inverses (specifically, zero does not).
89    /// This operation typically uses the extended Euclidean algorithm.
90    Inversion,
91
92    /// Square root computation in the field.
93    ///
94    /// Computes x such that x² ≡ a mod p. This may not exist for all elements
95    /// depending on the field properties (Tonelli-Shanks algorithm is commonly used).
96    SquareRoot,
97
98    /// Batch operations: performing the same operation on multiple field elements.
99    ///
100    /// This enables optimizations like Montgomery batch processing or SIMD operations
101    /// when multiple field elements need the same operation applied.
102    BatchOperations,
103
104    /// Multi-exponentiation: computing ∑ bᵢ * xᵢ^yᵢ for multiple bases and exponents.
105    ///
106    /// This is a fundamental operation in cryptographic protocols and pairing-based
107    /// cryptography. Efficient implementations use techniques like the Pippenger algorithm.
108    MultiExponentiation,
109
110    /// Legendre symbol computation: determining if an element is a quadratic residue.
111    ///
112    /// Computes the Legendre symbol (a/p) which indicates whether a has a square
113    /// root modulo p. Returns 1 (quadratic residue), -1 (non-residue), or 0 (zero).
114    LegendreSymbol,
115}
clock_curve_math/extensible/field_parameters.rs

clock_curve_math/extensible/
field_parameters.rs
