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

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 \).

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 \).

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.

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

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

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());

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.

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

Convert this Scalar to its underlying sequence of bytes.

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

View this Scalar as a sequence of bytes.

fn zero() -> Self

Construct the scalar \( 0 \).

fn one() -> Self

Construct the scalar \( 1 \).

fn from_u64(x: u64) -> Scalar

Construct a scalar from the given u64.

fn invert(&self) -> Scalar

Compute the multiplicative inverse of this scalar.

fn reduce(&self) -> Scalar

Reduce this Scalar modulo \(\ell\).

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

Test equality between two Scalars.

Warning

This function is not guaranteed to be constant time and should only be used for debugging purposes.

Returns

True if they are equal, and false otherwise.

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

This method tests for !=.

impl Equal for Scalar

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

Test equality between two Scalars in constant time.

Returns

1u8 if they are equal, and 0u8 otherwise.

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<'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> AddAssign<&'b Scalar> for Scalar

fn add_assign(&mut self, _rhs: &'b 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> SubAssign<&'b Scalar> for Scalar

fn sub_assign(&mut self, _rhs: &'b 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<'a> Neg for &'a 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: u8)

Conditionally assign another Scalar to this one.

let a = Scalar::from_bits([0u8;32]);
let b = Scalar::from_bits([1u8;32]);
let mut t = a;
t.conditional_assign(&b, 0u8);
assert!(t[0] == a[0]);
t.conditional_assign(&b, 1u8);
assert!(t[0] == b[0]);

Preconditions

• choice in {0,1}

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<'a, 'b> Mul<&'b ExtendedPoint> for &'a Scalar

type Output = ExtendedPoint

The resulting type after applying the * operator.

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

Scalar multiplication: compute scalar * self.

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

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

type Output = ExtendedPoint

The resulting type after applying the * operator.

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

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

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