Botan 3.14.1
Crypto and TLS for C&
ec_inner_data.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_INNER_DATA_H_
8#define BOTAN_EC_INNER_DATA_H_
9
10#include <botan/ec_group.h>
11
12#include <botan/asn1_obj.h>
13#include <botan/bigint.h>
14#include <botan/internal/monty.h>
15#include <functional>
16#include <memory>
17#include <span>
18
19#if defined(BOTAN_HAS_LEGACY_EC_POINT)
20 #include <botan/internal/barrett.h>
21#endif
22
23namespace Botan {
24
25#if defined(BOTAN_HAS_LEGACY_EC_POINT)
27#endif
28
29namespace PCurve {
30
31class PrimeOrderCurve;
32
33}
34
35class EC_Group_Data;
36
37class EC_Scalar_Data /* NOLINT(*-special-member-functions) */ {
38 public:
39 virtual ~EC_Scalar_Data() = default;
40
41 virtual const std::shared_ptr<const EC_Group_Data>& group() const = 0;
42
43 virtual size_t bytes() const = 0;
44
45 virtual std::unique_ptr<EC_Scalar_Data> clone() const = 0;
46
47 virtual bool is_zero() const = 0;
48
49 virtual bool is_eq(const EC_Scalar_Data& y) const = 0;
50
51 virtual void assign(const EC_Scalar_Data& y) = 0;
52
53 virtual void zeroize() = 0;
54
55 virtual void square_self() = 0;
56
57 virtual std::unique_ptr<EC_Scalar_Data> negate() const = 0;
58
59 virtual std::unique_ptr<EC_Scalar_Data> invert() const = 0;
60
61 virtual std::unique_ptr<EC_Scalar_Data> invert_vartime() const = 0;
62
63 virtual std::unique_ptr<EC_Scalar_Data> add(const EC_Scalar_Data& other) const = 0;
64
65 virtual std::unique_ptr<EC_Scalar_Data> sub(const EC_Scalar_Data& other) const = 0;
66
67 virtual std::unique_ptr<EC_Scalar_Data> mul(const EC_Scalar_Data& other) const = 0;
68
69 virtual void serialize_to(std::span<uint8_t> bytes) const = 0;
70
71 virtual void _const_time_poison() const = 0;
72
73 virtual void _const_time_unpoison() const = 0;
74};
75
76class EC_AffinePoint_Data /* NOLINT(*-special-member-functions) */ {
77 public:
78 virtual ~EC_AffinePoint_Data() = default;
79
80 virtual const std::shared_ptr<const EC_Group_Data>& group() const = 0;
81
82 virtual std::unique_ptr<EC_AffinePoint_Data> clone() const = 0;
83
84 // Return size of a field element
85 virtual size_t field_element_bytes() const = 0;
86
87 // Return if this is the identity element
88 virtual bool is_identity() const = 0;
89
90 // Writes 1 field element worth of data to bytes
91 virtual void serialize_x_to(std::span<uint8_t> bytes) const = 0;
92
93 // Writes 1 field element worth of data to bytes
94 virtual void serialize_y_to(std::span<uint8_t> bytes) const = 0;
95
96 // Writes 2 field elements worth of data to bytes
97 virtual void serialize_xy_to(std::span<uint8_t> bytes) const = 0;
98
99 // Writes 1 byte + 1 field element worth of data to bytes
100 virtual void serialize_compressed_to(std::span<uint8_t> bytes) const = 0;
101
102 // Writes 1 byte + 2 field elements worth of data to bytes
103 virtual void serialize_uncompressed_to(std::span<uint8_t> bytes) const = 0;
104
105 virtual std::unique_ptr<EC_AffinePoint_Data> mul(const EC_Scalar_Data& scalar,
106 RandomNumberGenerator& rng) const = 0;
107
109
110 virtual void _const_time_poison() const = 0;
111
112 virtual void _const_time_unpoison() const = 0;
113
114#if defined(BOTAN_HAS_LEGACY_EC_POINT)
115 virtual EC_Point to_legacy_point() const = 0;
116#endif
117};
118
119class EC_Mul2Table_Data /* NOLINT(*-special-member-functions) */ {
120 public:
121 virtual ~EC_Mul2Table_Data() = default;
122
123 // Returns nullptr if g*x + h*y was point at infinity
124 virtual std::unique_ptr<EC_AffinePoint_Data> mul2_vartime(const EC_Scalar_Data& x,
125 const EC_Scalar_Data& y) const = 0;
126
127 // Check if v == (g*x + h*y).x % n
128 //
129 // Returns false if g*x + h*y was point at infinity
131 const EC_Scalar_Data& x,
132 const EC_Scalar_Data& y) const = 0;
133};
134
135class EC_Group_Data final : public std::enable_shared_from_this<EC_Group_Data> {
136 public:
137 static std::shared_ptr<EC_Group_Data> create(const BigInt& p,
138 const BigInt& a,
139 const BigInt& b,
140 const BigInt& g_x,
141 const BigInt& g_y,
142 const BigInt& order,
143 const BigInt& cofactor,
144 const OID& oid,
146
148
149 EC_Group_Data(const EC_Group_Data& other) = delete;
150 EC_Group_Data(EC_Group_Data&& other) = delete;
151 EC_Group_Data& operator=(const EC_Group_Data& other) = delete;
153
154 bool params_match(const BigInt& p,
155 const BigInt& a,
156 const BigInt& b,
157 const BigInt& g_x,
158 const BigInt& g_y,
159 const BigInt& order,
160 const BigInt& cofactor) const;
161
162 // Like the other params_match but accepting the base point in encoded form
163 bool params_match(const BigInt& p,
164 const BigInt& a,
165 const BigInt& b,
166 std::span<const uint8_t> base_pt,
167 const BigInt& order,
168 const BigInt& cofactor) const;
169
170 bool params_match(const EC_Group_Data& other) const;
171
172 void set_oid(const OID& oid);
173
174 const OID& oid() const { return m_oid; }
175
176 const std::vector<uint8_t>& der_named_curve() const { return m_der_named_curve; }
177
178 const BigInt& p() const { return m_p; }
179
180 const BigInt& a() const { return m_a; }
181
182 const BigInt& b() const { return m_b; }
183
184 const BigInt& order() const { return m_order; }
185
186 const BigInt& cofactor() const { return m_cofactor; }
187
188#if defined(BOTAN_HAS_LEGACY_EC_POINT)
189 const CurveGFp& curve() const { return m_curve; }
190
191 const EC_Point& base_point() const { return m_base_point; }
192
193 const Montgomery_Params& monty() const { return m_monty; }
194
195 const BigInt& monty_a() const { return m_a_r; }
196
197 const BigInt& monty_b() const { return m_b_r; }
198
199 const Barrett_Reduction& mod_order() const { return m_mod_order; }
200#endif
201
202 bool order_is_less_than_p() const { return m_order_is_less_than_p; }
203
204 bool has_cofactor() const { return m_has_cofactor; }
205
206 const BigInt& g_x() const { return m_g_x; }
207
208 const BigInt& g_y() const { return m_g_y; }
209
210 size_t p_words() const { return m_p_words; }
211
212 size_t p_bits() const { return m_p_bits; }
213
214 size_t p_bytes() const { return (m_p_bits + 7) / 8; }
215
216 size_t order_bits() const { return m_order_bits; }
217
218 size_t order_bytes() const { return m_order_bytes; }
219
220 bool a_is_minus_3() const { return m_a_is_minus_3; }
221
222 bool a_is_zero() const { return m_a_is_zero; }
223
224 EC_Group_Source source() const { return m_source; }
225
226 EC_Group_Engine engine() const { return m_engine; }
227
228 /// Scalar from bytes
229 ///
230 /// This returns a value only if the bytes represent (in big-endian encoding) an integer
231 /// that is less than n, where n is the group order. It requires that the fixed length
232 /// encoding (with zero prefix) be used. It also rejects inputs that encode zero.
233 /// Thus the accepted range is [1,n)
234 ///
235 /// If the input is rejected then nullptr is returned
236 std::unique_ptr<EC_Scalar_Data> scalar_deserialize(std::span<const uint8_t> bytes) const;
237
238 /// Scalar from bytes with ECDSA style truncation
239 ///
240 /// This should always succeed
241 std::unique_ptr<EC_Scalar_Data> scalar_from_bytes_with_trunc(std::span<const uint8_t> bytes) const;
242
243 /// Scalar from bytes with modular reduction
244 ///
245 /// This returns a value only if bytes represents (in big-endian encoding) an integer
246 /// that is at most the square of the scalar group size. Otherwise it returns nullptr.
247 std::unique_ptr<EC_Scalar_Data> scalar_from_bytes_mod_order(std::span<const uint8_t> bytes) const;
248
249 /// Scalar from BigInt
250 ///
251 /// This returns a value only if bn is in [1,n) where n is the group order.
252 /// Otherwise it returns nullptr
253 std::unique_ptr<EC_Scalar_Data> scalar_from_bigint(const BigInt& bn) const;
254
255 /// Return a random scalar
256 ///
257 /// This will be in the range [1,n) where n is the group order
258 std::unique_ptr<EC_Scalar_Data> scalar_random(RandomNumberGenerator& rng) const;
259
260 std::unique_ptr<EC_Scalar_Data> scalar_one() const;
261
262 std::unique_ptr<EC_Scalar_Data> gk_x_mod_order(const EC_Scalar_Data& scalar, RandomNumberGenerator& rng) const;
263
264 /// Deserialize a point in the SEC1 uncompressed format
265 ///
266 /// Returns nullptr if the encoding was not in the uncompressed format,
267 /// or if the point is not on the curve
268 std::unique_ptr<EC_AffinePoint_Data> point_deserialize_uncompressed(std::span<const uint8_t> bytes) const;
269
270 /// Deserialize a point in the SEC1 compressed format
271 ///
272 /// Returns nullptr if the encoding was not in the compressed format,
273 /// or if the point is not on the curve
274 std::unique_ptr<EC_AffinePoint_Data> point_deserialize_compressed(std::span<const uint8_t> bytes) const;
275
276 /// Return the identity element (aka the point at infinity)
277 std::unique_ptr<EC_AffinePoint_Data> point_identity() const;
278
279 /// Return true if point_hash_to_curve_ro/point_hash_to_curve_nu will
280 /// work for this group when using the specified hash function
281 bool hash_to_curve_supported(std::string_view hash_fn) const;
282
283 std::unique_ptr<EC_AffinePoint_Data> point_hash_to_curve_ro(std::string_view hash_fn,
284 std::span<const uint8_t> input,
285 std::span<const uint8_t> domain_sep) const;
286
287 std::unique_ptr<EC_AffinePoint_Data> point_hash_to_curve_nu(std::string_view hash_fn,
288 std::span<const uint8_t> input,
289 std::span<const uint8_t> domain_sep) const;
290
291 std::unique_ptr<EC_AffinePoint_Data> point_g_mul(const EC_Scalar_Data& scalar, RandomNumberGenerator& rng) const;
292
293 std::unique_ptr<EC_AffinePoint_Data> mul_px_qy(const EC_AffinePoint_Data& p,
294 const EC_Scalar_Data& x,
295 const EC_AffinePoint_Data& q,
296 const EC_Scalar_Data& y,
297 RandomNumberGenerator& rng) const;
298
299 std::unique_ptr<EC_AffinePoint_Data> affine_add(const EC_AffinePoint_Data& p, const EC_AffinePoint_Data& q) const;
300
301 std::unique_ptr<EC_AffinePoint_Data> affine_neg(const EC_AffinePoint_Data& p) const;
302
303 std::unique_ptr<EC_Mul2Table_Data> make_mul2_table(const EC_AffinePoint_Data& pt) const;
304
306 BOTAN_ASSERT_NONNULL(m_pcurve);
307 return *m_pcurve;
308 }
309
310 /**
311 * Note this constructor should *only* be called by EC_Group_Data::create.
312 *
313 * It is only public to allow use of std::make_shared
314 */
315 EC_Group_Data(const BigInt& p,
316 const BigInt& a,
317 const BigInt& b,
318 const BigInt& g_x,
319 const BigInt& g_y,
320 const BigInt& order,
321 const BigInt& cofactor,
322 const OID& oid,
324
325 private:
326 // Possibly nullptr (if pcurves not available or not a standard curve)
327 std::shared_ptr<const PCurve::PrimeOrderCurve> m_pcurve;
328
329#if defined(BOTAN_HAS_LEGACY_EC_POINT)
330 // Set only if m_pcurve is nullptr
331 std::unique_ptr<EC_Point_Base_Point_Precompute> m_base_mult;
332#endif
333
334 BigInt m_p;
335 BigInt m_a;
336 BigInt m_b;
337 BigInt m_g_x;
338 BigInt m_g_y;
339 BigInt m_order;
340 BigInt m_cofactor;
341
342#if defined(BOTAN_HAS_LEGACY_EC_POINT)
343 CurveGFp m_curve;
344 EC_Point m_base_point;
345
346 Barrett_Reduction m_mod_field;
347 Barrett_Reduction m_mod_order;
348
349 // Montgomery parameters (only used for legacy EC_Point)
350 Montgomery_Params m_monty;
351
352 BigInt m_a_r; // (a*r) % p
353 BigInt m_b_r; // (b*r) % p
354#endif
355
356 OID m_oid;
357 std::vector<uint8_t> m_der_named_curve;
358 size_t m_p_words;
359 size_t m_p_bits;
360 size_t m_order_bits;
361 size_t m_order_bytes;
362 bool m_a_is_minus_3;
363 bool m_a_is_zero;
364 bool m_has_cofactor;
365 bool m_order_is_less_than_p;
366 EC_Group_Source m_source;
367 EC_Group_Engine m_engine;
368};
369
370/**
371* Instantiate the named hash and return a closure implementing the
372* expand_message function of RFC 9380
373*
374* Throws if the hash is unknown, or too weak for use with a group
375* of order_bits, per the RFC 9380 requirements
376*/
377std::function<void(std::span<uint8_t>)> h2c_expand_message(std::string_view hash_fn,
378 size_t order_bits,
379 std::span<const uint8_t> input,
380 std::span<const uint8_t> domain_sep);
381
382} // namespace Botan
383
384#endif
#define BOTAN_ASSERT_NONNULL(ptr)
Definition assert.h:121
virtual void serialize_compressed_to(std::span< uint8_t > bytes) const =0
virtual void _const_time_unpoison() const =0
virtual ~EC_AffinePoint_Data()=default
virtual std::unique_ptr< EC_AffinePoint_Data > mul(const EC_Scalar_Data &scalar, RandomNumberGenerator &rng) const =0
virtual secure_vector< uint8_t > mul_x_only(const EC_Scalar_Data &scalar, RandomNumberGenerator &rng) const =0
virtual void serialize_y_to(std::span< uint8_t > bytes) const =0
virtual std::unique_ptr< EC_AffinePoint_Data > clone() const =0
virtual size_t field_element_bytes() const =0
virtual void serialize_uncompressed_to(std::span< uint8_t > bytes) const =0
virtual void serialize_x_to(std::span< uint8_t > bytes) const =0
virtual const std::shared_ptr< const EC_Group_Data > & group() const =0
virtual void _const_time_poison() const =0
virtual bool is_identity() const =0
virtual void serialize_xy_to(std::span< uint8_t > bytes) const =0
std::unique_ptr< EC_Scalar_Data > gk_x_mod_order(const EC_Scalar_Data &scalar, RandomNumberGenerator &rng) const
const BigInt & p() const
const BigInt & g_x() const
std::unique_ptr< EC_AffinePoint_Data > affine_neg(const EC_AffinePoint_Data &p) const
const BigInt & a() const
std::unique_ptr< EC_Scalar_Data > scalar_from_bytes_mod_order(std::span< const uint8_t > bytes) const
bool a_is_minus_3() const
std::unique_ptr< EC_Scalar_Data > scalar_random(RandomNumberGenerator &rng) const
bool has_cofactor() const
std::unique_ptr< EC_Scalar_Data > scalar_deserialize(std::span< const uint8_t > bytes) const
bool params_match(const BigInt &p, const BigInt &a, const BigInt &b, const BigInt &g_x, const BigInt &g_y, const BigInt &order, const BigInt &cofactor) const
const PCurve::PrimeOrderCurve & pcurve() const
static std::shared_ptr< EC_Group_Data > create(const BigInt &p, const BigInt &a, const BigInt &b, const BigInt &g_x, const BigInt &g_y, const BigInt &order, const BigInt &cofactor, const OID &oid, EC_Group_Source source)
EC_Group_Data & operator=(EC_Group_Data &&other)=delete
std::unique_ptr< EC_AffinePoint_Data > affine_add(const EC_AffinePoint_Data &p, const EC_AffinePoint_Data &q) const
std::unique_ptr< EC_Scalar_Data > scalar_from_bytes_with_trunc(std::span< const uint8_t > bytes) const
std::unique_ptr< EC_Mul2Table_Data > make_mul2_table(const EC_AffinePoint_Data &pt) const
std::unique_ptr< EC_AffinePoint_Data > mul_px_qy(const EC_AffinePoint_Data &p, const EC_Scalar_Data &x, const EC_AffinePoint_Data &q, const EC_Scalar_Data &y, RandomNumberGenerator &rng) const
std::unique_ptr< EC_AffinePoint_Data > point_deserialize_compressed(std::span< const uint8_t > bytes) const
std::unique_ptr< EC_Scalar_Data > scalar_one() const
const OID & oid() const
EC_Group_Data & operator=(const EC_Group_Data &other)=delete
std::unique_ptr< EC_AffinePoint_Data > point_g_mul(const EC_Scalar_Data &scalar, RandomNumberGenerator &rng) const
size_t order_bits() const
const BigInt & cofactor() const
std::unique_ptr< EC_AffinePoint_Data > point_identity() const
Return the identity element (aka the point at infinity).
std::unique_ptr< EC_AffinePoint_Data > point_deserialize_uncompressed(std::span< const uint8_t > bytes) const
const std::vector< uint8_t > & der_named_curve() const
bool order_is_less_than_p() const
EC_Group_Data(EC_Group_Data &&other)=delete
EC_Group_Data(const EC_Group_Data &other)=delete
size_t p_words() const
size_t p_bytes() const
EC_Group_Source source() const
void set_oid(const OID &oid)
EC_Group_Engine engine() const
bool hash_to_curve_supported(std::string_view hash_fn) const
const BigInt & g_y() const
size_t order_bytes() const
std::unique_ptr< EC_Scalar_Data > scalar_from_bigint(const BigInt &bn) const
std::unique_ptr< EC_AffinePoint_Data > point_hash_to_curve_ro(std::string_view hash_fn, std::span< const uint8_t > input, std::span< const uint8_t > domain_sep) const
size_t p_bits() const
const BigInt & b() const
std::unique_ptr< EC_AffinePoint_Data > point_hash_to_curve_nu(std::string_view hash_fn, std::span< const uint8_t > input, std::span< const uint8_t > domain_sep) const
const BigInt & order() const
virtual ~EC_Mul2Table_Data()=default
virtual bool mul2_vartime_x_mod_order_eq(const EC_Scalar_Data &v, const EC_Scalar_Data &x, const EC_Scalar_Data &y) const =0
virtual std::unique_ptr< EC_AffinePoint_Data > mul2_vartime(const EC_Scalar_Data &x, const EC_Scalar_Data &y) const =0
virtual void assign(const EC_Scalar_Data &y)=0
virtual void _const_time_poison() const =0
virtual const std::shared_ptr< const EC_Group_Data > & group() const =0
virtual std::unique_ptr< EC_Scalar_Data > invert_vartime() const =0
virtual void zeroize()=0
virtual void _const_time_unpoison() const =0
virtual size_t bytes() const =0
virtual std::unique_ptr< EC_Scalar_Data > sub(const EC_Scalar_Data &other) const =0
virtual std::unique_ptr< EC_Scalar_Data > invert() const =0
virtual void serialize_to(std::span< uint8_t > bytes) const =0
virtual std::unique_ptr< EC_Scalar_Data > negate() const =0
virtual std::unique_ptr< EC_Scalar_Data > clone() const =0
virtual std::unique_ptr< EC_Scalar_Data > add(const EC_Scalar_Data &other) const =0
virtual void square_self()=0
virtual bool is_eq(const EC_Scalar_Data &y) const =0
virtual bool is_zero() const =0
virtual ~EC_Scalar_Data()=default
virtual std::unique_ptr< EC_Scalar_Data > mul(const EC_Scalar_Data &other) const =0
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)
EC_Group_Engine
Definition ec_group.h:48
std::vector< T, secure_allocator< T > > secure_vector
Definition secmem.h:128
EC_Group_Source
Definition ec_group.h:38