Botan 3.9.0
Crypto and TLS for C&
Botan::EC_Scalar Class Referencefinal

#include <ec_scalar.h>

Public Member Functions

const EC_Scalar_Data_inner () const
EC_Scalar add (const EC_Scalar &x) const
void assign (const EC_Scalar &x)
size_t bytes () const
 EC_Scalar (const EC_Group &group, std::span< const uint8_t > bytes)
 EC_Scalar (const EC_Scalar &other)
 EC_Scalar (EC_Scalar &&other) noexcept
EC_Scalar invert () const
EC_Scalar invert_vartime () const
bool is_eq (const EC_Scalar &x) const
bool is_nonzero () const
bool is_zero () const
EC_Scalar mul (const EC_Scalar &x) const
EC_Scalar negate () const
EC_Scalaroperator= (const EC_Scalar &other)
EC_Scalaroperator= (EC_Scalar &&other) noexcept
template<concepts::resizable_byte_buffer T = std::vector<uint8_t>>
serialize () const
void serialize_to (std::span< uint8_t > bytes) const
void square_self ()
EC_Scalar sub (const EC_Scalar &x) const
BigInt to_bigint () const
void zeroize ()
 ~EC_Scalar ()

Static Public Member Functions

static EC_Scalar _from_inner (std::unique_ptr< EC_Scalar_Data > inner)
static std::optional< EC_Scalardeserialize (const EC_Group &group, std::span< const uint8_t > bytes)
static std::optional< std::pair< EC_Scalar, EC_Scalar > > deserialize_pair (const EC_Group &group, std::span< const uint8_t > bytes)
static EC_Scalar from_bigint (const EC_Group &group, const BigInt &bn)
static EC_Scalar from_bytes_mod_order (const EC_Group &group, std::span< const uint8_t > bytes)
static EC_Scalar from_bytes_with_trunc (const EC_Group &group, std::span< const uint8_t > bytes)
static EC_Scalar gk_x_mod_order (const EC_Scalar &scalar, RandomNumberGenerator &rng)
static EC_Scalar gk_x_mod_order (const EC_Scalar &scalar, RandomNumberGenerator &rng, std::vector< BigInt > &)
static EC_Scalar hash (const EC_Group &group, std::string_view hash_fn, std::span< const uint8_t > input, std::span< const uint8_t > domain_sep)
static EC_Scalar one (const EC_Group &group)
static EC_Scalar random (const EC_Group &group, RandomNumberGenerator &rng)
template<concepts::resizable_byte_buffer T = std::vector<uint8_t>>
static T serialize_pair (const EC_Scalar &r, const EC_Scalar &s)
static void serialize_pair_to (std::span< uint8_t > bytes, const EC_Scalar &r, const EC_Scalar &s)

Friends

class EC_AffinePoint
EC_Scalar operator* (const EC_Scalar &x, const EC_Scalar &y)
EC_Scalar operator+ (const EC_Scalar &x, const EC_Scalar &y)
EC_Scalar operator- (const EC_Scalar &x, const EC_Scalar &y)
bool operator== (const EC_Scalar &x, const EC_Scalar &y)

Detailed Description

Represents an integer modulo the prime group order of an elliptic curve

Definition at line 28 of file ec_scalar.h.

Constructor & Destructor Documentation

◆ EC_Scalar() [1/3]

Botan::EC_Scalar::EC_Scalar ( const EC_Group & group,
std::span< const uint8_t > bytes )

Convert a bytestring to an EC_Scalar

This is similar to deserialize but instead of returning nullopt if the input is invalid, it will throw an exception.

Definition at line 126 of file ec_scalar.cpp.

126 {
127 m_scalar = group._data()->scalar_deserialize(bytes);
128 if(!m_scalar) {
129 throw Decoding_Error("EC_Scalar::from_bytes is not a valid scalar value");
130 }
131}
size_t bytes() const
Definition ec_scalar.cpp:45

