Struct curve25519_dalek::scalar::Scalar

pub struct Scalar { /* fields omitted */ }

The Scalar struct holds an integer \(s < 2^{255} \) which represents an element of \(\mathbb Z / \ell\).

Both the Ristretto group and the Ed25519 basepoint have prime order \( \ell = 2^{252} + 27742317777372353535851937790883648493 \).

The code is intended to be useful with both the Ristretto group (where everything is done modulo \( \ell \)), and the X/Ed25519 setting, which mandates specific bit-twiddles that are not well-defined modulo \( \ell \).

To create a Scalar from a supposedly canonical encoding, use Scalar::from_canonical_bytes.

To create a Scalar by reducing a \(256\)-bit integer mod \( \ell \), use Scalar::from_bytes_mod_order.

To create a Scalar by reducing a \(512\)-bit integer mod \( \ell \), use Scalar::from_bytes_mod_order_wide.

To create a Scalar with a specific bit-pattern (e.g., for compatibility with X25519 "clamping"), use Scalar::from_bits.

All arithmetic on Scalars is done modulo \( \ell \).

Methods

impl Scalar

pub fn from_bytes_mod_order(bytes: [u8; 32]) -> Scalar

Construct a Scalar by reducing a 256-bit little-endian integer modulo the group order \( \ell \).

pub fn from_bytes_mod_order_wide(input: &[u8; 64]) -> Scalar

Construct a Scalar by reducing a 512-bit little-endian integer modulo the group order \( \ell \).

pub fn from_canonical_bytes(bytes: [u8; 32]) -> Option<Scalar>

Attempt to construct a Scalar from a canonical byte representation.

Return

• Some(s), where s is the Scalar corresponding to bytes, if bytes is a canonical byte representation;
• None if bytes is not a canonical byte representation.

pub fn from_bits(bytes: [u8; 32]) -> Scalar

Construct a Scalar from the low 255 bits of a 256-bit integer.

This function is intended for applications like X25519 which require specific bit-patterns when performing scalar multiplication.

impl Scalar

pub fn random<T: Rng>(rng: &mut T) -> Self

Return a Scalar chosen uniformly at random using a user-provided RNG.

Inputs

• rng: any RNG which implements the rand::Rng interface.

Returns

A random scalar within ℤ/lℤ.

pub fn hash_from_bytes<D>(input: &[u8]) -> Scalar where
    D: Digest<OutputSize = U64> + Default, 

Hash a slice of bytes into a scalar.

Takes a type parameter D, which is any Digest producing 64 bytes (512 bits) of output.

Convenience wrapper around from_hash.

Example

extern crate sha2;
use sha2::Sha512;

let msg = "To really appreciate architecture, you may even need to commit a murder";
let s = Scalar::hash_from_bytes::<Sha512>(msg.as_bytes());

pub fn from_hash<D>(hash: D) -> Scalar where
    D: Digest<OutputSize = U64> + Default, 

Construct a scalar from an existing Digest instance.

Use this instead of hash_from_bytes if it is more convenient to stream data into the Digest than to pass a single byte slice.

pub fn to_bytes(&self) -> [u8; 32]

Convert this Scalar to its underlying sequence of bytes.

pub fn as_bytes(&self) -> &[u8; 32]

View this Scalar as a sequence of bytes.

pub fn zero() -> Self

Construct the scalar \( 0 \).

pub fn one() -> Self

Construct the scalar \( 1 \).

pub fn from_u64(x: u64) -> Scalar

Construct a scalar from the given u64.

pub fn invert(&self) -> Scalar

Compute the multiplicative inverse of this scalar.

pub fn batch_invert(inputs: &mut [Scalar]) -> Scalar

Given a slice of nonzero (possibly secret) Scalars, compute their inverses in a batch.

Return

Each element of inputs is replaced by its inverse.

The product of all inverses is returned.

Warning

All input Scalars MUST be nonzero. If you cannot prove that this is the case, you SHOULD NOT USE THIS FUNCTION.

This function is most efficient when the batch size (slice length) is a power of 2.

Example

let mut scalars = [
    Scalar::from_u64(3),
    Scalar::from_u64(5),
    Scalar::from_u64(7),
    Scalar::from_u64(11),
];

let allinv = Scalar::batch_invert(&mut scalars);

