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

#include <ec_scalar.h>

Public Member Functions

void _const_time_poison () const
void _const_time_unpoison () const
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_Group group () const
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_Scalar & operator= (const EC_Scalar &other)
EC_Scalar & operator= (EC_Scalar &&other) noexcept
template<concepts::resizable_byte_buffer T = std::vector<uint8_t>>
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_Scalar > deserialize (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 142 of file ec_scalar.cpp.

142 {
143 m_scalar = group._data()->scalar_deserialize(bytes);
144 if(!m_scalar) {
145 throw Decoding_Error("EC_Scalar::from_bytes is not a valid scalar value");
146 }
147}
size_t bytes() const
Definition ec_scalar.cpp:60
EC_Group group() const
Definition ec_scalar.cpp:56

References bytes(), and group().

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)

Copy constructor

Parameters
otherthe scalar to copy

Definition at line 31 of file ec_scalar.cpp.

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

References EC_Scalar().

◆ EC_Scalar() [3/3]

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

Move constructor

Parameters
otherthe scalar to move from

Definition at line 33 of file ec_scalar.cpp.

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

References EC_Scalar().

◆ ~EC_Scalar()

Botan::EC_Scalar::~EC_Scalar ( )
default

Member Function Documentation

◆ _const_time_poison()

void Botan::EC_Scalar::_const_time_poison ( ) const

Mark this scalar as holding secret data

Warning
this is an implementation detail which is not for public use and not covered by SemVer.

Definition at line 19 of file ec_scalar.cpp.

19 {
20 m_scalar->_const_time_poison();
21}

◆ _const_time_unpoison()

void Botan::EC_Scalar::_const_time_unpoison ( ) const

Mark this scalar as no longer holding secret data

Warning
this is an implementation detail which is not for public use and not covered by SemVer.

Definition at line 23 of file ec_scalar.cpp.

23 {
24 m_scalar->_const_time_unpoison();
25}

◆ _from_inner()

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

For internal use only

Parameters
innerthe inner representation to wrap
Returns
a scalar wrapping the provided inner representation

Definition at line 15 of file ec_scalar.cpp.

15 {
16 return EC_Scalar(std::move(inner));
17}
EC_Scalar(const EC_Group &group, std::span< const uint8_t > bytes)

References EC_Scalar().

◆ _inner()

const EC_Scalar_Data & Botan::EC_Scalar::_inner ( ) const
inline

◆ add()

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

Scalar addition (modulo group order)

Definition at line 169 of file ec_scalar.cpp.

169 {
170 BOTAN_ARG_CHECK(inner().group() == x.inner().group(), "Curve mismatch");
171 return EC_Scalar(inner().add(x.inner()));
172}
#define BOTAN_ARG_CHECK(expr, msg)
Definition assert.h:33
EC_Scalar add(const EC_Scalar &x) const

References add(), BOTAN_ARG_CHECK, EC_Scalar(), group(), and Botan::EC_Scalar_Data::group().

Referenced by add(), and operator+.

◆ assign()

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

Assign a scalar

Definition at line 184 of file ec_scalar.cpp.

184 {
185 if(this != &x) {
186 if(m_scalar == nullptr || m_scalar->group() != x.inner().group()) {
187 m_scalar = x.inner().clone();
188 } else {
189 m_scalar->assign(x.inner());
190 }
191 }
192}

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

Referenced by operator=().

◆ bytes()

size_t Botan::EC_Scalar::bytes ( ) const

Return the byte size of this scalar

Definition at line 60 of file ec_scalar.cpp.

60 {
61 return m_scalar->bytes();
62}

Referenced by 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 134 of file ec_scalar.cpp.

134 {
135 if(auto v = group._data()->scalar_deserialize(bytes)) {
136 return EC_Scalar(std::move(v));
137 } else {
138 return {};
139 }
140}

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

Referenced by Botan::SPAKE2p::RegistrationRecord::deserialize(), deserialize_pair(), and Botan::EC_PrivateKey_Data::EC_PrivateKey_Data().

◆ 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 116 of file ec_scalar.cpp.

117 {
118 if(bytes.size() % 2 != 0) {
119 return {};
120 }
121
122 const size_t half = bytes.size() / 2;
123
124 auto r = EC_Scalar::deserialize(group, bytes.first(half));
125 auto s = EC_Scalar::deserialize(group, bytes.last(half));
126
127 if(r && s) {
128 return std::make_pair(r.value(), s.value());
129 } else {
130 return {};
131 }
132}
static std::optional< EC_Scalar > deserialize(const EC_Group &group, std::span< const uint8_t > bytes)