References Botan::EC_Group::_data(), and bytes().

Referenced by _from_inner(), add(), assign(), deserialize(), EC_AffinePoint, EC_Scalar(), EC_Scalar(), from_bigint(), from_bytes_mod_order(), from_bytes_with_trunc(), gk_x_mod_order(), gk_x_mod_order(), hash(), invert(), invert_vartime(), is_eq(), mul(), negate(), one(), operator*, operator+, operator-, operator=(), operator=(), operator==, random(), serialize_pair(), serialize_pair_to(), and sub().

◆ EC_Scalar() [2/3]

Botan::EC_Scalar::EC_Scalar ( const EC_Scalar & other)

Definition at line 26 of file ec_scalar.cpp.

26: m_scalar(other.inner().clone()) {}

References EC_Scalar().

◆ EC_Scalar() [3/3]

Botan::EC_Scalar::EC_Scalar ( EC_Scalar && other)
noexcept

Definition at line 28 of file ec_scalar.cpp.

28: m_scalar(std::move(other.m_scalar)) {}

References EC_Scalar().

◆ ~EC_Scalar()

Botan::EC_Scalar::~EC_Scalar ( )
default

Member Function Documentation

◆ _from_inner()

EC_Scalar Botan::EC_Scalar::_from_inner ( std::unique_ptr< EC_Scalar_Data > inner)
static

Definition at line 18 of file ec_scalar.cpp.

18 {
19 return EC_Scalar(std::move(inner));
20}
EC_Scalar(const EC_Group &group, std::span< const uint8_t > bytes)

References EC_Scalar().

◆ _inner()

◆ add()

EC_Scalar Botan::EC_Scalar::add ( const EC_Scalar & x) const

Scalar addition (modulo group order)

Definition at line 153 of file ec_scalar.cpp.

153 {
154 return EC_Scalar(inner().add(x.inner()));
155}
EC_Scalar add(const EC_Scalar &x) const

References add(), and EC_Scalar().

Referenced by add(), and operator+.

◆ assign()

void Botan::EC_Scalar::assign ( const EC_Scalar & x)

Assign a scalar

Definition at line 165 of file ec_scalar.cpp.

165 {
166 m_scalar->assign(x.inner());
167}

References EC_Scalar().

Referenced by operator=().

◆ bytes()

size_t Botan::EC_Scalar::bytes ( ) const

Return the byte size of this scalar

Definition at line 45 of file ec_scalar.cpp.

45 {
46 return m_scalar->bytes();
47}

References bytes().

Referenced by bytes(), deserialize(), deserialize_pair(), EC_Scalar(), from_bytes_mod_order(), from_bytes_with_trunc(), serialize_pair(), serialize_pair_to(), serialize_to(), and to_bigint().

◆ deserialize()

std::optional< EC_Scalar > Botan::EC_Scalar::deserialize ( const EC_Group & group,
std::span< const uint8_t > bytes )
static

Deserialize a scalar

The span must be exactly bytes() long; this function does not accept either short inputs (eg [1] to encode the integer 1) or inputs with excess leading zero bytes.

Returns nullopt if the length is incorrect or if the integer is not within the range [0,n) where n is the group order.

Definition at line 118 of file ec_scalar.cpp.

118 {
119 if(auto v = group._data()->scalar_deserialize(bytes)) {
120 return EC_Scalar(std::move(v));
121 } else {
122 return {};
123 }
124}

References Botan::EC_Group::_data(), bytes(), and EC_Scalar().

Referenced by deserialize_pair().

◆ deserialize_pair()

std::optional< std::pair< EC_Scalar, EC_Scalar > > Botan::EC_Scalar::deserialize_pair ( const EC_Group & group,
std::span< const uint8_t > bytes )
static

Deserialize a pair of scalars

Returns nullopt if the length is not 2*bytes(), or if either scalar is out of range or zero

