Struct FieldElement 

pub struct FieldElement(pub(crate) fiat_p521_tight_field_element);

Element of the secp521r1 base field used for curve coordinates.

Tuple Fields

0: fiat_p521_tight_field_element

Implementations

impl FieldElement

pub const ZERO: Self

Zero element.

pub const ONE: Self

Multiplicative identity.

const LIMBS: usize = 9

pub fn from_bytes(repr: &FieldBytes) -> CtOption<Self>

Create a FieldElement from a canonical big-endian representation.

pub fn from_slice(slice: &[u8]) -> Result<Self>

Decode FieldElement from a big endian byte slice.

pub fn from_uint(uint: Uint) -> CtOption<Self>

Decode FieldElement from Uint.

pub(crate) const fn from_hex(hex: &str) -> Self

Parse a FieldElement from big endian hex-encoded bytes.

This method is primarily intended for defining internal constants.

Panics

• if the input in hex is not the correct length
• if the given value when decoded from hex overflows the modulus

pub const fn from_u64(w: u64) -> Self

Convert a u64 into a FieldElement.

pub(crate) const fn from_uint_unchecked(w: Uint) -> Self

Decode FieldElement from Uint.

Does not perform a check that the field element does not overflow the order.

Used incorrectly this can lead to invalid results!

pub const fn to_bytes(self) -> FieldBytes

Returns the big-endian encoding of this FieldElement.

pub fn is_odd(&self) -> Choice

Determine if this FieldElement is odd in the SEC1 sense: self mod 2 == 1.

Returns

If odd, return Choice(1). Otherwise, return Choice(0).

pub fn is_even(&self) -> Choice

Determine if this FieldElement is even in the SEC1 sense: self mod 2 == 0.

Returns

If even, return Choice(1). Otherwise, return Choice(0).

pub fn is_zero(&self) -> Choice

Determine if this FieldElement is zero.

Returns

If zero, return Choice(1). Otherwise, return Choice(0).

pub const fn add_loose(&self, rhs: &Self) -> LooseFieldElement

Add elements.

pub const fn double_loose(&self) -> LooseFieldElement

Double element (add it to itself).

pub const fn sub_loose(&self, rhs: &Self) -> LooseFieldElement

Subtract elements, returning a loose field element.

pub const fn neg_loose(&self) -> LooseFieldElement

Negate element, returning a loose field element.

pub const fn add(&self, rhs: &Self) -> Self

Add two field elements.

pub const fn sub(&self, rhs: &Self) -> Self

Subtract field elements.

pub const fn neg(&self) -> Self

Negate element.

pub const fn double(&self) -> Self

Double element (add it to itself).

pub const fn multiply(&self, rhs: &Self) -> Self

Multiply elements.

pub const fn square(&self) -> Self

Square element.

const fn sqn(&self, n: usize) -> Self

Returns self^(2^n) mod p

pub const fn pow_vartime<const RHS_LIMBS: usize>( &self, exp: &Uint<RHS_LIMBS>, ) -> Self

Returns self^exp, where exp is a little-endian integer exponent.

This operation is variable time with respect to the exponent exp.

If the exponent is fixed, this operation is constant time.

pub const fn sqn_vartime(&self, n: usize) -> Self

Returns self^(2^n) mod p.

This operation is variable time with respect to the exponent n.

If the exponent is fixed, this operation is constant time.

pub fn invert(&self) -> CtOption<Self>

Compute FieldElement inversion: 1 / self.

pub fn invert_vartime(&self) -> CtOption<Self>

Compute FieldElement inversion: 1 / self in variable-time.

const fn invert_unwrap(&self) -> Self

Returns the multiplicative inverse of self.

Panics

Will panic in the event self is zero

pub fn sqrt(&self) -> CtOption<Self>

Returns the square root of self mod p, or None if no square root exists.

Implementation details

If x has a sqrt, then due to Euler’s criterion this implies x^{(p - 1)/2} = 1.

