logo
pub struct Scalar { /* private fields */ }
Expand description

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

Implementations

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

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

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.

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.

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

Inputs
  • rng: any RNG which implements the RngCore + CryptoRng interface.
Returns

A random scalar within ℤ/lℤ.

Example
extern crate rand_core;
use curve25519_dalek::scalar::Scalar;

use rand_core::OsRng;

let mut csprng = OsRng;
let a: Scalar = Scalar::random(&mut csprng);

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

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.

Example
extern crate sha2;

use sha2::Digest;
use sha2::Sha512;

let mut h = Sha512::new()
    .chain("To really appreciate architecture, you may even need to commit a murder.")
    .chain("While the programs used for The Manhattan Transcripts are of the most extreme")
    .chain("nature, they also parallel the most common formula plot: the archetype of")
    .chain("murder. Other phantasms were occasionally used to underline the fact that")
    .chain("perhaps all architecture, rather than being about functional standards, is")
    .chain("about love and death.");

let s = Scalar::from_hash(h);

println!("{:?}", s.to_bytes());
assert!(s == Scalar::from_bits([ 21,  88, 208, 252,  63, 122, 210, 152,
                                154,  38,  15,  23,  16, 167,  80, 150,
                                192, 221,  77, 226,  62,  25, 224, 148,
                                239,  48, 176,  10, 185,  69, 168,  11, ]));

Convert this Scalar to its underlying sequence of bytes.

Example
use curve25519_dalek::scalar::Scalar;

let s: Scalar = Scalar::zero();

assert!(s.to_bytes() == [0u8; 32]);

View the little-endian byte encoding of the integer representing this Scalar.

Example
use curve25519_dalek::scalar::Scalar;

let s: Scalar = Scalar::zero();

assert!(s.as_bytes() == &[0u8; 32]);

Construct the scalar \( 0 \).

Construct the scalar \( 1 \).

Given a nonzero Scalar, compute its multiplicative inverse.

Warning

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

Returns

The multiplicative inverse of the this Scalar.

Example
use curve25519_dalek::scalar::Scalar;

// x = 2238329342913194256032495932344128051776374960164957527413114840482143558222
let X: Scalar = Scalar::from_bytes_mod_order([
        0x4e, 0x5a, 0xb4, 0x34, 0x5d, 0x47, 0x08, 0x84,
        0x59, 0x13, 0xb4, 0x64, 0x1b, 0xc2, 0x7d, 0x52,
        0x52, 0xa5, 0x85, 0x10, 0x1b, 0xcc, 0x42, 0x44,
        0xd4, 0x49, 0xf4, 0xa8, 0x79, 0xd9, 0xf2, 0x04,
    ]);
// 1/x = 6859937278830797291664592131120606308688036382723378951768035303146619657244
let XINV: Scalar = Scalar::from_bytes_mod_order([
        0x1c, 0xdc, 0x17, 0xfc, 0xe0, 0xe9, 0xa5, 0xbb,
        0xd9, 0x24, 0x7e, 0x56, 0xbb, 0x01, 0x63, 0x47,
        0xbb, 0xba, 0x31, 0xed, 0xd5, 0xa9, 0xbb, 0x96,
        0xd5, 0x0b, 0xcd, 0x7a, 0x3f, 0x96, 0x2a, 0x0f,
    ]);

let inv_X: Scalar = X.invert();
assert!(XINV == inv_X);
let should_be_one: Scalar = &inv_X * &X;
assert!(should_be_one == Scalar::one());

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.

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

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

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

Reduce this Scalar modulo \(\ell\).

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

The resulting type after applying the + operator.

Performs the + operation. Read more

The resulting type after applying the + operator.

Performs the + operation. Read more

The resulting type after applying the + operator.

Performs the + operation. Read more

The resulting type after applying the + operator.

Performs the + operation. Read more

Performs the += operation. Read more

Performs the += operation. Read more

Returns a copy of the value. Read more

Performs copy-assignment from source. Read more

Select a or b according to choice. Read more

Conditionally assign other to self, according to choice. Read more

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

Determine if two items are equal. Read more

Formats the value using the given formatter. Read more

Returns the “default value” for a type. Read more

Performs the conversion.

Performs the conversion.

Performs the conversion.

Construct a scalar from the given u64.

Inputs

An u64 to convert to a Scalar.

Returns

A Scalar corresponding to the input u64.

Example
use curve25519_dalek::scalar::Scalar;

let fourtytwo = Scalar::from(42u64);
let six = Scalar::from(6u64);
let seven = Scalar::from(7u64);