Definition at line 100 of file ec_scalar.cpp.

101 {
102 if(bytes.size() % 2 != 0) {
103 return {};
104 }
105
106 const size_t half = bytes.size() / 2;
107
108 auto r = EC_Scalar::deserialize(group, bytes.first(half));
109 auto s = EC_Scalar::deserialize(group, bytes.last(half));
110
111 if(r && s) {
112 return std::make_pair(r.value(), s.value());
113 } else {
114 return {};
115 }
116}
static std::optional< EC_Scalar > deserialize(const EC_Group &group, std::span< const uint8_t > bytes)

References bytes(), and deserialize().

◆ from_bigint()

EC_Scalar Botan::EC_Scalar::from_bigint ( const EC_Group & group,
const BigInt & bn )
static

Convert from the argument BigInt to a EC_Scalar

Throws an exception if the provided bn is negative or too large

Definition at line 69 of file ec_scalar.cpp.

69 {
70 if(auto data = group._data()->scalar_from_bigint(bn)) {
71 return EC_Scalar(std::move(data));
72 } else {
73 throw Invalid_Argument("EC_Scalar::from_bigint input out of range");
74 }
75}

References Botan::EC_Group::_data(), and EC_Scalar().

Referenced by Botan::EC_Group::cube_mod_order(), Botan::ECIES_KA_Operation::derive_secret(), Botan::EC_PrivateKey::EC_PrivateKey(), Botan::EC_Group::inverse_mod_order(), Botan::EC_Group::multiply_mod_order(), Botan::EC_Group::multiply_mod_order(), and Botan::EC_Group::square_mod_order().

◆ from_bytes_mod_order()

EC_Scalar Botan::EC_Scalar::from_bytes_mod_order ( const EC_Group & group,
std::span< const uint8_t > bytes )
static

Convert a bytestring to an EC_Scalar

This reduces the bytes modulo the group order. The input can be at most 2*bytes() long

Definition at line 53 of file ec_scalar.cpp.

53 {
54 if(auto s = group._data()->scalar_from_bytes_mod_order(bytes)) {
55 return EC_Scalar(std::move(s));
56 } else {
57 throw Decoding_Error("EC_Scalar::from_bytes_mod_order input invalid");
58 }
59}

References Botan::EC_Group::_data(), bytes(), and EC_Scalar().

Referenced by hash(), and Botan::EC_Group::mod_order().

◆ from_bytes_with_trunc()

EC_Scalar Botan::EC_Scalar::from_bytes_with_trunc ( const EC_Group & group,
std::span< const uint8_t > bytes )
static

Convert a bytestring to an EC_Scalar

This uses the truncation rules from ECDSA

Definition at line 49 of file ec_scalar.cpp.

49 {
50 return EC_Scalar(group._data()->scalar_from_bytes_with_trunc(bytes));
51}

References Botan::EC_Group::_data(), bytes(), and EC_Scalar().

◆ gk_x_mod_order() [1/2]

EC_Scalar Botan::EC_Scalar::gk_x_mod_order ( const EC_Scalar & scalar,
RandomNumberGenerator & rng )
static

Compute the elliptic curve scalar multiplication (g*k) where g is the standard base point on the curve. Then extract the x coordinate of the resulting point, and reduce it modulo the group order.

Definition at line 83 of file ec_scalar.cpp.

83 {
84 const auto& group = scalar._inner().group();
85 return EC_Scalar(group->gk_x_mod_order(scalar.inner(), rng));
86}

References _inner(), EC_Scalar(), and Botan::EC_Scalar_Data::group().

Referenced by gk_x_mod_order().

◆ gk_x_mod_order() [2/2]

EC_Scalar Botan::EC_Scalar::gk_x_mod_order ( const EC_Scalar & scalar,
RandomNumberGenerator & rng,
std::vector< BigInt > &  )
inlinestatic

Definition at line 110 of file ec_scalar.h.

