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;
// Required methods
fn random(rng: impl RngCore) -> Self;
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 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 random(rng: impl RngCore) -> Self
fn random(rng: impl RngCore) -> Self
Returns an element chosen uniformly at random using a user-provided RNG.
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
sqrt
is unspecified. - The value of $G_S$ is unspecified, and cannot be assumed to have any specific value in a generic context.
Provided Methods§
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.
Object Safety§
Implementations on Foreign Types§
§impl Field for Fp
impl Field for Fp
§fn invert(&self) -> CtOption<Fp>
fn invert(&self) -> CtOption<Fp>
Computes the multiplicative inverse of this element, failing if the element is zero.
const ZERO: Fp = _
const ONE: Fp = _
fn random(rng: impl RngCore) -> Fp
fn double(&self) -> Fp
fn square(&self) -> Fp
fn sqrt_ratio(num: &Fp, div: &Fp) -> (Choice, Fp)
fn sqrt_alt(&self) -> (Choice, Fp)
fn pow_vartime<S>(&self, exp: S) -> Fp
§impl Field for Fq
impl Field for Fq
§fn invert(&self) -> CtOption<Fq>
fn invert(&self) -> CtOption<Fq>
Computes the multiplicative inverse of this element, failing if the element is zero.