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 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<&FieldElement> for &FieldElement

type Output = FieldElement

The resulting type after applying the + operator.

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

Performs the + operation.

impl AddAssign for FieldElement

fn add_assign(&mut self, other: FieldElement)

Performs the += operation.

impl AddAssign<&FieldElement> 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 Copy for FieldElement

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 DefaultIsZeroes for FieldElement

impl Eq for FieldElement

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 FieldExt for FieldElement

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<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 From<u128> for FieldElement

fn from(n: u128) -> 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 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<&FieldElement> for &FieldElement

type Output = FieldElement

The resulting type after applying the * operator.

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

Performs the * operation.

impl MulAssign for FieldElement

fn mul_assign(&mut self, other: FieldElement)

Performs the *= operation.

impl MulAssign<&FieldElement> 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

Equality operator ==.

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

Inequality operator !=.

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 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<'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 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 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<&FieldElement> for &FieldElement

type Output = FieldElement

The resulting type after applying the - operator.

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

Performs the - operation.

impl SubAssign for FieldElement

fn sub_assign(&mut self, other: FieldElement)

Performs the -= operation.

impl SubAssign<&FieldElement> for FieldElement

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

Performs the -= operation.

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<'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.