110 {
111 return EC_Scalar::gk_x_mod_order(scalar, rng);
112 }
static EC_Scalar gk_x_mod_order(const EC_Scalar &scalar, RandomNumberGenerator &rng)
Definition ec_scalar.cpp:83

References EC_Scalar(), and gk_x_mod_order().

◆ hash()

EC_Scalar Botan::EC_Scalar::hash ( const EC_Group & group,
std::string_view hash_fn,
std::span< const uint8_t > input,
std::span< const uint8_t > domain_sep )
static

Hash to scalar following RFC 9380

This requires XMD. Unlike hash2curve, any group is supported

Definition at line 178 of file ec_scalar.cpp.

181 {
182#if defined(BOTAN_HAS_XMD)
183
184 /*
185 * This could be extended to support expand_message_xof or a MHF like Argon2
186 */
187 if(hash_fn.starts_with("SHAKE")) {
188 throw Not_Implemented("Hash to scalar currently does not support expand_message_xof");
189 }
190
191 const size_t scalar_bits = group.get_order_bits();
192 const size_t security_level = (scalar_bits + 1) / 2;
193 secure_vector<uint8_t> uniform_bytes((scalar_bits + security_level + 7) / 8);
194 expand_message_xmd(hash_fn, uniform_bytes, input, domain_sep);
195
196 return EC_Scalar::from_bytes_mod_order(group, uniform_bytes);
197#else
198 BOTAN_UNUSED(group, hash_fn, input, domain_sep);
199 throw Not_Implemented("EC_Scalar::hash not available due to missing XMD");
200#endif
201}
#define BOTAN_UNUSED
Definition assert.h:144
static EC_Scalar from_bytes_mod_order(const EC_Group &group, std::span< const uint8_t > bytes)
Definition ec_scalar.cpp:53
void expand_message_xmd(std::string_view hash_fn, std::span< uint8_t > output, std::span< const uint8_t > input, std::span< const uint8_t > domain_sep)
Definition xmd.cpp:17
std::vector< T, secure_allocator< T > > secure_vector
Definition secmem.h:69

References BOTAN_UNUSED, EC_Scalar(), Botan::expand_message_xmd(), from_bytes_mod_order(), and Botan::EC_Group::get_order_bits().

◆ invert()

EC_Scalar Botan::EC_Scalar::invert ( ) const

Constant time modular inversion

Return the modular inverse of this EC_Scalar

If *this is zero, then invert() returns zero

Definition at line 137 of file ec_scalar.cpp.

137 {
138 return EC_Scalar(inner().invert());
139}
EC_Scalar invert() const

References EC_Scalar(), and invert().

Referenced by invert().

◆ invert_vartime()

EC_Scalar Botan::EC_Scalar::invert_vartime ( ) const

Variable time modular inversion

Return the modular inverse of this EC_Scalar

If *this is zero, then invert_vartime() returns zero

Definition at line 141 of file ec_scalar.cpp.

141 {
142 return EC_Scalar(inner().invert_vartime());
143}
EC_Scalar invert_vartime() const

References EC_Scalar(), and invert_vartime().

Referenced by invert_vartime().

◆ is_eq()

bool Botan::EC_Scalar::is_eq ( const EC_Scalar & x) const

Test for equality

Definition at line 173 of file ec_scalar.cpp.

173 {
174 return inner().is_eq(x.inner());
175}

References EC_Scalar().

Referenced by operator==.

◆ is_nonzero()

bool Botan::EC_Scalar::is_nonzero ( ) const
inline

Return true if this EC_Scalar is not zero

Definition at line 161 of file ec_scalar.h.

161{ return !is_zero(); }
bool is_zero() const

References is_zero().

◆ is_zero()

bool Botan::EC_Scalar::is_zero ( ) const

Return true if this EC_Scalar is zero

Definition at line 133 of file ec_scalar.cpp.