assert_eq!(allinv, Scalar::from_u64(3*5*7*11).invert());
assert_eq!(scalars[0], Scalar::from_u64(3).invert());
assert_eq!(scalars[1], Scalar::from_u64(5).invert());
assert_eq!(scalars[2], Scalar::from_u64(7).invert());
assert_eq!(scalars[3], Scalar::from_u64(11).invert());

pub fn reduce(&self) -> Scalar

Reduce this Scalar modulo \(\ell\).

pub fn is_canonical(&self) -> bool

Check whether this Scalar is the canonical representative mod \(\ell\).

This is intended for uses like input validation, where variable-time code is acceptable.

// 2^255 - 1, since `from_bits` clears the high bit
let _2_255_minus_1 = Scalar::from_bits([0xff;32]);
assert!(!_2_255_minus_1.is_canonical());

let reduced = _2_255_minus_1.reduce();
assert!(reduced.is_canonical());

Trait Implementations

impl Copy for Scalar

impl Clone for Scalar

fn clone(&self) -> Scalar

Returns a copy of the value.

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

Performs copy-assignment from source.

impl Debug for Scalar

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

Formats the value using the given formatter.

impl Eq for Scalar

impl PartialEq for Scalar

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

This method tests for self and other values to be equal, and is used by ==.

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

This method tests for !=.

impl ConstantTimeEq for Scalar

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

Determine if two items are equal.

impl Index<usize> for Scalar

type Output = u8

The returned type after indexing.

fn index(&self, _index: usize) -> &u8

Index the bytes of the representative for this Scalar. Mutation is not permitted.

impl<'b> MulAssign<&'b Scalar> for Scalar

