Botan 3.14.1
Crypto and TLS for C&
ec_scalar.h
Go to the documentation of this file.
1/*
2* (C) 2024 Jack Lloyd
3*
4* Botan is released under the Simplified BSD License (see license.txt)
5*/
6
7#ifndef BOTAN_EC_SCALAR_H_
8#define BOTAN_EC_SCALAR_H_
9
10#include <botan/concepts.h>
11#include <botan/types.h>
12#include <memory>
13#include <optional>
14#include <span>
15#include <string_view>
16#include <vector>
17
18namespace Botan {
19
20class BigInt;
22class EC_Group;
23class EC_Scalar_Data;
24
25/**
26* Represents an integer modulo the prime group order of an elliptic curve
27*/
28class BOTAN_PUBLIC_API(3, 6) EC_Scalar final {
29 public:
30 /**
31 * Deserialize a scalar
32 *
33 * The span must be exactly bytes() long; this function does not accept
34 * either short inputs (eg [1] to encode the integer 1) or inputs with
35 * excess leading zero bytes.
36 *
37 * Returns nullopt if the length is incorrect or if the integer is not
38 * within the range [0,n) where n is the group order.
39 */
40 static std::optional<EC_Scalar> deserialize(const EC_Group& group, std::span<const uint8_t> bytes);
41
42 /**
43 * Convert a bytestring to an EC_Scalar
44 *
45 * This uses the truncation rules from ECDSA
46 */
47 static EC_Scalar from_bytes_with_trunc(const EC_Group& group, std::span<const uint8_t> bytes);
48
49 /**
50 * Convert a bytestring to an EC_Scalar
51 *
52 * This reduces the bytes modulo the group order. The input can be at most
53 * 2*bytes() long
54 */
55 static EC_Scalar from_bytes_mod_order(const EC_Group& group, std::span<const uint8_t> bytes);
56
57 /**
58 * Hash to scalar following RFC 9380
59 *
60 * This requires XMD. Unlike hash2curve, any group is supported
61 */
62 static EC_Scalar hash(const EC_Group& group,
63 std::string_view hash_fn,
64 std::span<const uint8_t> input,
65 std::span<const uint8_t> domain_sep);
66
67 /**
68 * Convert a bytestring to an EC_Scalar
69 *
70 * This is similar to deserialize but instead of returning nullopt if the input
71 * is invalid, it will throw an exception.
72 */
73 BOTAN_DEPRECATED("Use EC_Scalar::deserialize") EC_Scalar(const EC_Group& group, std::span<const uint8_t> bytes);
74
75 /**
76 * Deserialize a pair of scalars
77 *
78 * Returns nullopt if the length is not 2*bytes(), or if either scalar is
79 * out of range or zero
80 */
81 static std::optional<std::pair<EC_Scalar, EC_Scalar>> deserialize_pair(const EC_Group& group,
82 std::span<const uint8_t> bytes);
83
84 /**
85 * Return a new random scalar value
86 */
88
89 /**
90 * Return the scalar value 1
91 */
92 static EC_Scalar one(const EC_Group& group);
93
94 /**
95 * Convert from the argument BigInt to a EC_Scalar
96 *
97 * Throws an exception if the provided bn is negative or too large
98 */
99 static EC_Scalar from_bigint(const EC_Group& group, const BigInt& bn);
100
101 /**
102 * Compute the elliptic curve scalar multiplication (g*k) where g is the
103 * standard base point on the curve. Then extract the x coordinate of
104 * the resulting point, and reduce it modulo the group order.
105 */
106 static EC_Scalar gk_x_mod_order(const EC_Scalar& scalar, RandomNumberGenerator& rng);
107
108 /**
109 * Compute the elliptic curve scalar multiplication (g*k) where g is the
110 * standard base point on the curve. Then extract the x coordinate of
111 * the resulting point, and reduce it modulo the group order.
112 *
113 * @param scalar the scalar k to multiply the base point by
114 * @param rng a random number generator, used for blinding
115 * @return the x coordinate of g*k reduced modulo the group order
116 */
117 BOTAN_DEPRECATED("Use version without workspace arg")
118 static EC_Scalar
119 gk_x_mod_order(const EC_Scalar& scalar, RandomNumberGenerator& rng, std::vector<BigInt>& /*ws*/) {
120 return EC_Scalar::gk_x_mod_order(scalar, rng);
121 }
122
123 /**
124 * Return the elliptic curve group this scalar is associated with
125 */
126 EC_Group group() const;
127
128 /**
129 * Return the byte size of this scalar
130 */
131 size_t bytes() const;
132
133 /**
134 * Write the fixed length serialization to bytes
135 *
136 * The provided span must be exactly bytes() long
137 */
138 void serialize_to(std::span<uint8_t> bytes) const;
139
140 /**
141 * Return the bytes of the encoded scalar in a container
142 */
143 template <concepts::resizable_byte_buffer T = std::vector<uint8_t>>
144 T serialize() const {
145 T s(this->bytes());
146 this->serialize_to(s);
147 return s;
148 }
149
150 /**
151 * Write the fixed length serialization to bytes
152 *
153 * The provided span must be exactly 2*bytes() long
154 */
155 static void serialize_pair_to(std::span<uint8_t> bytes, const EC_Scalar& r, const EC_Scalar& s);
156
157 /**
158 * Return the bytes of the encoded scalar in a container
159 */
160 template <concepts::resizable_byte_buffer T = std::vector<uint8_t>>
161 static T serialize_pair(const EC_Scalar& r, const EC_Scalar& s) {
162 T bytes(r.bytes() + s.bytes());
164 return bytes;
165 }
166
167 /**
168 * Return true if this EC_Scalar is zero
169 */
170 bool is_zero() const;
171
172 /**
173 * Return true if this EC_Scalar is not zero
174 */
175 bool is_nonzero() const { return !is_zero(); }
176
177 /**
178 * Constant time modular inversion
179 *
180 * Return the modular inverse of this EC_Scalar
181 *
182 * If *this is zero, then invert() returns zero
183 */
184 EC_Scalar invert() const;
185
186 /**
187 * Variable time modular inversion
188 *
189 * Return the modular inverse of this EC_Scalar
190 *
191 * If *this is zero, then invert_vartime() returns zero
192 */
193 EC_Scalar invert_vartime() const;
194
195 /**
196 * Return the additive inverse of *this
197 */
198 EC_Scalar negate() const;
199
200 /**
201 * Scalar addition (modulo group order)
202 */
203 EC_Scalar add(const EC_Scalar& x) const;
204
205 /**
206 * Scalar subtraction (modulo group order)
207 */
208 EC_Scalar sub(const EC_Scalar& x) const;
209
210 /**
211 * Scalar multiplication (modulo group order)
212 */
213 EC_Scalar mul(const EC_Scalar& x) const;
214
215 /**
216 * Assign a scalar
217 */
218 void assign(const EC_Scalar& x);
219
220 /**
221 * Equivalent to assigning a zero value, but also does so in a way that
222 * attempts to ensure the write always occurs even if a compiler can deduce
223 * the assignment is otherwise unnecessary.
224 */
225 void zeroize();
226
227 /**
228 * Set *this to its own square modulo the group order
229 */
230 void square_self();
231
232 /**
233 * Test for equality
234 */
235 bool is_eq(const EC_Scalar& x) const;
236
237 /**
238 * Convert *this to a BigInt
239 */
240 BigInt to_bigint() const;
241
242 friend EC_Scalar operator+(const EC_Scalar& x, const EC_Scalar& y) { return x.add(y); }
243
244 friend EC_Scalar operator-(const EC_Scalar& x, const EC_Scalar& y) { return x.sub(y); }
245
246 friend EC_Scalar operator*(const EC_Scalar& x, const EC_Scalar& y) { return x.mul(y); }
247
248 friend bool operator==(const EC_Scalar& x, const EC_Scalar& y) { return x.is_eq(y); }
249
250 /**
251 * Copy constructor
252 * @param other the scalar to copy
253 */
254 EC_Scalar(const EC_Scalar& other);
255
256 /**
257 * Move constructor
258 * @param other the scalar to move from
259 */
260 EC_Scalar(EC_Scalar&& other) noexcept;
261
262 /**
263 * Copy assignment
264 * @param other the scalar to copy
265 * @return reference to this
266 */
267 EC_Scalar& operator=(const EC_Scalar& other);
268
269 /**
270 * Move assignment
271 * @param other the scalar to move from
272 * @return reference to this
273 */
274 EC_Scalar& operator=(EC_Scalar&& other) noexcept;
275
277
278 /**
279 * For internal use only
280 * @return the inner representation of this scalar
281 */
282 const EC_Scalar_Data& _inner() const { return inner(); }
283
284 /**
285 * For internal use only
286 * @param inner the inner representation to wrap
287 * @return a scalar wrapping the provided inner representation
288 */
289 static EC_Scalar _from_inner(std::unique_ptr<EC_Scalar_Data> inner);
290
291 /**
292 * Mark this scalar as holding secret data
293 *
294 * @warning this is an implementation detail which is not for
295 * public use and not covered by SemVer.
296 */
297 void _const_time_poison() const;
298
299 /**
300 * Mark this scalar as no longer holding secret data
301 *
302 * @warning this is an implementation detail which is not for
303 * public use and not covered by SemVer.
304 */
305 void _const_time_unpoison() const;
306
307 private:
308 friend class EC_AffinePoint;
309
310 explicit EC_Scalar(std::unique_ptr<EC_Scalar_Data> scalar);
311
312 const EC_Scalar_Data& inner() const { return *m_scalar; }
313
314 std::unique_ptr<EC_Scalar_Data> m_scalar;
315};
316
317} // namespace Botan
318
319#endif
#define BOTAN_PUBLIC_API(maj, min)
Definition api.h:21
#define BOTAN_DEPRECATED(msg)
Definition api.h:73
static EC_Scalar one(const EC_Group &group)
Definition ec_scalar.cpp:80
const EC_Scalar_Data & _inner() const
Definition ec_scalar.h:282
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)
bool is_eq(const EC_Scalar &x) const
static std::optional< EC_Scalar > deserialize(const EC_Group &group, std::span< const uint8_t > bytes)
EC_Scalar mul(const EC_Scalar &x) const
EC_Scalar add(const EC_Scalar &x) const
friend EC_Scalar operator*(const EC_Scalar &x, const EC_Scalar &y)
Definition ec_scalar.h:246
static EC_Scalar gk_x_mod_order(const EC_Scalar &scalar, RandomNumberGenerator &rng)
Definition ec_scalar.cpp:99
static EC_Scalar gk_x_mod_order(const EC_Scalar &scalar, RandomNumberGenerator &rng, std::vector< BigInt > &)
Definition ec_scalar.h:119
void serialize_to(std::span< uint8_t > bytes) const
bool is_zero() const
size_t bytes() const
Definition ec_scalar.cpp:60
static EC_Scalar from_bigint(const EC_Group &group, const BigInt &bn)
Definition ec_scalar.cpp:84
static T serialize_pair(const EC_Scalar &r, const EC_Scalar &s)
Definition ec_scalar.h:161
T serialize() const
Definition ec_scalar.h:144
friend EC_Scalar operator+(const EC_Scalar &x, const EC_Scalar &y)
Definition ec_scalar.h:242
static void serialize_pair_to(std::span< uint8_t > bytes, const EC_Scalar &r, const EC_Scalar &s)
EC_Scalar(const EC_Group &group, std::span< const uint8_t > bytes)
friend bool operator==(const EC_Scalar &x, const EC_Scalar &y)
Definition ec_scalar.h:248
static EC_Scalar from_bytes_mod_order(const EC_Group &group, std::span< const uint8_t > bytes)
Definition ec_scalar.cpp:68
EC_Group group() const
Definition ec_scalar.cpp:56
bool is_nonzero() const
Definition ec_scalar.h:175
static EC_Scalar random(const EC_Group &group, RandomNumberGenerator &rng)
Definition ec_scalar.cpp:76
EC_Scalar sub(const EC_Scalar &x) const
friend EC_Scalar operator-(const EC_Scalar &x, const EC_Scalar &y)
Definition ec_scalar.h:244
static std::optional< std::pair< EC_Scalar, EC_Scalar > > deserialize_pair(const EC_Group &group, std::span< const uint8_t > bytes)
friend class EC_AffinePoint
Definition ec_scalar.h:308
static EC_Scalar from_bytes_with_trunc(const EC_Group &group, std::span< const uint8_t > bytes)
Definition ec_scalar.cpp:64