Struct Scalar 

pub struct Scalar { /* private fields */ }

Represents a non-zero scalar in the range [1, n) where n is the order of the secp256k1 curve. A Scalar can be:

• added, negated, subtracted, and multiplied with other Scalar instances.
• added, negated, subtracted, and multiplied with MaybeScalar.
• multiplied with Point.
• multiplied with MaybePoint.

…using the normal Rust arithemtic operators +, - and *. Such operations are commutative, i.e. a * b = b * a and a + b = b + a in call cases.

Depending on the types involved in an operation, certain operators will produce different result types which should be handled depending on your use case. For instance, adding two Scalars results in a MaybeScalar, because the two Scalars may be additive inverses of each other and their output would result in MaybeScalar::Zero when taken mod n.

Implementations

impl Scalar

pub fn one() -> Scalar

Returns a valid Scalar with a value of 1.

pub fn two() -> Scalar

Returns a valid Scalar with a value of two.

pub fn half_order() -> Scalar

Returns half of the curve order n, specifically n >> 1.

pub fn max() -> Scalar

Returns a valid Scalar with the maximum possible value less than the curve order, n - 1.

pub fn is_high(&self) -> Choice

Returns subtle::Choice::from(1) if this scalar is strictly greater than half the curve order; i.e if self > (n >> 1).

This is used to reduce malleability of ECDSA signatures, whose s values could be considered valid if they are either s or n - s. Converting the s value using Scalar::to_low and checking it using Scalar::is_high upon verification fixes this ambiguity.

Beware that leaking timing information about this bit may expose a bit of information about the scalar.

pub fn to_low(self) -> Scalar

If self.is_high(), this returns -self. Otherwise, returns the scalar unchanged.

This is used to reduce malleability of ECDSA signatures, whose s values could be considered valid if they are either s or n - s. Converting the s value using Scalar::to_low and checking it using Scalar::is_high upon verification fixes this ambiguity.

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

Generates a new random scalar from the given CSPRNG.

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

Serializes the scalar to a big-endian byte array representation.

Warning

Use cautiously. Non-constant time operations on these bytes could reveal secret key material.

pub fn from_slice(bytes: &[u8]) -> Result<Self, InvalidScalarBytes>

Parses a non-zero scalar in the range [1, n) from a given byte slice, which must be exactly 32-byte long and must represent the scalar in big-endian format.

pub fn from_hex(hex: &str) -> Result<Self, InvalidScalarString>

Parses a Scalar from a 32-byte hex string representation.

pub fn base_point_mul(&self) -> Point

Multiplies the secp256k1 base point by this scalar. This is how public keys (points) are derived from private keys (scalars). Since this scalar is non-zero, the point derived from base-point multiplication is also guaranteed to be valid.

pub fn negate_if(self, parity: Choice) -> Scalar

Negates the scalar in constant-time if the given parity bit is a 1.

pub fn invert(self) -> Scalar

Inverts a scalar modulo the curve order n in constant time. This outputs a scalar such that self * self.inverse() == Scalar::one() for all non-zero scalars.

pub fn reduce_from(z_bytes: &[u8; 32]) -> Self

Converts a 32-byte array into a Scalar by interpreting it as a big-endian integer z and returning (z % (n-1)) + 1, where n is the secp256k1 curve order. This always returns a valid non-zero scalar in the range [1, n). All operations are constant-time, except if z works out to be zero.

The probability that z_bytes represents an integer z larger than the curve order is only about 1 in 2^128, but nonetheless this function makes a best-effort attempt to parse all inputs in constant time and reduce them to an integer in the range [1, n).

Trait Implementations

impl Add<MaybeScalar> for Scalar

type Output = MaybeScalar

The resulting type after applying the + operator.

fn add(self, rhs: MaybeScalar) -> Self::Output

Performs the + operation.

impl Add<Scalar> for MaybeScalar

type Output = MaybeScalar

The resulting type after applying the + operator.

fn add(self, rhs: Scalar) -> Self::Output

Performs the + operation.

impl Add for Scalar

Scalar + Scalar

type Output = MaybeScalar

The resulting type after applying the + operator.

fn add(self, other: Scalar) -> Self::Output

Performs the + operation.

impl AddAssign<Scalar> for MaybeScalar

fn add_assign(&mut self, rhs: Scalar)

Performs the += operation.

impl AsRef<[u8]> for Scalar