1. x^{(p + 1)/2} = x.
2. There’s a special property due to p ≡ 3 (mod 4) which implies (p + 1)/4 is an integer.
3. We can rewrite 1. as x^((p+1)/4)2
4. x^(p+1)/4 is the square root.
5. This is simplified as (2²⁵¹ - 1 + 1) /4 = 2⁵¹⁹
6. Hence, x²⁵¹⁹ is the square root iff result.square() == self

pub const fn relax(&self) -> LooseFieldElement

Relax a tight field element into a loose one.

pub(crate) const fn to_uint(self) -> Uint

Raise this field element into a canonical integer representative.

Trait Implementations

impl Add<&FieldElement> for &FieldElement

type Output = FieldElement

The resulting type after applying the + operator.

fn add(self, rhs: &FieldElement) -> FieldElement

Performs the + operation.

impl Add<&FieldElement> for FieldElement

type Output = FieldElement

The resulting type after applying the + operator.

fn add(self, rhs: &FieldElement) -> FieldElement

Performs the + operation.

impl Add for FieldElement

type Output = FieldElement

The resulting type after applying the + operator.

fn add(self, rhs: FieldElement) -> FieldElement

Performs the + operation.

impl AddAssign<&FieldElement> for FieldElement

fn add_assign(&mut self, other: &FieldElement)

Performs the += operation.

impl AddAssign for FieldElement

fn add_assign(&mut self, other: FieldElement)

Performs the += operation.

impl AsRef<fiat_p521_tight_field_element> for FieldElement

fn as_ref(&self) -> &fiat_p521_tight_field_element

Converts this type into a shared reference of the (usually inferred) input type.

impl BatchInvert for FieldElement

fn batch_invert_in_place( elements: &mut [Self], scratch_space: &mut [Self], ) -> Self

Inverts each field element in elements (when non-zero). Zero-valued elements are left as zero.

fn batch_invert_in_place_vartime( elements: &mut [Self], scratch_space: &mut [Self], ) -> Self

Variable-time batch inversion.

impl Clone for FieldElement

fn clone(&self) -> FieldElement

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl ConditionallySelectable for FieldElement

fn conditional_select(a: &Self, b: &Self, choice: Choice) -> Self

Select a or b according to choice.

fn conditional_assign(&mut self, other: &Self, choice: Choice)

Conditionally assign other to self, according to choice.

fn conditional_swap(a: &mut Self, b: &mut Self, choice: Choice)

Conditionally swap self and other if choice == 1; otherwise, reassign both unto themselves.

impl ConstantTimeEq for FieldElement

fn ct_eq(&self, other: &Self) -> Choice

Determine if two items are equal.

fn ct_ne(&self, other: &Self) -> Choice

Determine if two items are NOT equal.

impl Debug for FieldElement

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formatting machinery for FieldElement

Why

let fe1 = FieldElement([9, 0, 0, 0, 0, 0, 0, 0, 0]);
let fe2 = FieldElement([
    8,
    0,
    288230376151711744,
    288230376151711743,
    288230376151711743,
    288230376151711743,
    288230376151711743,
    288230376151711743,
    144115188075855871,
]);

For the above example, deriving core::fmt::Debug will result in returning 2 different strings, which are in reality the same due to p521’s unsaturated math, instead print the output as a hex string in big-endian.

This makes debugging easier.

impl Default for FieldElement

fn default() -> Self

Returns the “default value” for a type.

impl Field for FieldElement

const ZERO: Self = Self::ZERO

The zero element of the field, the additive identity.

const ONE: Self = Self::ONE

The one element of the field, the multiplicative identity.

fn try_random<R: TryRng + ?Sized>(rng: &mut R) -> Result<Self, R::Error>

Returns an element chosen uniformly at random using a user-provided fallible RNG.

fn is_zero(&self) -> Choice

Returns true iff this element is zero.

fn square(&self) -> Self

Squares this element.

fn double(&self) -> Self

Doubles this element.

fn invert(&self) -> CtOption<Self>

Computes the multiplicative inverse of this element, failing if the element is zero.

