Struct secp256kfun::Scalar

pub struct Scalar<S = Secret, Z = NonZero>(_, _);

A secp256k1 scalar (an integer mod the curve order)

The term scalar comes from interpreting the secp256k1 elliptic curve group as a vector space with a point as a notional single element vector and the field of integers modulo the curve order as its scalars. Specifically, a Scalar represents an integer modulo the curve order q where

q = 0xFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFEBAAEDCE6AF48A03BBFD25E8CD0364141

The thing that makes secp256k1 and other elliptic curves useful for cryptography is that scalar multiplication can be done efficiently:

use secp256kfun::{g, Scalar, G};
let x = Scalar::random(&mut rand::thread_rng());
let X = g!(x * G);

But finding x from (X,G) is hard because there is no known efficient algorithm to divide X by G to get x. This is known as the elliptic curve discrete logarithm problem. Because of this, scalars are often used as a secret keys with the points obtained by multiplying them by G as their corresponding public keys.

Markers

A Scalar<S,Z> has two markers:

• S: A Secrecy to determine whether operations on this scalar should be done in constant time or not. By default scalars are Secret so operations run in constant-time.
• Z: A ZeroChoice to keep track of whether the point might be zero or is guaranteed to non-zero.

Implementations

impl<Z, S> Scalar<S, Z>

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

Serializes the scalar to its 32-byte big-endian representation

pub fn conditional_negate(&mut self, cond: bool)

Negates the scalar in-place if cond is true.

pub fn is_high(&self) -> bool

Returns whether the scalar is greater than the curve_order/2.

pub fn is_zero(&self) -> bool

Returns true if the scalar is equal to zero

pub fn set_secrecy<SNew>(self) -> Scalar<SNew, Z>

A hack that is necessary when writing deserialization code until rust issue #44491 is fixed. Don’t use this method use mark which checks the type is a valid secrecy.

impl<S> Scalar<S, NonZero>

pub fn invert(&self) -> Self

Returns the multiplicative inverse of the scalar modulo the curve order.

Example

use secp256kfun::{s, Scalar};
let a = Scalar::random(&mut rand::thread_rng());
let a_inverse = a.invert();
assert_eq!(s!(a * a_inverse), Scalar::one());

impl Scalar<Secret, NonZero>

pub fn random<R: RngCore + CryptoRng>(rng: &mut R) -> Self

Generates a random scalar from randomness taken from a caller provided cryptographically secure random number generator.

Example

use secp256kfun::{g, Scalar, G};
let secret_scalar = Scalar::random(&mut rand::thread_rng());
let public_point = g!(secret_scalar * G);

pub fn from_hash(hash: impl Digest<OutputSize = U32>) -> Self

Converts the output of a 32-byte hash into a scalar by reducing it modulo the curve order.

Example

use digest::Digest;
use secp256kfun::Scalar;
let mut hash = sha2::Sha256::default();
hash.update(b"Chancellor on brink of second bailout for banks".as_ref());
let scalar = Scalar::from_hash(hash);

pub fn from_non_zero_u32(int: NonZeroU32) -> Self

Converts a NonZeroU32 into a Scalar<Secret,NonZero>.

pub fn one() -> Self

Returns the integer 1 as a Scalar<Secret, NonZero>.

pub fn minus_one() -> Self

Returns the integer -1 (modulo the curve order) as a Scalar<Secret, NonZero>.

impl Scalar<Secret, Zero>

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

Converts 32 bytes into a scalar by reducing it modulo the curve order q.

Example

use secp256kfun::{hex, Scalar};
let scalar = Scalar::from_bytes_mod_order(*b"xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx");
assert_eq!(scalar.to_bytes(), *b"xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx");
let scalar_overflowed = Scalar::from_bytes_mod_order(
    hex::decode_array("FFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFEBAAEDCE6AF48A03BBFD25E8CD0364142")
        .unwrap(),
);
assert_eq!(scalar_overflowed, Scalar::one())

pub fn from_slice_mod_order(slice: &[u8]) -> Option<Self>

Exactly like from_bytes_mod_order except it operates on a 32-byte slice rather than an array. If the slice is not 32 bytes long then the function returns None.

Example

let bytes = b"xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx";
assert!(Scalar::from_slice_mod_order(&bytes[..31]).is_none());
assert_eq!(
    Scalar::from_slice_mod_order(&bytes[..]).unwrap(),
    Scalar::from_bytes_mod_order(*bytes)
);

pub fn from_bytes(bytes: [u8; 32]) -> Option<Self>

Creates a scalar from 32 big-endian encoded bytes. If the bytes represent an integer greater than or equal to the curve order then it returns None.

Example

use secp256kfun::{marker::*, Scalar};
assert!(Scalar::from_bytes([0u8; 32]).is_some());
assert!(Scalar::from_bytes([255u8; 32]).is_none());

pub fn from_slice(slice: &[u8]) -> Option<Self>

Creates a scalar from 32 big-endian encoded bytes in a slice. If the length of the slice is not 32 or the bytes represent an integer greater than or equal to the curve order then it returns None.

pub fn zero() -> Self

Returns the zero scalar.