fn as_ref(&self) -> &[u8]

Returns a reference to the underlying secret bytes of this scalar.

Warning

Use cautiously. Non-constant time operations on these bytes could reveal secret key material.

impl AsRef<[u8; 32]> for Scalar

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

Returns a reference to the underlying secret bytes of this scalar.

Warning

Use cautiously. Non-constant time operations on these bytes could reveal secret key material.

impl AsRef<SecretKey> for Scalar

fn as_ref(&self) -> &SecretKey

Converts this type into a shared reference of the (usually inferred) input type.

impl Bounded for Scalar

fn min_value() -> Self

Returns the smallest finite number this type can represent

fn max_value() -> Self

Returns the largest finite number this type can represent

impl Clone for Scalar

fn clone(&self) -> Scalar

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl ConditionallySelectable for Scalar

fn conditional_select(a: &Self, b: &Self, choice: Choice) -> Self

Conditionally selects one of two scalars in constant time. No timing information about the value of either scalar will be leaked.

fn conditional_assign(&mut self, other: &Self, choice: Choice)

Conditionally assign other to self, according to choice.

fn conditional_swap(a: &mut Self, b: &mut Self, choice: Choice)

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

impl ConstantTimeEq for Scalar

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

Compares this scalar against another in constant time. Returns subtle::Choice::from(1) if and only if the two scalars represent the same integer.

fn ct_ne(&self, other: &Self) -> Choice

Determine if two items are NOT equal.

impl ConstantTimeGreater for Scalar

fn ct_gt(&self, other: &Self) -> Choice

Compares this scalar against another in constant time. Returns subtle::Choice::from(1) if self is strictly lexicographically greater than other.

impl ConstantTimeLess for Scalar

fn ct_lt(&self, other: &Self) -> Choice

Determine whether self < other.

impl Debug for Scalar

This implementation was duplicated from the secp256k1 crate, because k256::NonZeroScalar doesn’t implement Debug.

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

Formats the value using the given formatter.

impl<'de> Deserialize<'de> for Scalar

fn deserialize<D: Deserializer<'de>>(deserializer: D) -> Result<Self, D::Error>

Deserialize this value from the given Serde deserializer.

impl Div<Scalar> for G

To divide by rhs, we simply multiply by rhs.inverse(), because rhs.inverse() is algebraically the same as 1 / rhs.

type Output = Point

The resulting type after applying the / operator.

fn div(self, rhs: Scalar) -> Self::Output

Performs the / operation.

impl Div<Scalar> for MaybePoint

type Output = MaybePoint

The resulting type after applying the / operator.

fn div(self, rhs: Scalar) -> Self::Output

Performs the / operation.

impl Div<Scalar> for MaybeScalar

type Output = MaybeScalar

The resulting type after applying the / operator.

fn div(self, rhs: Scalar) -> Self::Output

Performs the / operation.

impl Div<Scalar> for Point

To divide by rhs, we simply multiply by rhs.inverse(), because rhs.inverse() is algebraically the same as 1 / rhs.

type Output = Point

The resulting type after applying the / operator.

fn div(self, rhs: Scalar) -> Self::Output

Performs the / operation.

impl Div for Scalar

To divide by rhs, we simply multiply by rhs.inverse(), because rhs.inverse() is algebraically the same as 1 / rhs.

type Output = Scalar

The resulting type after applying the / operator.

fn div(self, rhs: Scalar) -> Self::Output

Performs the / operation.

impl DivAssign<Scalar> for MaybePoint

fn div_assign(&mut self, rhs: Scalar)

Performs the /= operation.

impl DivAssign<Scalar> for MaybeScalar

fn div_assign(&mut self, rhs: Scalar)

Performs the /= operation.

impl DivAssign<Scalar> for Point

fn div_assign(&mut self, rhs: Scalar)

Performs the /= operation.

impl DivAssign for Scalar

fn div_assign(&mut self, rhs: Scalar)

Performs the /= operation.

impl From<NonZeroScalar<Secp256k1>> for Scalar

fn from(nz_scalar: NonZeroScalar) -> Self

Converts to this type from the input type.

impl From<Scalar> for [u8; 32]

fn from(scalar: Scalar) -> Self

Serializes the scalar to a big-endian byte array representation.

impl From<Scalar> for MaybeScalar

fn from(scalar: Scalar) -> Self

Converts the scalar into a MaybeScalar::Valid instance.