fn sqrt(&self) -> CtOption<Self>

Returns the square root of the field element, if it is quadratic residue.

fn sqrt_ratio(num: &Self, div: &Self) -> (Choice, Self)

Computes:

fn random<R>(rng: &mut R) -> Self

where R: Rng + ?Sized,

Returns an element chosen uniformly at random using a user-provided infallible RNG.

fn is_zero_vartime(&self) -> bool

Returns true iff this element is zero.

fn cube(&self) -> Self

Cubes this element.

fn sqrt_alt(&self) -> (Choice, Self)

Equivalent to Self::sqrt_ratio(self, one()).

fn pow<S>(&self, exp: S) -> Self

where S: AsRef<[u64]>,

Exponentiates self by exp, where exp is a little-endian order integer exponent.

fn pow_vartime<S>(&self, exp: S) -> Self

where S: AsRef<[u64]>,

Exponentiates self by exp, where exp is a little-endian order integer exponent.

impl From<&FieldElement> for LooseFieldElement

fn from(tight: &FieldElement) -> LooseFieldElement

Converts to this type from the input type.

impl From<&LooseFieldElement> for FieldElement

fn from(loose: &LooseFieldElement) -> FieldElement

Converts to this type from the input type.

impl From<FieldElement> for LooseFieldElement

fn from(tight: FieldElement) -> LooseFieldElement

Converts to this type from the input type.

impl From<LooseFieldElement> for FieldElement

fn from(loose: LooseFieldElement) -> FieldElement

Converts to this type from the input type.

impl From<u128> for FieldElement

fn from(n: u128) -> FieldElement

Converts to this type from the input type.

impl From<u32> for FieldElement

fn from(n: u32) -> FieldElement

Converts to this type from the input type.

impl From<u64> for FieldElement

fn from(n: u64) -> FieldElement

Converts to this type from the input type.

impl Generate for FieldElement

fn try_generate_from_rng<R: TryRng + ?Sized>( rng: &mut R, ) -> Result<Self, R::Error>

Generate random key using the provided TryCryptoRng.

fn generate_from_rng<R>(rng: &mut R) -> Self

where R: CryptoRng + ?Sized,

Generate random key using the provided CryptoRng.

fn try_generate() -> Result<Self, Error>

Randomly generate a value of this type using the system’s ambient cryptographically secure random number generator.

fn generate() -> Self

Randomly generate a value of this type using the system’s ambient cryptographically secure random number generator.

impl Invert for FieldElement

type Output = CtOption<FieldElement>

Output of the inversion.

fn invert(&self) -> CtOption<Self>

Computes the inverse.

fn invert_vartime(&self) -> CtOption<Self>

Computes the inverse in variable-time.

impl Mul<&FieldElement> for &FieldElement

type Output = FieldElement

The resulting type after applying the * operator.

fn mul(self, rhs: &FieldElement) -> FieldElement

Performs the * operation.

impl Mul<&FieldElement> for FieldElement

type Output = FieldElement

The resulting type after applying the * operator.

fn mul(self, rhs: &FieldElement) -> FieldElement

Performs the * operation.

impl Mul for FieldElement

type Output = FieldElement

The resulting type after applying the * operator.

fn mul(self, rhs: FieldElement) -> FieldElement

Performs the * operation.

impl MulAssign<&FieldElement> for FieldElement

fn mul_assign(&mut self, other: &FieldElement)

Performs the *= operation.

impl MulAssign for FieldElement

fn mul_assign(&mut self, other: FieldElement)

Performs the *= operation.

impl Neg for FieldElement

type Output = FieldElement

The resulting type after applying the - operator.

fn neg(self) -> FieldElement

Performs the unary - operation.

impl PartialEq for FieldElement

fn eq(&self, rhs: &Self) -> bool

Tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Rhs) -> bool

Tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl PrimeField for FieldElement

const MODULUS: &'static str = MODULUS_HEX

Modulus of the field written as a string for debugging purposes.

const NUM_BITS: u32 = 521

How many bits are needed to represent an element of this field.