fn mul_assign(&mut self, _rhs: &'b Scalar)

Performs the *= operation.

impl MulAssign<Scalar> for Scalar

fn mul_assign(&mut self, rhs: Scalar)

Performs the *= operation.

impl<'a, 'b> Mul<&'b Scalar> for &'a Scalar

type Output = Scalar

The resulting type after applying the * operator.

fn mul(self, _rhs: &'b Scalar) -> Scalar

Performs the * operation.

impl<'b> Mul<&'b Scalar> for Scalar

type Output = Scalar

The resulting type after applying the * operator.

fn mul(self, rhs: &'b Scalar) -> Scalar

Performs the * operation.

impl<'a> Mul<Scalar> for &'a Scalar

type Output = Scalar

The resulting type after applying the * operator.

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

Performs the * operation.

impl Mul<Scalar> for Scalar

type Output = Scalar

The resulting type after applying the * operator.

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

Performs the * operation.

impl<'b> AddAssign<&'b Scalar> for Scalar

fn add_assign(&mut self, _rhs: &'b Scalar)

Performs the += operation.

impl AddAssign<Scalar> for Scalar

fn add_assign(&mut self, rhs: Scalar)

Performs the += operation.

impl<'a, 'b> Add<&'b Scalar> for &'a Scalar

type Output = Scalar

The resulting type after applying the + operator.

fn add(self, _rhs: &'b Scalar) -> Scalar

Performs the + operation.

impl<'b> Add<&'b Scalar> for Scalar

type Output = Scalar

The resulting type after applying the + operator.

fn add(self, rhs: &'b Scalar) -> Scalar

Performs the + operation.

impl<'a> Add<Scalar> for &'a Scalar

type Output = Scalar

The resulting type after applying the + operator.

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

Performs the + operation.

impl Add<Scalar> for Scalar

type Output = Scalar

The resulting type after applying the + operator.

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

Performs the + operation.

impl<'b> SubAssign<&'b Scalar> for Scalar

fn sub_assign(&mut self, _rhs: &'b Scalar)

Performs the -= operation.

impl SubAssign<Scalar> for Scalar

fn sub_assign(&mut self, rhs: Scalar)

Performs the -= operation.

impl<'a, 'b> Sub<&'b Scalar> for &'a Scalar

type Output = Scalar

The resulting type after applying the - operator.

fn sub(self, _rhs: &'b Scalar) -> Scalar

Performs the - operation.

impl<'b> Sub<&'b Scalar> for Scalar

type Output = Scalar

The resulting type after applying the - operator.

fn sub(self, rhs: &'b Scalar) -> Scalar

Performs the - operation.

impl<'a> Sub<Scalar> for &'a Scalar

type Output = Scalar

The resulting type after applying the - operator.

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

Performs the - operation.

impl Sub<Scalar> for Scalar

type Output = Scalar

The resulting type after applying the - operator.

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

Performs the - operation.

impl<'a> Neg for &'a Scalar

type Output = Scalar

The resulting type after applying the - operator.

fn neg(self) -> Scalar

Performs the unary - operation.

impl<'a> Neg for Scalar

type Output = Scalar

The resulting type after applying the - operator.

fn neg(self) -> Scalar

Performs the unary - operation.

impl ConditionallyAssignable for Scalar

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

Conditionally assign other to self, according to choice.

impl<T> Product<T> for Scalar where
    T: Borrow<Scalar>, 

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

Method which takes an iterator and generates Self from the elements by multiplying the items.

impl<T> Sum<T> for Scalar where
    T: Borrow<Scalar>, 

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

Method which takes an iterator and generates Self from the elements by "summing up" the items.

impl MulAssign<Scalar> for MontgomeryPoint

fn mul_assign(&mut self, rhs: Scalar)

Performs the *= operation.

impl<'b> Mul<&'b Scalar> for MontgomeryPoint

type Output = MontgomeryPoint

The resulting type after applying the * operator.

fn mul(self, rhs: &'b Scalar) -> MontgomeryPoint

Performs the * operation.

impl<'a> Mul<Scalar> for &'a MontgomeryPoint

type Output = MontgomeryPoint

The resulting type after applying the * operator.

fn mul(self, rhs: Scalar) -> MontgomeryPoint

Performs the * operation.

impl Mul<Scalar> for MontgomeryPoint

type Output = MontgomeryPoint

The resulting type after applying the * operator.

fn mul(self, rhs: Scalar) -> MontgomeryPoint

Performs the * operation.

impl<'b> Mul<&'b MontgomeryPoint> for Scalar

type Output = MontgomeryPoint

The resulting type after applying the * operator.

fn mul(self, rhs: &'b MontgomeryPoint) -> MontgomeryPoint

Performs the * operation.

impl<'a> Mul<MontgomeryPoint> for &'a Scalar

type Output = MontgomeryPoint

The resulting type after applying the * operator.

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

Performs the * operation.

impl Mul<MontgomeryPoint> for Scalar

type Output = MontgomeryPoint

The resulting type after applying the * operator.

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

Performs the * operation.

impl<'a, 'b> Mul<&'b Scalar> for &'a MontgomeryPoint

Multiply this MontgomeryPoint by a Scalar.

type Output = MontgomeryPoint

The resulting type after applying the * operator.

fn mul(self, scalar: &'b Scalar) -> MontgomeryPoint

Given self \( = u_0(P) \), and a Scalar \(n\), return \( u_0([n]P) \).

impl<'b> MulAssign<&'b Scalar> for MontgomeryPoint

fn mul_assign(&mut self, scalar: &'b Scalar)

Performs the *= operation.

impl<'a, 'b> Mul<&'b MontgomeryPoint> for &'a Scalar

type Output = MontgomeryPoint

The resulting type after applying the * operator.

fn mul(self, point: &'b MontgomeryPoint) -> MontgomeryPoint

Performs the * operation.

impl<'b> MulAssign<&'b Scalar> for EdwardsPoint

fn mul_assign(&mut self, scalar: &'b Scalar)

Performs the *= operation.

impl MulAssign<Scalar> for EdwardsPoint

fn mul_assign(&mut self, rhs: Scalar)

Performs the *= operation.

impl<'b> Mul<&'b Scalar> for EdwardsPoint

type Output = EdwardsPoint

The resulting type after applying the * operator.

fn mul(self, rhs: &'b Scalar) -> EdwardsPoint

Performs the * operation.

impl<'a> Mul<Scalar> for &'a EdwardsPoint

type Output = EdwardsPoint

The resulting type after applying the * operator.

fn mul(self, rhs: Scalar) -> EdwardsPoint

Performs the * operation.

impl Mul<Scalar> for EdwardsPoint

type Output = EdwardsPoint

The resulting type after applying the * operator.

fn mul(self, rhs: Scalar) -> EdwardsPoint

Performs the * operation.

impl<'b> Mul<&'b EdwardsPoint> for Scalar

type Output = EdwardsPoint

The resulting type after applying the * operator.

fn mul(self, rhs: &'b EdwardsPoint) -> EdwardsPoint

Performs the * operation.

impl<'a> Mul<EdwardsPoint> for &'a Scalar

type Output = EdwardsPoint

The resulting type after applying the * operator.

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

Performs the * operation.

impl Mul<EdwardsPoint> for Scalar

type Output = EdwardsPoint

The resulting type after applying the * operator.

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

Performs the * operation.

impl<'a, 'b> Mul<&'b Scalar> for &'a EdwardsPoint

type Output = EdwardsPoint

The resulting type after applying the * operator.

fn mul(self, scalar: &'b Scalar) -> EdwardsPoint

Scalar multiplication: compute scalar * self.

For scalar multiplication of a basepoint, EdwardsBasepointTable is approximately 4x faster.

impl<'a, 'b> Mul<&'b EdwardsPoint> for &'a Scalar

type Output = EdwardsPoint

The resulting type after applying the * operator.

fn mul(self, point: &'b EdwardsPoint) -> EdwardsPoint

Scalar multiplication: compute scalar * self.

For scalar multiplication of a basepoint, EdwardsBasepointTable is approximately 4x faster.

impl<'a, 'b> Mul<&'b Scalar> for &'a EdwardsBasepointTable

type Output = EdwardsPoint

The resulting type after applying the * operator.

fn mul(self, scalar: &'b Scalar) -> EdwardsPoint

Construct an EdwardsPoint from a Scalar \(a\) by computing the multiple \(aB\) of this basepoint \(B\).

impl<'a, 'b> Mul<&'a EdwardsBasepointTable> for &'b Scalar

type Output = EdwardsPoint

The resulting type after applying the * operator.

fn mul(self, basepoint_table: &'a EdwardsBasepointTable) -> EdwardsPoint

Construct an EdwardsPoint from a Scalar \(a\) by computing the multiple \(aB\) of this basepoint \(B\).

impl<'b> MulAssign<&'b Scalar> for RistrettoPoint

fn mul_assign(&mut self, scalar: &'b Scalar)

Performs the *= operation.

impl<'a, 'b> Mul<&'b Scalar> for &'a RistrettoPoint

type Output = RistrettoPoint

The resulting type after applying the * operator.

fn mul(self, scalar: &'b Scalar) -> RistrettoPoint

Scalar multiplication: compute scalar * self.

impl<'a, 'b> Mul<&'b RistrettoPoint> for &'a Scalar

type Output = RistrettoPoint

The resulting type after applying the * operator.

fn mul(self, point: &'b RistrettoPoint) -> RistrettoPoint

Scalar multiplication: compute self * scalar.

impl MulAssign<Scalar> for RistrettoPoint

fn mul_assign(&mut self, rhs: Scalar)

Performs the *= operation.

impl<'b> Mul<&'b Scalar> for RistrettoPoint

type Output = RistrettoPoint

The resulting type after applying the * operator.

fn mul(self, rhs: &'b Scalar) -> RistrettoPoint

Performs the * operation.

impl<'a> Mul<Scalar> for &'a RistrettoPoint

type Output = RistrettoPoint

The resulting type after applying the * operator.

fn mul(self, rhs: Scalar) -> RistrettoPoint

Performs the * operation.

impl Mul<Scalar> for RistrettoPoint

type Output = RistrettoPoint

The resulting type after applying the * operator.

fn mul(self, rhs: Scalar) -> RistrettoPoint

Performs the * operation.

impl<'b> Mul<&'b RistrettoPoint> for Scalar

type Output = RistrettoPoint

The resulting type after applying the * operator.

fn mul(self, rhs: &'b RistrettoPoint) -> RistrettoPoint

Performs the * operation.

impl<'a> Mul<RistrettoPoint> for &'a Scalar

type Output = RistrettoPoint

The resulting type after applying the * operator.

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

Performs the * operation.

impl Mul<RistrettoPoint> for Scalar

type Output = RistrettoPoint

The resulting type after applying the * operator.

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

Performs the * operation.

impl<'a, 'b> Mul<&'b Scalar> for &'a RistrettoBasepointTable

type Output = RistrettoPoint

The resulting type after applying the * operator.

fn mul(self, scalar: &'b Scalar) -> RistrettoPoint

Performs the * operation.

impl<'a, 'b> Mul<&'a RistrettoBasepointTable> for &'b Scalar

type Output = RistrettoPoint

The resulting type after applying the * operator.

fn mul(self, basepoint_table: &'a RistrettoBasepointTable) -> RistrettoPoint

Performs the * operation.