Botan 3.8.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 <vector>
16
17namespace Botan {
18
19class BigInt;
21class EC_Group;
22class EC_Group_Data;
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 * Convert a bytestring to an EC_Scalar
59 *
60 * This is similar to deserialize but instead of returning nullopt if the input
61 * is invalid, it will throw an exception.
62 */
63 BOTAN_DEPRECATED("Use EC_Scalar::deserialize") EC_Scalar(const EC_Group& group, std::span<const uint8_t> bytes);
64
65 /**
66 * Deserialize a pair of scalars
67 *
68 * Returns nullopt if the length is not 2*bytes(), or if either scalar is
69 * out of range or zero
70 */
71 static std::optional<std::pair<EC_Scalar, EC_Scalar>> deserialize_pair(const EC_Group& group,
72 std::span<const uint8_t> bytes);
73
74 /**
75 * Return a new random scalar value
76 */
77 static EC_Scalar random(const EC_Group& group, RandomNumberGenerator& rng);
78
79 /**
80 * Return the scalar value 1
81 */
82 static EC_Scalar one(const EC_Group& group);
83
84 /**
85 * Convert from the argument BigInt to a EC_Scalar
86 *
87 * Throws an exception if the provided bn is negative or too large
88 */
89 static EC_Scalar from_bigint(const EC_Group& group, const BigInt& bn);
90
91 /**
92 * Compute the elliptic curve scalar multiplication (g*k) where g is the
93 * standard base point on the curve. Then extract the x coordinate of
94 * the resulting point, and reduce it modulo the group order.
95 */
96 static EC_Scalar gk_x_mod_order(const EC_Scalar& scalar, RandomNumberGenerator& rng);
97
98 BOTAN_DEPRECATED("Use version without workspace arg")
99 static EC_Scalar gk_x_mod_order(const EC_Scalar& scalar, RandomNumberGenerator& rng, std::vector<BigInt>&) {
100 return EC_Scalar::gk_x_mod_order(scalar, rng);
101 }
102
103 /**
104 * Return the byte size of this scalar
105 */
106 size_t bytes() const;
107
108 /**
109 * Write the fixed length serialization to bytes
110 *
111 * The provided span must be exactly bytes() long
112 */
113 void serialize_to(std::span<uint8_t> bytes) const;
114
115 /**
116 * Return the bytes of the encoded scalar in a container
117 */
118 template <concepts::resizable_byte_buffer T = std::vector<uint8_t>>
119 T serialize() const {
120 T s(this->bytes());
121 this->serialize_to(s);
122 return s;
123 }
124
125 /**
126 * Write the fixed length serialization to bytes
127 *
128 * The provided span must be exactly 2*bytes() long
129 */
130 static void serialize_pair_to(std::span<uint8_t> bytes, const EC_Scalar& r, const EC_Scalar& s);
131
132 /**
133 * Return the bytes of the encoded scalar in a container
134 */
135 template <concepts::resizable_byte_buffer T = std::vector<uint8_t>>
136 static T serialize_pair(const EC_Scalar& r, const EC_Scalar& s) {
137 T bytes(r.bytes() + s.bytes());
139 return bytes;
140 }
141
142 /**
143 * Return true if this EC_Scalar is zero
144 */
145 bool is_zero() const;
146
147 /**
148 * Return true if this EC_Scalar is not zero
149 */
150 bool is_nonzero() const { return !is_zero(); }
151
152 /**
153 * Constant time modular inversion
154 *
155 * Return the modular inverse of this EC_Scalar
156 *
157 * If *this is zero, then invert() returns zero
158 */
159 EC_Scalar invert() const;
160
161 /**
162 * Variable time modular inversion
163 *
164 * Return the modular inverse of this EC_Scalar
165 *
166 * If *this is zero, then invert_vartime() returns zero
167 */
168 EC_Scalar invert_vartime() const;
169
170 /**
171 * Return the additive inverse of *this
172 */
173 EC_Scalar negate() const;
174
175 /**
176 * Scalar addition (modulo group order)
177 */
178 EC_Scalar add(const EC_Scalar& x) const;
179
180 /**
181 * Scalar subtraction (modulo group order)
182 */
183 EC_Scalar sub(const EC_Scalar& x) const;
184
185 /**
186 * Scalar multiplication (modulo group order)
187 */
188 EC_Scalar mul(const EC_Scalar& x) const;
189
190 /**
191 * Assign a scalar
192 */
193 void assign(const EC_Scalar& x);
194
195 /**
196 * Set *this to its own square modulo the group order
197 */
198 void square_self();
199
200 /**
201 * Test for equality
202 */
203 bool is_eq(const EC_Scalar& x) const;
204
205 /**
206 * Convert *this to a BigInt
207 */
208 BigInt to_bigint() const;
209
210 friend EC_Scalar operator+(const EC_Scalar& x, const EC_Scalar& y) { return x.add(y); }
211
212 friend EC_Scalar operator-(const EC_Scalar& x, const EC_Scalar& y) { return x.sub(y); }
213
214 friend EC_Scalar operator*(const EC_Scalar& x, const EC_Scalar& y) { return x.mul(y); }
215
216 friend bool operator==(const EC_Scalar& x, const EC_Scalar& y) { return x.is_eq(y); }
217
218 EC_Scalar(const EC_Scalar& other);
219 EC_Scalar(EC_Scalar&& other) noexcept;
220
221 EC_Scalar& operator=(const EC_Scalar& other);
222 EC_Scalar& operator=(EC_Scalar&& other) noexcept;
223
225
226 const EC_Scalar_Data& _inner() const { return inner(); }
227
228 static EC_Scalar _from_inner(std::unique_ptr<EC_Scalar_Data> inner);
229
230 private:
231 friend class EC_AffinePoint;
232
233 EC_Scalar(std::unique_ptr<EC_Scalar_Data> scalar);
234
235 const EC_Scalar_Data& inner() const { return *m_scalar; }
236
237 std::unique_ptr<EC_Scalar_Data> m_scalar;
238};
239
240} // namespace Botan
241
242#endif
#define BOTAN_PUBLIC_API(maj, min)
Definition api.h:19
#define BOTAN_DEPRECATED(msg)
Definition api.h:59
static EC_Scalar one(const EC_Group &group)
Definition ec_scalar.cpp:61
const EC_Scalar_Data & _inner() const
Definition ec_scalar.h:226
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:214
static EC_Scalar gk_x_mod_order(const EC_Scalar &scalar, RandomNumberGenerator &rng)
Definition ec_scalar.cpp:79
void serialize_to(std::span< uint8_t > bytes) const
Definition ec_scalar.cpp:84
bool is_zero() const
size_t bytes() const
Definition ec_scalar.cpp:41
static EC_Scalar from_bigint(const EC_Group &group, const BigInt &bn)
Definition ec_scalar.cpp:65
static T serialize_pair(const EC_Scalar &r, const EC_Scalar &s)
Definition ec_scalar.h:136
T serialize() const
Definition ec_scalar.h:119
friend EC_Scalar operator+(const EC_Scalar &x, const EC_Scalar &y)
Definition ec_scalar.h:210
static void serialize_pair_to(std::span< uint8_t > bytes, const EC_Scalar &r, const EC_Scalar &s)
Definition ec_scalar.cpp:88
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:216
static EC_Scalar from_bytes_mod_order(const EC_Group &group, std::span< const uint8_t > bytes)
Definition ec_scalar.cpp:49
bool is_nonzero() const
Definition ec_scalar.h:150
static EC_Scalar random(const EC_Group &group, RandomNumberGenerator &rng)
Definition ec_scalar.cpp:57
EC_Scalar sub(const EC_Scalar &x) const
friend EC_Scalar operator-(const EC_Scalar &x, const EC_Scalar &y)
Definition ec_scalar.h:212
static std::optional< std::pair< EC_Scalar, EC_Scalar > > deserialize_pair(const EC_Group &group, std::span< const uint8_t > bytes)
Definition ec_scalar.cpp:96
friend class EC_AffinePoint
Definition ec_scalar.h:231
static EC_Scalar from_bytes_with_trunc(const EC_Group &group, std::span< const uint8_t > bytes)
Definition ec_scalar.cpp:45