Struct secp256kfun::Scalar

pub struct Scalar<S = Secret, Z = NonZero>(/* private fields */);

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 from_bytes(bytes: [u8; 32]) -> Option<Self>

where Z: ZeroChoice,

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. If the scalar is marked NonZero then it will also return None it it’s the zero scalar.

Example

use secp256kfun::{marker::*, Scalar};
assert!(Scalar::<Secret, Zero>::from_bytes([0u8; 32]).is_some());
// NonZero scalar's can't be zero
assert!(Scalar::<Secret, NonZero>::from_bytes([0u8; 32]).is_none());
// >= curve order
assert!(Scalar::<Secret, Zero>::from_bytes([255u8; 32]).is_none());

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

where Z: ZeroChoice,

Decode a 32 byte long slice to a scalar.

Essentially from_bytes but checks that the slice is 32 bytes long first.

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>

Set the secrecy of the Scalar to the type parameter.

pub fn public(self) -> Scalar<Public, Z>

Set the secrecy of the Scalar to Public.

A scalar should be set to public when the adversary is meant to know it as part of the protocol.

pub fn secret(self) -> Scalar<Secret, Z>

Set the secrecy of the Scalar to Secret.

A scalar should be set to secret when the adversary is not meant to know about it in the protocol.

pub fn mark_zero(self) -> Scalar<S, Zero>

Mark the scalar as possibly being Zero (even though it isn’t).

This is useful in accumulator variables where although the initial value is non-zero, every sum addition after that might make it zero so it’s necessary to start off with Zero marked scalar.

impl<S> Scalar<S, NonZero>

pub fn invert(&self) -> Self

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

Example

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

pub fn one() -> Self

Returns the integer 1 as a Scalar.

pub fn minus_one() -> Self

Returns the integer -1 (modulo the curve order) as a Scalar.

pub fn mark_zero_choice<Z: ZeroChoice>(self) -> Scalar<S, Z>

Marks a scalar non-zero scalar as having the zero choice Z (rather than NonZero).

Useful when writing code that preserves the zero choice of the caller.

Example

use secp256kfun::{marker::*, s, Scalar};

/// Returns an iterator of 1, x, x², x³ ...
fn powers<S: Secrecy, Z: ZeroChoice>(x: Scalar<S, Z>) -> impl Iterator<Item = Scalar<S, Z>> {
    core::iter::successors(Some(Scalar::one().mark_zero_choice::<Z>()), move |xpow| {
        Some(s!(xpow * x).set_secrecy())
    })
}

assert_eq!(powers(s!(2)).take(4).collect::<Vec<_>>(), vec![
    s!(1),
    s!(2),
    s!(4),
    s!(8)
]);
assert_eq!(powers(s!(0)).take(4).collect::<Vec<_>>(), vec![
    s!(1).mark_zero(),
    s!(0),
    s!(0),
    s!(0)
]);

impl Scalar<Secret, NonZero>

pub fn random<R: RngCore>(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>.

impl<S> Scalar<S, Zero>

pub fn non_zero(self) -> Option<Scalar<S, NonZero>>

Converts a scalar marked with Zero to NonZero.

Returns None in the case that the scalar was in fact zero.

pub fn zero() -> Self

Returns the zero scalar.

Example

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

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, marker::*, s, Scalar};
let scalar = Scalar::<Secret, _>::from_bytes_mod_order(*b"xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx");
assert_eq!(scalar.to_bytes(), *b"xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx");
let scalar_overflowed = Scalar::<Secret, _>::from_bytes_mod_order(
    hex::decode_array("FFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFEBAAEDCE6AF48A03BBFD25E8CD0364142")
        .unwrap(),
);
assert_eq!(scalar_overflowed, s!(1))

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

use secp256kfun::{marker::*, Scalar};
let bytes = b"xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx";
assert!(Scalar::<Secret, _>::from_slice_mod_order(&bytes[..31]).is_none());
assert_eq!(
    Scalar::<Secret, _>::from_slice_mod_order(&bytes[..]).unwrap(),
    Scalar::<Secret, _>::from_bytes_mod_order(*bytes)
);

Trait Implementations

impl<SL, SR, ZR> AddAssign<&Scalar<SR, ZR>> for Scalar<SL, Zero>

fn add_assign(&mut self, rhs: &Scalar<SR, ZR>)

Performs the += operation.

impl<SL, SR, ZR> AddAssign<Scalar<SR, ZR>> for Scalar<SL, Zero>

fn add_assign(&mut self, rhs: Scalar<SR, ZR>)

Performs the += operation.

impl<S: Secrecy> Arbitrary for Scalar<S, NonZero>

type Parameters = ()

The type of parameters that arbitrary_with accepts for configuration of the generated Strategy. Parameters must implement Default.

type Strategy = BoxedStrategy<Scalar<S>>

The type of Strategy used to generate values of type Self.

fn arbitrary_with(_: Self::Parameters) -> Self::Strategy

Generates a Strategy for producing arbitrary values of type the implementing type (Self). The strategy is passed the arguments given in args.

fn arbitrary() -> Self::Strategy

Generates a Strategy for producing arbitrary values of type the implementing type (Self).

impl<S: Secrecy> Arbitrary for Scalar<S, Zero>

type Parameters = ()