Example

let x = Scalar::random(&mut rand::thread_rng());
let zero = Scalar::zero();
assert_eq!(s!(zero * x), zero);
assert_eq!(s!(x + zero), x);

impl<S> Scalar<S, Zero>

pub fn expect_nonzero(self, reason: &str) -> Scalar<S, NonZero>

Converts a scalar marked with Zero to one that is marked NonZero. You must provide a justification for this as the reason. If you’re wrong the method will panic with the reason.

This is shorthand for:

use secp256kfun::marker::{Mark, NonZero};
scalar.mark::<NonZero>().expect(reason);

Example

use secp256kfun::{s, Scalar};
let two = s!(1 + 1).expect_nonzero("one plus one is not zero");

Trait Implementations

impl<Z, S> ChangeMark<Scalar<S, Z>> for NonZero

type Out = Option<Scalar<S, NonZero>>

The result type of marking T with Self

fn change_mark(scalar: Scalar<S, Z>) -> Self::Out

Marks item with Self.

impl<Z, S> ChangeMark<Scalar<S, Z>> for Zero

type Out = Scalar<S, Zero>

The result type of marking T with Self

fn change_mark(scalar: Scalar<S, Z>) -> Self::Out

Marks item with Self.

impl<Z, S, SNew: Secrecy> ChangeMark<Scalar<S, Z>> for SNew

type Out = Scalar<SNew, Z>

The result type of marking T with Self

fn change_mark(scalar: Scalar<S, Z>) -> Self::Out

Marks item with Self.

impl<S: Clone, Z: Clone> Clone for Scalar<S, Z>

fn clone(&self) -> Scalar<S, Z>

Returns a copy of the value.

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

Performs copy-assignment from source.

impl<Z, S> Debug for Scalar<S, Z>

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

Formats the type as hex and any markers on the type.

impl<S> Default for Scalar<S, Zero> where
    S: Secrecy, 

fn default() -> Self

Returns the “default value” for a type.

impl<S> Default for Scalar<S, NonZero> where
    S: Secrecy, 

fn default() -> Self

Returns the “default value” for a type.

impl<'de, S> Deserialize<'de> for Scalar<S, NonZero>

fn deserialize<Deser: Deserializer<'de>>(
    deserializer: Deser
) -> Result<Scalar<S, NonZero>, Deser::Error>

Deserialize this value from the given Serde deserializer.

impl<'de, S> Deserialize<'de> for Scalar<S, Zero>

fn deserialize<Deser: Deserializer<'de>>(
    deserializer: Deser
) -> Result<Scalar<S, Zero>, Deser::Error>

Deserialize this value from the given Serde deserializer.

impl<Z, S> Display for Scalar<S, Z>

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

Displays as hex.

impl From<Scalar<Secret, NonZero>> for SecretKey

fn from(scalar: Scalar) -> Self

Performs the conversion.

impl From<SecretKey> for Scalar

fn from(sk: SecretKey) -> Self

Performs the conversion.

impl From<u32> for Scalar<Secret, Zero>

fn from(int: u32) -> Self

Performs the conversion.

impl<S> FromStr for Scalar<S, NonZero>

fn from_str(hex: &str) -> Result<Scalar<S, NonZero>, HexError>

Parses the string as hex and interprets tries to convert the resulting byte array into the desired value.

type Err = HexError

The associated error which can be returned from parsing.

impl<S> FromStr for Scalar<S, Zero>

fn from_str(hex: &str) -> Result<Scalar<S, Zero>, HexError>

Parses the string as hex and interprets tries to convert the resulting byte array into the desired value.

type Err = HexError

The associated error which can be returned from parsing.

impl<Z> Hash for Scalar<Public, Z>

fn hash<H: Hasher>(&self, state: &mut H)

Feeds this value into the given Hasher.

fn hash_slice<H>(data: &[Self], state: &mut H) where
    H: Hasher, 

Feeds a slice of this type into the given Hasher.

impl<S, Z> HashInto for Scalar<S, Z>

fn hash_into(self, hash: &mut impl Digest)

Asks the item to convert itself to bytes and add itself to hash.

impl<S, Z> Neg for Scalar<S, Z>

type Output = Scalar<S, Z>

The resulting type after applying the - operator.

fn neg(self) -> Self::Output

Performs the unary - operation.

impl<S, Z> Neg for &Scalar<S, Z>

type Output = Scalar<S, Z>

The resulting type after applying the - operator.

fn neg(self) -> Self::Output

Performs the unary - operation.

impl<Z1, Z2, S1, S2> PartialEq<Scalar<S2, Z2>> for Scalar<S1, Z1>

fn eq(&self, rhs: &Scalar<S2, Z2>) -> 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<Z, S> Serialize for Scalar<S, Z>

fn serialize<Ser: Serializer>(
    &self,
    serializer: Ser
) -> Result<Ser::Ok, Ser::Error>

Serialize this value into the given Serde serializer.

impl<Z: Clone> Copy for Scalar<Public, Z>

impl<S: Eq, Z: Eq> Eq for Scalar<S, Z>

impl<S, Z> StructuralEq for Scalar<S, Z>