impl From<Scalar> for NonZeroScalar

fn from(scalar: Scalar) -> Self

Converts to this type from the input type.

impl From<Scalar> for Scalar

fn from(scalar: Scalar) -> Self

Converts to this type from the input type.

impl From<Scalar> for Scalar

fn from(scalar: Scalar) -> Self

Converts to this type from the input type.

impl From<Scalar> for Scalar

fn from(scalar: Scalar) -> Self

Converts to this type from the input type.

impl From<Scalar> for SecretKey

fn from(scalar: Scalar) -> SecretKey

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<Secp256k1>> for Scalar

fn from(seckey: SecretKey) -> Self

Converts to this type from the input type.

impl From<SecretKey> for Scalar

fn from(inner: SecretKey) -> Self

Converts to this type from the input type.

impl FromStr for Scalar

fn from_str(s: &str) -> Result<Self, Self::Err>

Parses a Scalar from a 32-byte hex string representation.

type Err = InvalidScalarString

The associated error which can be returned from parsing.

impl Inv for Scalar

type Output = Scalar

The result after applying the operator.

fn inv(self) -> Self::Output

Returns the multiplicative inverse of self.

impl LowerHex for Scalar

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

Formats the scalar as a hex string in lower case.

Warning

This method may expose private data if the scalar represents a secret key.

impl Mul<G> for Scalar

Scalar * G

type Output = Point

The resulting type after applying the * operator.

fn mul(self, _: G) -> Self::Output

Performs the * operation.

impl Mul<MaybePoint> for Scalar

type Output = MaybePoint

The resulting type after applying the * operator.

fn mul(self, rhs: MaybePoint) -> Self::Output

Performs the * operation.

impl Mul<MaybeScalar> for Scalar

type Output = MaybeScalar

The resulting type after applying the * operator.

fn mul(self, rhs: MaybeScalar) -> Self::Output

Performs the * operation.

impl Mul<Point> for Scalar

Scalar * Point

type Output = Point

The resulting type after applying the * operator.

fn mul(self, point: Point) -> Self::Output

Performs the * operation.

impl Mul<Scalar> for G

G * Scalar

type Output = Point

The resulting type after applying the * operator.

fn mul(self, scalar: Scalar) -> Self::Output

Performs the * operation.

impl Mul<Scalar> for MaybePoint

type Output = MaybePoint

The resulting type after applying the * operator.

fn mul(self, rhs: Scalar) -> Self::Output

Performs the * operation.

impl Mul<Scalar> for MaybeScalar

type Output = MaybeScalar

The resulting type after applying the * operator.

fn mul(self, rhs: Scalar) -> Self::Output

Performs the * operation.

impl Mul<Scalar> for Point

Point * Scalar

type Output = Point

The resulting type after applying the * operator.

fn mul(self, scalar: Scalar) -> Self::Output

Performs the * operation.

impl Mul for Scalar

Note: Scalar * Scalar always outputs a non-zero Scalar.

type Output = Scalar

The resulting type after applying the * operator.

fn mul(self, other: Scalar) -> Self::Output

Performs the * operation.

impl MulAssign<Scalar> for MaybePoint

fn mul_assign(&mut self, rhs: Scalar)

Performs the *= operation.

impl MulAssign<Scalar> for MaybeScalar

fn mul_assign(&mut self, rhs: Scalar)

Performs the *= operation.

impl MulAssign<Scalar> for Point

fn mul_assign(&mut self, rhs: Scalar)

Performs the *= operation.

impl MulAssign for Scalar

fn mul_assign(&mut self, rhs: Scalar)

Performs the *= operation.

impl Neg for Scalar

-Scalar

type Output = Scalar

The resulting type after applying the - operator.

fn neg(self) -> Self::Output

Performs the unary - operation.

impl One for Scalar

fn one() -> Self

Returns the multiplicative identity element of Self, 1.

fn is_one(&self) -> bool

Returns true if self is equal to the multiplicative identity.

fn set_one(&mut self)

Sets self to the multiplicative identity element of Self, 1.

impl PartialEq for Scalar

fn eq(&self, other: &Scalar) -> bool

Tests for self and other values to be equal, and is used by ==.

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

Tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl Product for Scalar

This implementation allows iterators of Scalar to be multiplied together with Iterator::product.

Since all scalars in the iterator are guaranteed to be non-zero, the resulting product is also guaranteed to be non-zero.