The type of parameters that arbitrary_with accepts for configuration of the generated Strategy. Parameters must implement Default.

type Strategy = BoxedStrategy<Scalar<S, Zero>>

The type of Strategy used to generate values of type Self.

fn arbitrary_with(_: Self::Parameters) -> Self::Strategy

Generates a Strategy for producing arbitrary values of type the implementing type (Self). The strategy is passed the arguments given in args.

fn arbitrary() -> Self::Strategy

Generates a Strategy for producing arbitrary values of type the implementing type (Self).

impl<'de, S, Z: ZeroChoice> BorrowDecode<'de> for Scalar<S, Z>

Available on crate feature bincode only.

fn borrow_decode<D: BorrowDecoder<'de>>( decoder: &mut D ) -> Result<Self, DecodeError>

Attempt to decode this type with the given BorrowDecode.

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

fn clone(&self) -> Self

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, Z: ZeroChoice> Decode for Scalar<S, Z>

Available on crate feature bincode only.

fn decode<D: Decoder>(decoder: &mut D) -> Result<Self, DecodeError>

Attempt to decode this type with the given Decode.

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

where S: Secrecy,

fn default() -> Self

Returns the “default value” for a type.

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

where S: Secrecy,

fn default() -> Self

Returns the “default value” for a type.

impl<'de, S, Z: ZeroChoice> Deserialize<'de> for Scalar<S, Z>

Available on crate feature serde only.

fn deserialize<Deser: Deserializer<'de>>( deserializer: Deser ) -> Result<Scalar<S, Z>, 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<Z, S> Encode for Scalar<S, Z>

Available on crate feature bincode only.

fn encode<E: Encoder>(&self, encoder: &mut E) -> Result<(), EncodeError>

Encode a given type.

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

fn from(value: Scalar<Public, Z>) -> Self

Converts to this type from the input type.

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

fn from(value: Scalar<Public, Z>) -> Self

Converts to this type from the input type.

impl From<Scalar> for Scalar<Public, Zero>

fn from(value: Scalar) -> Self

Converts to this type from the input type.

impl From<Scalar> for Scalar<Public, Zero>

fn from(value: Scalar) -> Self

Converts to this type from the input type.

impl From<Scalar> for SecretKey

fn from(scalar: Scalar) -> Self

Converts to this type from the input type.

impl From<Scalar> for SecretKey

fn from(scalar: Scalar) -> Self

Converts to this type from the input type.

impl From<SecretKey> for Scalar

fn from(sk: SecretKey) -> Self

Converts to this type from the input type.

impl From<SecretKey> for Scalar

fn from(sk: SecretKey) -> Self

Converts to this type from the input type.

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

fn from(int: u32) -> Self

Converts to this type from the input type.

impl<S, Z: ZeroChoice> FromStr for Scalar<S, Z>

fn from_str(hex: &str) -> Result<Scalar<S, Z>, 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, Self: Sized,

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<SL, SR> MulAssign<&Scalar<SR>> for Scalar<SL, NonZero>

fn mul_assign(&mut self, rhs: &Scalar<SR, NonZero>)

Performs the *= operation.

impl<SL, SR, ZR: ZeroChoice> MulAssign<&Scalar<SR, ZR>> for Scalar<SL, Zero>

fn mul_assign(&mut self, rhs: &Scalar<SR, ZR>)

Performs the *= operation.

impl<SL, SR> MulAssign<Scalar<SR>> for Scalar<SL, NonZero>

fn mul_assign(&mut self, rhs: Scalar<SR, NonZero>)

Performs the *= operation.

impl<SL, SR, ZR: ZeroChoice> MulAssign<Scalar<SR, ZR>> for Scalar<SL, Zero>

fn mul_assign(&mut self, rhs: Scalar<SR, ZR>)

Performs the *= 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<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<Z> Ord for Scalar<Public, Z>

fn cmp(&self, other: &Self) -> Ordering

This method returns an Ordering between self and other.

fn max(self, other: Self) -> Self

where Self: Sized,

Compares and returns the maximum of two values.

fn min(self, other: Self) -> Self

where Self: Sized,

Compares and returns the minimum of two values.

fn clamp(self, min: Self, max: Self) -> Self

where Self: Sized + PartialOrd,

Restrict a value to a certain interval.

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 !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl<Z1, Z2> PartialOrd<Scalar<Public, Z2>> for Scalar<Public, Z1>

fn partial_cmp(&self, other: &Scalar<Public, Z2>) -> Option<Ordering>

This method returns an ordering between self and other values if one exists.

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

This method tests less than (for self and other) and is used by the < operator.

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

This method tests less than or equal to (for self and other) and is used by the <= operator.

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

This method tests greater than (for self and other) and is used by the > operator.

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

This method tests greater than or equal to (for self and other) and is used by the >= operator.

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

Available on crate feature serde only.

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

Serialize this value into the given Serde serializer.

impl<SL, SR, ZR> SubAssign<&Scalar<SR, ZR>> for Scalar<SL, Zero>

fn sub_assign(&mut self, rhs: &Scalar<SR, ZR>)

Performs the -= operation.

impl<SL, SR, ZR> SubAssign<Scalar<SR, ZR>> for Scalar<SL, Zero>

fn sub_assign(&mut self, rhs: Scalar<SR, ZR>)

Performs the -= operation.

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

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