# [−][src]Module curve25519_dalek::scalar

Arithmetic on scalars (integers mod the group order).

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

This 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$$.

All arithmetic on Scalars is done modulo $$\ell$$.

# Constructing a scalar

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

This function does input validation, ensuring that the input bytes are the canonical encoding of a Scalar. If they are, we'll get Some(Scalar) in return:

use curve25519_dalek::scalar::Scalar;

let one_as_bytes: [u8; 32] = Scalar::one().to_bytes();
let a: Option<Scalar> = Scalar::from_canonical_bytes(one_as_bytes);

assert!(a.is_some());

However, if we give it bytes representing a scalar larger than $$\ell$$ (in this case, $$\ell + 2$$), we'll get None back:

use curve25519_dalek::scalar::Scalar;

let l_plus_two_bytes: [u8; 32] = [
0xef, 0xd3, 0xf5, 0x5c, 0x1a, 0x63, 0x12, 0x58,
0xd6, 0x9c, 0xf7, 0xa2, 0xde, 0xf9, 0xde, 0x14,
0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x10,
];
let a: Option<Scalar> = Scalar::from_canonical_bytes(l_plus_two_bytes);

assert!(a.is_none());

Another way to create a Scalar is by reducing a $$256$$-bit integer mod $$\ell$$, for which one may use the Scalar::from_bytes_mod_order method. In the case of the second example above, this would reduce the resultant scalar $$\mod \ell$$, producing $$2$$:

use curve25519_dalek::scalar::Scalar;

let l_plus_two_bytes: [u8; 32] = [
0xef, 0xd3, 0xf5, 0x5c, 0x1a, 0x63, 0x12, 0x58,
0xd6, 0x9c, 0xf7, 0xa2, 0xde, 0xf9, 0xde, 0x14,
0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x10,
];
let a: Scalar = Scalar::from_bytes_mod_order(l_plus_two_bytes);

let two: Scalar = Scalar::one() + Scalar::one();

assert!(a == two);

There is also a constructor that reduces a $$512$$-bit integer, Scalar::from_bytes_mod_order_wide.

To construct a Scalar as the hash of some input data, use Scalar::hash_from_bytes, which takes a buffer, or Scalar::from_hash, which allows an IUF API.

use sha2::{Digest, Sha512};
use curve25519_dalek::scalar::Scalar;

// Hashing a single byte slice
let a = Scalar::hash_from_bytes::<Sha512>(b"Abolish ICE");

// Streaming data into a hash object
let mut hasher = Sha512::default();
hasher.input(b"Abolish ");
hasher.input(b"ICE");
let a2 = Scalar::from_hash(hasher);

assert_eq!(a, a2);

Finally, to create a Scalar with a specific bit-pattern (e.g., for compatibility with X/Ed25519 "clamping"), use Scalar::from_bits. This constructs a scalar with exactly the bit pattern given, without any assurances as to reduction modulo the group order:

use curve25519_dalek::scalar::Scalar;

let l_plus_two_bytes: [u8; 32] = [
0xef, 0xd3, 0xf5, 0x5c, 0x1a, 0x63, 0x12, 0x58,
0xd6, 0x9c, 0xf7, 0xa2, 0xde, 0xf9, 0xde, 0x14,
0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x10,
];
let a: Scalar = Scalar::from_bits(l_plus_two_bytes);

let two: Scalar = Scalar::one() + Scalar::one();

assert!(a != two);              // the scalar is not reduced (mod l)…
assert!(! a.is_canonical());    // …and therefore is not canonical.
assert!(a.reduce() == two);     // if we were to reduce it manually, it would be.

The resulting Scalar has exactly the specified bit pattern, except for the highest bit, which will be set to 0.

## Structs

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

## Type Definitions

 UnpackedScalar An UnpackedScalar represents an element of the field GF(l), optimized for speed.