const CAPACITY: u32 = 520

How many bits of information can be reliably stored in the field element.

const TWO_INV: Self

Inverse of $2$ in the field.

const MULTIPLICATIVE_GENERATOR: Self

A fixed multiplicative generator of modulus - 1 order. This element must also be a quadratic nonresidue.

const S: u32 = 1

An integer s satisfying the equation 2^s * t = modulus - 1 with t odd.

const ROOT_OF_UNITY: Self

The 2^s root of unity.

const ROOT_OF_UNITY_INV: Self

Inverse of Self::ROOT_OF_UNITY.

const DELTA: Self

Generator of the t-order multiplicative subgroup.

type Repr = Array<u8, <NistP521 as Curve>::FieldBytesSize>

The prime field can be converted back and forth into this binary representation.

fn from_repr(bytes: FieldBytes) -> CtOption<Self>

Attempts to convert a byte representation of a field element into an element of this prime field, failing if the input is not canonical (is not smaller than the field’s modulus).

fn to_repr(&self) -> FieldBytes

Converts an element of the prime field into the standard byte representation for this field.

fn is_odd(&self) -> Choice

Returns true iff this element is odd.

fn from_str_vartime(s: &str) -> Option<Self>

Interpret a string of numbers as a (congruent) prime field element. Does not accept unnecessary leading zeroes or a blank string.

fn from_u128(v: u128) -> Self

Obtains a field element congruent to the integer v.

fn from_repr_vartime(repr: Self::Repr) -> Option<Self>

Attempts to convert a byte representation of a field element into an element of this prime field, failing if the input is not canonical (is not smaller than the field’s modulus).

fn is_even(&self) -> Choice

Returns true iff this element is even.

impl PrimeFieldExt for FieldElement

const REPR_ENDIANNESS: ByteOrder = ByteOrder::BigEndian

Endianness used when encoding ff::PrimeField::Repr.

fn to_be_repr(&self) -> Self::Repr

Encode self using a big endian representation.

fn to_le_repr(&self) -> Self::Repr

Encode self using a little endian representation.

impl<'a> Product<&'a FieldElement> for FieldElement

fn product<I: Iterator<Item = &'a Self>>(iter: I) -> Self

Takes an iterator and generates Self from the elements by multiplying the items.

impl Product for FieldElement

fn product<I: Iterator<Item = Self>>(iter: I) -> Self

Takes an iterator and generates Self from the elements by multiplying the items.

impl Retrieve for FieldElement

type Output = Uint<crypto_bigint::::uint::U576::{constant#0}>

The original type.

fn retrieve(&self) -> Uint

Convert the number back from the optimized representation.

impl Sub<&FieldElement> for &FieldElement

type Output = FieldElement

The resulting type after applying the - operator.

fn sub(self, rhs: &FieldElement) -> FieldElement

Performs the - operation.

impl Sub<&FieldElement> for FieldElement

type Output = FieldElement

The resulting type after applying the - operator.

fn sub(self, rhs: &FieldElement) -> FieldElement

Performs the - operation.

impl Sub for FieldElement

type Output = FieldElement

The resulting type after applying the - operator.

fn sub(self, rhs: FieldElement) -> FieldElement

Performs the - operation.

impl SubAssign<&FieldElement> for FieldElement

fn sub_assign(&mut self, other: &FieldElement)

Performs the -= operation.

impl SubAssign for FieldElement

fn sub_assign(&mut self, other: FieldElement)

Performs the -= operation.

impl<'a> Sum<&'a FieldElement> for FieldElement

fn sum<I: Iterator<Item = &'a FieldElement>>(iter: I) -> Self

Takes an iterator and generates Self from the elements by “summing up” the items.

impl Sum for FieldElement

fn sum<I: Iterator<Item = Self>>(iter: I) -> Self

Takes an iterator and generates Self from the elements by “summing up” the items.

impl Copy for FieldElement

impl DefaultIsZeroes for FieldElement

impl Eq for FieldElement

impl FieldExt for FieldElement