Trait Field
pub trait Field:
Sized
+ Eq
+ Copy
+ Clone
+ Default
+ Send
+ Sync
+ Debug
+ 'static
+ ConditionallySelectable
+ ConstantTimeEq
+ Neg<Output = Self>
+ Add<Output = Self, Output = Self>
+ Sub<Output = Self, Output = Self>
+ Mul<Output = Self, Output = Self>
+ Sum
+ Product
+ for<'a> Add<&'a Self>
+ for<'a> Sub<&'a Self>
+ for<'a> Mul<&'a Self>
+ for<'a> Sum<&'a Self>
+ for<'a> Product<&'a Self>
+ AddAssign
+ SubAssign
+ MulAssign
+ for<'a> AddAssign<&'a Self>
+ for<'a> SubAssign<&'a Self>
+ for<'a> MulAssign<&'a Self> {
const ZERO: Self;
const ONE: Self;
Show 13 methods
// Required methods
fn try_random<R>(rng: &mut R) -> Result<Self, <R as TryRng>::Error>
where R: TryRng + ?Sized;
fn square(&self) -> Self;
fn double(&self) -> Self;
fn invert(&self) -> CtOption<Self>;
fn sqrt_ratio(num: &Self, div: &Self) -> (Choice, Self);
// Provided methods
fn random<R>(rng: &mut R) -> Self
where R: Rng + ?Sized { ... }
fn is_zero(&self) -> Choice { ... }
fn is_zero_vartime(&self) -> bool { ... }
fn cube(&self) -> Self { ... }
fn sqrt_alt(&self) -> (Choice, Self) { ... }
fn sqrt(&self) -> CtOption<Self> { ... }
fn pow<S>(&self, exp: S) -> Self
where S: AsRef<[u64]> { ... }
fn pow_vartime<S>(&self, exp: S) -> Self
where S: AsRef<[u64]> { ... }
}Expand description
This trait represents an element of a field.
Required Associated Constants§
const ZERO: Self
const ZERO: Self
The zero element of the field, the additive identity.
const ONE: Self
const ONE: Self
The one element of the field, the multiplicative identity.
Required Methods§
fn try_random<R>(rng: &mut R) -> Result<Self, <R as TryRng>::Error>where
R: TryRng + ?Sized,
fn try_random<R>(rng: &mut R) -> Result<Self, <R as TryRng>::Error>where
R: TryRng + ?Sized,
Returns an element chosen uniformly at random using a user-provided fallible RNG.
Returns Err propagating the RNG’s error if the underlying RNG fails to produce
the randomness required to sample an element. Implementors of Field must
provide this method; Field::random is derived from it for infallible RNGs.
fn square(&self) -> Self
fn square(&self) -> Self
Squares this element.
fn double(&self) -> Self
fn double(&self) -> Self
Doubles this element.
fn invert(&self) -> CtOption<Self>
fn invert(&self) -> CtOption<Self>
Computes the multiplicative inverse of this element, failing if the element is zero.
fn sqrt_ratio(num: &Self, div: &Self) -> (Choice, Self)
fn sqrt_ratio(num: &Self, div: &Self) -> (Choice, Self)
Computes:
- $(\textsf{true}, \sqrt{\textsf{num}/\textsf{div}})$, if $\textsf{num}$ and $\textsf{div}$ are nonzero and $\textsf{num}/\textsf{div}$ is a square in the field;
- $(\textsf{true}, 0)$, if $\textsf{num}$ is zero;
- $(\textsf{false}, 0)$, if $\textsf{num}$ is nonzero and $\textsf{div}$ is zero;
- $(\textsf{false}, \sqrt{G_S \cdot \textsf{num}/\textsf{div}})$, if $\textsf{num}$ and $\textsf{div}$ are nonzero and $\textsf{num}/\textsf{div}$ is a nonsquare in the field;
where $G_S$ is a non-square.
§Warnings
- The choice of root from
sqrtis unspecified. - The value of $G_S$ is unspecified, and cannot be assumed to have any specific value in a generic context.
Provided Methods§
fn random<R>(rng: &mut R) -> Selfwhere
R: Rng + ?Sized,
fn random<R>(rng: &mut R) -> Selfwhere
R: Rng + ?Sized,
Returns an element chosen uniformly at random using a user-provided infallible RNG.
This is a convenience wrapper around Field::try_random for RNGs that cannot
fail. Use Field::try_random if your RNG may fail (for example, an OS-backed
entropy source).
fn is_zero_vartime(&self) -> bool
fn is_zero_vartime(&self) -> bool
Returns true iff this element is zero.
§Security
This method provides no constant-time guarantees. Implementors of the
Field trait may optimise this method using non-constant-time logic.
fn cube(&self) -> Self
fn cube(&self) -> Self
Cubes this element.
fn sqrt_alt(&self) -> (Choice, Self)
fn sqrt_alt(&self) -> (Choice, Self)
Equivalent to Self::sqrt_ratio(self, one()).
The provided method is implemented in terms of Self::sqrt_ratio.
fn sqrt(&self) -> CtOption<Self>
fn sqrt(&self) -> CtOption<Self>
Returns the square root of the field element, if it is quadratic residue.
The provided method is implemented in terms of Self::sqrt_ratio.
fn pow<S>(&self, exp: S) -> Self
fn pow<S>(&self, exp: S) -> Self
Exponentiates self by exp, where exp is a little-endian order integer
exponent.
§Guarantees
This operation is constant time with respect to self, for all exponents with the
same number of digits (exp.as_ref().len()). It is variable time with respect to
the number of digits in the exponent.
fn pow_vartime<S>(&self, exp: S) -> Self
fn pow_vartime<S>(&self, exp: S) -> Self
Exponentiates self by exp, where exp is a little-endian order integer
exponent.
§Guarantees
This operation is variable time with respect to self, for all exponent. If
the exponent is fixed, this operation is effectively constant time. However, for
stronger constant-time guarantees, Field::pow should be used.
Dyn Compatibility§
This trait is not dyn compatible.
In older versions of Rust, dyn compatibility was called "object safety".
Implementations on Foreign Types§
§impl Field for Scalar
impl Field for Scalar
§fn sqrt(&self) -> CtOption<Scalar>
fn sqrt(&self) -> CtOption<Scalar>
Tonelli-Shank’s algorithm for q mod 16 = 1 https://eprint.iacr.org/2012/685.pdf (page 12, algorithm 5)
const ZERO: Scalar = Self::ZERO
const ONE: Scalar = Self::ONE
fn try_random<R>(rng: &mut R) -> Result<Scalar, <R as TryRng>::Error>where
R: TryRng + ?Sized,
fn square(&self) -> Scalar
fn double(&self) -> Scalar
fn invert(&self) -> CtOption<Scalar>
fn sqrt_ratio(num: &Scalar, div: &Scalar) -> (Choice, Scalar)
§impl Field for Scalar
impl Field for Scalar
§fn invert(&self) -> CtOption<Scalar>
fn invert(&self) -> CtOption<Scalar>
§Security Note
This uses variable-time inversion. See [Scalar::invert()] for details.
§fn sqrt(&self) -> CtOption<Scalar>
fn sqrt(&self) -> CtOption<Scalar>
Square root in the scalar field.
§Security
Variable-time: delegates to the backend’s sqrt (a Tonelli–Shanks
variant) whose control flow depends on the input. Do not call on secret
values where timing is observable.
§fn sqrt_ratio(num: &Scalar, div: &Scalar) -> (Choice, Scalar)
fn sqrt_ratio(num: &Scalar, div: &Scalar) -> (Choice, Scalar)
Compute sqrt(num / div) following the Field::sqrt_ratio contract.
Delegates to ff’s generic implementation, which is built on this
field’s (now correct) ROOT_OF_UNITY and on the overridden sqrt
above (preventing the documented infinite recursion). Returns
(1, sqrt(num/div)) when num/div is a square (and (1, 0) when
num == 0), and (0, sqrt(ROOT_OF_UNITY * num/div)) for a non-square
(or (0, 0) when only div == 0).
The previous implementation was a stub that unconditionally returned
(1, 1), silently claiming every ratio was a square — which breaks any
hash-to-curve / quadratic-residue test built on it.
§Security
Variable-time: the implementation calls sqrt (a Tonelli–Shanks
variant) whose control flow depends on the input, and the Legendre
symbol computation itself can leak whether num/div is a quadratic
residue through timing. For hash-to-curve constructions where the
quadratic-residue decision on a secret input must remain secret,
this method is not appropriate. No constant-time alternative is
provided by this crate.