References bytes(), deserialize(), and group().

Referenced by Botan::SPAKE2p::ProverSecret::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 84 of file ec_scalar.cpp.

84 {
85 if(auto data = group._data()->scalar_from_bigint(bn)) {
86 return EC_Scalar(std::move(data));
87 } else {
88 throw Invalid_Argument("EC_Scalar::from_bigint input out of range");
89 }
90}

References EC_Scalar(), and group().

Referenced by botan_ec_scalar_from_mp(), 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 68 of file ec_scalar.cpp.

68 {
69 if(auto s = group._data()->scalar_from_bytes_mod_order(bytes)) {
70 return EC_Scalar(std::move(s));
71 } else {
72 throw Decoding_Error("EC_Scalar::from_bytes_mod_order input invalid");
73 }
74}

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

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 64 of file ec_scalar.cpp.

64 {
65 return EC_Scalar(group._data()->scalar_from_bytes_with_trunc(bytes));
66}

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

◆ 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 99 of file ec_scalar.cpp.

99 {
100 const auto& group = scalar._inner().group();
101 return EC_Scalar(group->gk_x_mod_order(scalar.inner(), rng));
102}

References _inner(), EC_Scalar(), group(), 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

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.

Parameters
scalarthe scalar k to multiply the base point by
Random Number Generatorsa random number generator, used for blinding
Returns
the x coordinate of g*k reduced modulo the group order

Definition at line 119 of file ec_scalar.h.

119 {
120 return EC_Scalar::gk_x_mod_order(scalar, rng);
121 }
static EC_Scalar gk_x_mod_order(const EC_Scalar &scalar, RandomNumberGenerator &rng)
Definition ec_scalar.cpp:99

References EC_Scalar(), and gk_x_mod_order().

◆ group()

EC_Group Botan::EC_Scalar::group ( ) const

Return the elliptic curve group this scalar is associated with

Definition at line 56 of file ec_scalar.cpp.

56 {
57 return EC_Group(inner().group());
58}

References group().

Referenced by add(), deserialize(), deserialize_pair(), EC_Scalar(), from_bigint(), from_bytes_mod_order(), from_bytes_with_trunc(), gk_x_mod_order(), group(), hash(), is_eq(), mul(), one(), random(), and sub().

◆ 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 207 of file ec_scalar.cpp.

210 {
211 /*
212 RFC 9380 Section 5.2
213 L = ceil((ceil(log2(p)) + k) / 8), where k is the security
214 parameter of the suite (e.g., k = 128)
215 */
216 const size_t scalar_bits = group.get_order_bits();
217 const size_t security_level = std::min<size_t>((scalar_bits + 1) / 2, 256);
218 secure_vector<uint8_t> uniform_bytes((scalar_bits + security_level + 7) / 8);
219
220 h2c_expand_message(hash_fn, scalar_bits, input, domain_sep)(uniform_bytes);
221
222 return EC_Scalar::from_bytes_mod_order(group, uniform_bytes);
223}
static EC_Scalar from_bytes_mod_order(const EC_Group &group, std::span< const uint8_t > bytes)
Definition ec_scalar.cpp:68
std::function< void(std::span< uint8_t >)> h2c_expand_message(std::string_view hash_fn, size_t order_bits, std::span< const uint8_t > input, std::span< const uint8_t > domain_sep)
std::vector< T, secure_allocator< T > > secure_vector
Definition secmem.h:128

References EC_Scalar(), from_bytes_mod_order(), group(), and Botan::h2c_expand_message().

◆ 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 153 of file ec_scalar.cpp.

153 {
154 return EC_Scalar(inner().invert());
155}
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 157 of file ec_scalar.cpp.

157 {
158 return EC_Scalar(inner().invert_vartime());
159}
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 198 of file ec_scalar.cpp.

198 {
199 if(inner().group() != x.inner().group()) {
200 return false;
201 }
202
203 return inner().is_eq(x.inner());
204}

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

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 175 of file ec_scalar.h.

175{ 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 149 of file ec_scalar.cpp.

149 {
150 return inner().is_zero();
151}

Referenced by is_nonzero().

◆ mul()

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

Scalar multiplication (modulo group order)

Definition at line 179 of file ec_scalar.cpp.

179 {
180 BOTAN_ARG_CHECK(inner().group() == x.inner().group(), "Curve mismatch");
181 return EC_Scalar(inner().mul(x.inner()));
182}
EC_Scalar mul(const EC_Scalar &x) const

References BOTAN_ARG_CHECK, EC_Scalar(), group(), Botan::EC_Scalar_Data::group(), and mul().

Referenced by mul(), and operator*.

◆ negate()

EC_Scalar Botan::EC_Scalar::negate ( ) const

Return the additive inverse of *this

Definition at line 161 of file ec_scalar.cpp.

161 {
162 return EC_Scalar(inner().negate());
163}
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 80 of file ec_scalar.cpp.

80 {
81 return EC_Scalar(group._data()->scalar_one());
82}

References EC_Scalar(), and group().

◆ operator=() [1/2]

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

Copy assignment

Parameters
otherthe scalar to copy
Returns
reference to this

Definition at line 35 of file ec_scalar.cpp.

35 {
36 if(this != &other) {
37 if(m_scalar == nullptr || m_scalar->group() != other.inner().group()) {
38 m_scalar = other.inner().clone();
39 } else {
40 this->assign(other);
41 }
42 }
43 return (*this);
44}
void assign(const EC_Scalar &x)

References assign(), Botan::EC_Scalar_Data::clone(), EC_Scalar(), and Botan::EC_Scalar_Data::group().

◆ operator=() [2/2]

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

Move assignment

Parameters
otherthe scalar to move from
Returns
reference to this

Definition at line 46 of file ec_scalar.cpp.

46 {
47 if(this != &other) {
48 // Even a cross-curve swap is accepted here
49 std::swap(m_scalar, other.m_scalar);
50 }
51 return (*this);
52}

References EC_Scalar().

◆ random()

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

◆ 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 144 of file ec_scalar.h.

144 {
145 T s(this->bytes());
146 this->serialize_to(s);
147 return s;
148 }
void serialize_to(std::span< uint8_t > bytes) const

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 161 of file ec_scalar.h.

161 {
162 T bytes(r.bytes() + s.bytes());
164 return bytes;
165 }
static void serialize_pair_to(std::span< uint8_t > bytes, const EC_Scalar &r, const EC_Scalar &s)

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

Referenced by Botan::SPAKE2p::ProverSecret::serialize().

◆ 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 108 of file ec_scalar.cpp.

108 {
109 BOTAN_ARG_CHECK(r._inner().group() == s._inner().group(), "Curve mismatch");
110 const size_t scalar_bytes = r.bytes();
111 BOTAN_ARG_CHECK(bytes.size() == 2 * scalar_bytes, "Invalid output length");
112 r.serialize_to(bytes.first(scalar_bytes));
113 s.serialize_to(bytes.last(scalar_bytes));
114}

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 104 of file ec_scalar.cpp.

104 {
105 inner().serialize_to(bytes);
106}

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 165 of file ec_scalar.cpp.

165 {
166 m_scalar->square_self();
167}

◆ sub()

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

Scalar subtraction (modulo group order)

Definition at line 174 of file ec_scalar.cpp.

174 {
175 BOTAN_ARG_CHECK(inner().group() == x.inner().group(), "Curve mismatch");
176 return EC_Scalar(inner().sub(x.inner()));
177}
EC_Scalar sub(const EC_Scalar &x) const

References BOTAN_ARG_CHECK, EC_Scalar(), group(), Botan::EC_Scalar_Data::group(), and sub().

Referenced by operator-, and sub().

◆ to_bigint()

BigInt Botan::EC_Scalar::to_bigint ( ) const

Convert *this to a BigInt

Definition at line 92 of file ec_scalar.cpp.

92 {
93 secure_vector<uint8_t> bytes(m_scalar->bytes());
94 m_scalar->serialize_to(bytes);
96}
static BigInt from_bytes(std::span< const uint8_t > bytes)
Definition bigint.cpp:84

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 194 of file ec_scalar.cpp.

194 {
195 m_scalar->zeroize();
196}

◆ EC_AffinePoint

friend class EC_AffinePoint
friend

Definition at line 308 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 246 of file ec_scalar.h.

246{ 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 242 of file ec_scalar.h.

242{ 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 244 of file ec_scalar.h.

244{ return x.sub(y); }

References EC_Scalar(), and sub().

◆ operator==

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

Definition at line 248 of file ec_scalar.h.

248{ return x.is_eq(y); }

References EC_Scalar(), and is_eq().


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