133 {
134 return inner().is_zero();
135}

Referenced by is_nonzero().

◆ mul()

EC_Scalar Botan::EC_Scalar::mul ( const EC_Scalar & x) const

Scalar multiplication (modulo group order)

Definition at line 161 of file ec_scalar.cpp.

161 {
162 return EC_Scalar(inner().mul(x.inner()));
163}
EC_Scalar mul(const EC_Scalar &x) const

References EC_Scalar(), and mul().

Referenced by mul(), and operator*.

◆ negate()

EC_Scalar Botan::EC_Scalar::negate ( ) const

Return the additive inverse of *this

Definition at line 145 of file ec_scalar.cpp.

145 {
146 return EC_Scalar(inner().negate());
147}
EC_Scalar negate() const

References EC_Scalar(), and negate().

Referenced by negate().

◆ one()

EC_Scalar Botan::EC_Scalar::one ( const EC_Group & group)
static

Return the scalar value 1

Definition at line 65 of file ec_scalar.cpp.

65 {
66 return EC_Scalar(group._data()->scalar_one());
67}

References Botan::EC_Group::_data(), and EC_Scalar().

◆ operator=() [1/2]

EC_Scalar & Botan::EC_Scalar::operator= ( const EC_Scalar & other)

Definition at line 30 of file ec_scalar.cpp.

30 {
31 if(this != &other) {
32 this->assign(other);
33 }
34 return (*this);
35}
void assign(const EC_Scalar &x)

References assign(), and EC_Scalar().

◆ operator=() [2/2]

EC_Scalar & Botan::EC_Scalar::operator= ( EC_Scalar && other)
noexcept

Definition at line 37 of file ec_scalar.cpp.

37 {
38 BOTAN_ARG_CHECK(_inner().group() == other._inner().group(), "Curve mismatch");
39 std::swap(m_scalar, other.m_scalar);
40 return (*this);
41}
#define BOTAN_ARG_CHECK(expr, msg)
Definition assert.h:33
virtual const std::shared_ptr< const EC_Group_Data > & group() const =0
const EC_Scalar_Data & _inner() const
Definition ec_scalar.h:244

References _inner(), BOTAN_ARG_CHECK, and EC_Scalar().

◆ random()

EC_Scalar Botan::EC_Scalar::random ( const EC_Group & group,
RandomNumberGenerator & rng )
static

Return a new random scalar value

Definition at line 61 of file ec_scalar.cpp.

61 {
62 return EC_Scalar(group._data()->scalar_random(rng));
63}

References Botan::EC_Group::_data(), and EC_Scalar().

Referenced by Botan::EC_PrivateKey::EC_PrivateKey(), and Botan::EC_PrivateKey::EC_PrivateKey().

◆ serialize()

template<concepts::resizable_byte_buffer T = std::vector<uint8_t>>
T Botan::EC_Scalar::serialize ( ) const
inline

Return the bytes of the encoded scalar in a container

Definition at line 130 of file ec_scalar.h.

130 {
131 T s(this->bytes());
132 this->serialize_to(s);
133 return s;
134 }
void serialize_to(std::span< uint8_t > bytes) const
Definition ec_scalar.cpp:88

References serialize_to().

◆ serialize_pair()

template<concepts::resizable_byte_buffer T = std::vector<uint8_t>>
T Botan::EC_Scalar::serialize_pair ( const EC_Scalar & r,
const EC_Scalar & s )
inlinestatic

Return the bytes of the encoded scalar in a container

Definition at line 147 of file ec_scalar.h.

147 {
148 T bytes(r.bytes() + s.bytes());
150 return bytes;
151 }
static void serialize_pair_to(std::span< uint8_t > bytes, const EC_Scalar &r, const EC_Scalar &s)
Definition ec_scalar.cpp:92

References bytes(), EC_Scalar(), and serialize_pair_to().

◆ serialize_pair_to()