assert!(fourtytwo == six * seven);

Performs the conversion.

Feeds this value into the given Hasher. Read more

Feeds a slice of this type into the given Hasher. Read more

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

The returned type after indexing.

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

The resulting type after applying the * operator.

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

The resulting type after applying the * operator.

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

The resulting type after applying the * operator.

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

The resulting type after applying the * operator.

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

The resulting type after applying the * operator.

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

The resulting type after applying the * operator.

The resulting type after applying the * operator.

Performs the * operation. Read more

The resulting type after applying the * operator.

Performs the * operation. Read more

Scalar multiplication: compute scalar * self.

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

The resulting type after applying the * operator.

The resulting type after applying the * operator.

Performs the * operation. Read more

The resulting type after applying the * operator.

Performs the * operation. Read more

Scalar multiplication: compute self * scalar.

The resulting type after applying the * operator.

The resulting type after applying the * operator.

Performs the * operation. Read more

The resulting type after applying the * operator.

Performs the * operation. Read more

The resulting type after applying the * operator.

Performs the * operation. Read more

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

The resulting type after applying the * operator.

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

The resulting type after applying the * operator.

Scalar multiplication: compute scalar * self.

The resulting type after applying the * operator.

The resulting type after applying the * operator.

Performs the * operation. Read more

The resulting type after applying the * operator.

Performs the * operation. Read more

The resulting type after applying the * operator.

Performs the * operation. Read more

Multiply this MontgomeryPoint by a Scalar.

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

The resulting type after applying the * operator.

The resulting type after applying the * operator.

Performs the * operation. Read more

Scalar multiplication: compute scalar * self.

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

The resulting type after applying the * operator.

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

The resulting type after applying the * operator.

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

The resulting type after applying the * operator.

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

The resulting type after applying the * operator.

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

The resulting type after applying the * operator.

The resulting type after applying the * operator.

Performs the * operation. Read more

The resulting type after applying the * operator.

Performs the * operation. Read more

The resulting type after applying the * operator.

Performs the * operation. Read more

The resulting type after applying the * operator.

Performs the * operation. Read more

The resulting type after applying the * operator.

Performs the * operation. Read more

The resulting type after applying the * operator.

Performs the * operation. Read more

The resulting type after applying the * operator.

Performs the * operation. Read more

The resulting type after applying the * operator.

Performs the * operation. Read more

The resulting type after applying the * operator.

Performs the * operation. Read more

The resulting type after applying the * operator.

Performs the * operation. Read more

The resulting type after applying the * operator.

Performs the * operation. Read more

The resulting type after applying the * operator.

Performs the * operation. Read more

The resulting type after applying the * operator.

Performs the * operation. Read more

The resulting type after applying the * operator.

Performs the * operation. Read more

Performs the *= operation. Read more

Performs the *= operation. Read more

Performs the *= operation. Read more

Performs the *= operation. Read more

Performs the *= operation. Read more

Performs the *= operation. Read more

Performs the *= operation. Read more

Performs the *= operation. Read more

The resulting type after applying the - operator.

Performs the unary - operation. Read more

The resulting type after applying the - operator.

Performs the unary - operation. Read more

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

This method tests for !=.

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

The resulting type after applying the - operator.

Performs the - operation. Read more

The resulting type after applying the - operator.

Performs the - operation. Read more

The resulting type after applying the - operator.

Performs the - operation. Read more

The resulting type after applying the - operator.

Performs the - operation. Read more

Performs the -= operation. Read more

Performs the -= operation. Read more

Method which takes an iterator and generates Self from the elements by “summing up” the items. Read more

Zero out this object from memory using Rust intrinsics which ensure the zeroization operation is not “optimized away” by the compiler. Read more

Auto Trait Implementations

Blanket Implementations

Gets the TypeId of self. Read more

Immutably borrows from an owned value. Read more

Mutably borrows from an owned value. Read more

Negate self if choice == Choice(1); otherwise, leave it unchanged. Read more

Returns the argument unchanged.

Calls U::from(self).

That is, this conversion is whatever the implementation of From<T> for U chooses to do.

Should always be Self

The resulting type after obtaining ownership.

Creates owned data from borrowed data, usually by cloning. Read more

🔬 This is a nightly-only experimental API. (toowned_clone_into)

Uses borrowed data to replace owned data, usually by cloning. Read more

The type returned in the event of a conversion error.

Performs the conversion.

The type returned in the event of a conversion error.

Performs the conversion.