use secp::Scalar;

let scalars = [
  Scalar::two(),
  Scalar::two(),
  Scalar::two(),
];
let expected = "0000000000000000000000000000000000000000000000000000000000000008"
    .parse::<Scalar>()
    .unwrap();

assert_eq!(scalars.into_iter().product::<Scalar>(), expected);

Returns Scalar::one() if the iterator is empty.

fn product<I: Iterator<Item = Scalar>>(iter: I) -> Self

Takes an iterator and generates Self from the elements by multiplying the items.

impl Serialize for Scalar

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

Serialize this value into the given Serde serializer.

impl Sub<MaybeScalar> for Scalar

type Output = MaybeScalar

The resulting type after applying the - operator.

fn sub(self, rhs: MaybeScalar) -> Self::Output

Performs the - operation.

impl Sub<Scalar> for MaybeScalar

type Output = MaybeScalar

The resulting type after applying the - operator.

fn sub(self, rhs: Scalar) -> Self::Output

Performs the - operation.

impl Sub for Scalar

type Output = MaybeScalar

The resulting type after applying the - operator.

fn sub(self, rhs: Scalar) -> Self::Output

Performs the - operation.

impl SubAssign<Scalar> for MaybeScalar

fn sub_assign(&mut self, rhs: Scalar)

Performs the -= operation.

impl TryFrom<&[u8]> for Scalar

fn try_from(bytes: &[u8]) -> Result<Self, Self::Error>

Attempts to parse a 32-byte slice as a scalar in the range [1, n) in constant time, where n is the curve order.

Returns InvalidScalarBytes if the integer represented by the bytes is greater than or equal to the curve order, or if the bytes are all zero.

Fails if bytes.len() != 32.

type Error = InvalidScalarBytes

The type returned in the event of a conversion error.

impl TryFrom<&[u8; 32]> for Scalar

fn try_from(bytes: &[u8; 32]) -> Result<Self, Self::Error>

Attempts to parse a 32-byte array as a scalar in the range [1, n) in constant time, where n is the curve order.

Returns InvalidScalarBytes if the integer represented by the bytes is greater than or equal to the curve order, or if the bytes are all zero.

type Error = InvalidScalarBytes

The type returned in the event of a conversion error.

impl TryFrom<[u8; 32]> for Scalar

fn try_from(bytes: [u8; 32]) -> Result<Self, Self::Error>

Attempts to parse a 32-byte array as a scalar in the range [1, n) in constant time, where n is the curve order.

Returns InvalidScalarBytes if the integer represented by the bytes is greater than or equal to the curve order, or if the bytes are all zero.

type Error = InvalidScalarBytes

The type returned in the event of a conversion error.

impl TryFrom<GenericArray<u8, <Secp256k1 as Curve>::FieldBytesSize>> for Scalar

fn try_from(bytes: FieldBytes) -> Result<Self, Self::Error>

Attempts to parse a 32-byte array as a scalar in the range [1, n) in constant time, where n is the curve order.

Returns InvalidScalarBytes if the integer represented by the bytes is greater than or equal to the curve order.

type Error = InvalidScalarBytes

The type returned in the event of a conversion error.

impl TryFrom<MaybeScalar> for Scalar

fn try_from(maybe_scalar: MaybeScalar) -> Result<Self, Self::Error>

Converts the MaybeScalar into a Result<Scalar, ZeroScalarError>, returning Ok(Scalar) if the scalar is a valid non-zero number, or Err(ZeroScalarError) if maybe_scalar == MaybeScalar::Zero.

type Error = ZeroScalarError

The type returned in the event of a conversion error.

impl TryFrom<Scalar> for Scalar

type Error = ZeroScalarError

The type returned in the event of a conversion error.

fn try_from(scalar: Scalar) -> Result<Self, Self::Error>

Performs the conversion.

impl TryFrom<u128> for Scalar

Converts any unsigned integer number into a Scalar. Returns ZeroScalarError if the integer is zero.

type Error = ZeroScalarError

The type returned in the event of a conversion error.

fn try_from(value: u128) -> Result<Self, Self::Error>

Performs the conversion.

impl UpperHex for Scalar

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

Formats the scalar as a hex string in upper case.

Warning

This method may expose private data if the scalar represents a secret key.

impl Copy for Scalar

impl Eq for Scalar

impl StructuralPartialEq for Scalar