void Botan::EC_Scalar::serialize_pair_to ( std::span< uint8_t > bytes,
const EC_Scalar & r,
const EC_Scalar & s )
static

Write the fixed length serialization to bytes

The provided span must be exactly 2*bytes() long

Definition at line 92 of file ec_scalar.cpp.

92 {
93 BOTAN_ARG_CHECK(r._inner().group() == s._inner().group(), "Curve mismatch");
94 const size_t scalar_bytes = r.bytes();
95 BOTAN_ARG_CHECK(bytes.size() == 2 * scalar_bytes, "Invalid output length");
96 r.serialize_to(bytes.first(scalar_bytes));
97 s.serialize_to(bytes.last(scalar_bytes));
98}

References _inner(), BOTAN_ARG_CHECK, bytes(), EC_Scalar(), Botan::EC_Scalar_Data::group(), and serialize_to().

Referenced by serialize_pair().

◆ serialize_to()

void Botan::EC_Scalar::serialize_to ( std::span< uint8_t > bytes) const

Write the fixed length serialization to bytes

The provided span must be exactly bytes() long

Definition at line 88 of file ec_scalar.cpp.

88 {
89 inner().serialize_to(bytes);
90}

References bytes().

Referenced by serialize(), and serialize_pair_to().

◆ square_self()

void Botan::EC_Scalar::square_self ( )

Set *this to its own square modulo the group order

Definition at line 149 of file ec_scalar.cpp.

149 {
150 m_scalar->square_self();
151}

◆ sub()

EC_Scalar Botan::EC_Scalar::sub ( const EC_Scalar & x) const

Scalar subtraction (modulo group order)

Definition at line 157 of file ec_scalar.cpp.

157 {
158 return EC_Scalar(inner().sub(x.inner()));
159}
EC_Scalar sub(const EC_Scalar &x) const

References EC_Scalar(), and sub().

Referenced by operator-, and sub().

◆ to_bigint()

BigInt Botan::EC_Scalar::to_bigint ( ) const

Convert *this to a BigInt

Definition at line 77 of file ec_scalar.cpp.

77 {
78 secure_vector<uint8_t> bytes(m_scalar->bytes());
79 m_scalar->serialize_to(bytes);
81}
static BigInt from_bytes(std::span< const uint8_t > bytes)
Definition bigint.cpp:87

References bytes(), and Botan::BigInt::from_bytes().

◆ zeroize()

void Botan::EC_Scalar::zeroize ( )

Equivalent to assigning a zero value, but also does so in a way that attempts to ensure the write always occurs even if a compiler can deduce the assignment is otherwise unnecessary.

Definition at line 169 of file ec_scalar.cpp.

169 {
170 m_scalar->zeroize();
171}

◆ EC_AffinePoint

friend class EC_AffinePoint
friend

Definition at line 249 of file ec_scalar.h.

References EC_AffinePoint, and EC_Scalar().

Referenced by EC_AffinePoint.

◆ operator*

EC_Scalar operator* ( const EC_Scalar & x,
const EC_Scalar & y )
friend

Definition at line 232 of file ec_scalar.h.

232{ return x.mul(y); }

References EC_Scalar(), and mul().

◆ operator+

EC_Scalar operator+ ( const EC_Scalar & x,
const EC_Scalar & y )
friend

Definition at line 228 of file ec_scalar.h.

228{ return x.add(y); }

References add(), and EC_Scalar().

◆ operator-

EC_Scalar operator- ( const EC_Scalar & x,
const EC_Scalar & y )
friend

Definition at line 230 of file ec_scalar.h.

230{ return x.sub(y); }

References EC_Scalar(), and sub().

◆ operator==

bool operator== ( const EC_Scalar & x,
const EC_Scalar & y )
friend

Definition at line 234 of file ec_scalar.h.

234{ return x.is_eq(y); }

References EC_Scalar(), and is_eq().


The documentation for this class was generated from the following files: