Botan 3.14.1
Crypto and TLS for C&
ec_apoint.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_APOINT_H_
8#define BOTAN_EC_APOINT_H_
9
10#include <botan/concepts.h>
11#include <botan/ec_point_format.h>
12#include <botan/secmem.h>
13#include <botan/types.h>
14#include <memory>
15#include <optional>
16#include <span>
17#include <string_view>
18#include <vector>
19
20namespace Botan {
21
22class BigInt;
24class EC_Group;
25class EC_Scalar;
26
27#if defined(BOTAN_HAS_LEGACY_EC_POINT)
28class EC_Point;
29#endif
30
31class EC_Group_Data;
33
34/**
35* Elliptic Curve Point in Affine Representation
36*/
38 public:
39 /// Point deserialization. Throws if wrong length or not a valid point
40 ///
41 /// This accepts SEC1 compressed or uncompressed formats. It also (for
42 /// backward compatibility) accepts the deprecated hybrid format, and
43 /// the encoding of the identity element as a single zero byte. Prefer
44 /// deserialize_compressed or deserialize_uncompressed, which accept
45 /// exactly one well-defined encoding.
46 EC_AffinePoint(const EC_Group& group, std::span<const uint8_t> bytes);
47
48 /// Point deserialization. Returns nullopt if wrong length or not a valid point
49 ///
50 /// This accepts SEC1 compressed or uncompressed formats. It also (for
51 /// backward compatibility) accepts the deprecated hybrid format, and
52 /// the encoding of the identity element as a single zero byte. Prefer
53 /// deserialize_compressed or deserialize_uncompressed, which accept
54 /// exactly one well-defined encoding.
55 static std::optional<EC_AffinePoint> deserialize(const EC_Group& group, std::span<const uint8_t> bytes);
56
57 /// Point deserialization, accepting only the SEC1 compressed format
58 ///
59 /// The encoding must be exactly 1 + field_element_bytes long, with a
60 /// header byte of either 0x02 or 0x03. All other encodings (including
61 /// the uncompressed, hybrid, and identity encodings) are rejected.
62 ///
63 /// Returns nullopt if the encoding was rejected or not a valid point
64 static std::optional<EC_AffinePoint> deserialize_compressed(const EC_Group& group,
65 std::span<const uint8_t> bytes);
66
67 /// Point deserialization, accepting only the SEC1 uncompressed format
68 ///
69 /// The encoding must be exactly 1 + 2*field_element_bytes long, with a
70 /// header byte of 0x04. All other encodings (including the compressed,
71 /// hybrid, and identity encodings) are rejected.
72 ///
73 /// Returns nullopt if the encoding was rejected or not a valid point
74 static std::optional<EC_AffinePoint> deserialize_uncompressed(const EC_Group& group,
75 std::span<const uint8_t> bytes);
76
77 /// Create a point from a pair (x,y) of integers
78 ///
79 /// The integers must be within the field - in the range [0,p) and must
80 /// satisfy the curve equation
81 static std::optional<EC_AffinePoint> from_bigint_xy(const EC_Group& group, const BigInt& x, const BigInt& y);
82
83 /// Multiply by the group generator returning a complete point
84 static EC_AffinePoint g_mul(const EC_Scalar& scalar, RandomNumberGenerator& rng);
85
86 /// Return the identity element
88
89 /// Return the standard group generator
91
92 /// Hash to curve (RFC 9380), random oracle variant
93 ///
94 /// Only supported for specific groups
96 std::string_view hash_fn,
97 std::span<const uint8_t> input,
98 std::span<const uint8_t> domain_sep);
99
100 /// Hash to curve (RFC 9380), random oracle variant
101 ///
102 /// Only supported for specific groups
104 std::string_view hash_fn,
105 std::span<const uint8_t> input,
106 std::string_view domain_sep);
107
108 /// Hash to curve (RFC 9380), non uniform variant
109 ///
110 /// Only supported for specific groups
112 std::string_view hash_fn,
113 std::span<const uint8_t> input,
114 std::span<const uint8_t> domain_sep);
115
116 /// Hash to curve (RFC 9380), non uniform variant
117 ///
118 /// Only supported for specific groups
120 std::string_view hash_fn,
121 std::span<const uint8_t> input,
122 std::string_view domain_sep);
123
124 /// Multiply a point by a scalar returning a complete point
125 EC_AffinePoint mul(const EC_Scalar& scalar, RandomNumberGenerator& rng) const;
126
127 /// Multiply a point by a scalar, returning the byte encoding of the x coordinate only
129
130 /// Compute 2-ary multiscalar multiplication - p*x + q*y
131 ///
132 /// This operation runs in constant time with respect to p, x, q, and y
133 ///
134 /// @returns p*x+q*y, or nullopt if the result was the point at infinity
135 static std::optional<EC_AffinePoint> mul_px_qy(const EC_AffinePoint& p,
136 const EC_Scalar& x,
137 const EC_AffinePoint& q,
138 const EC_Scalar& y,
140
141 /// Point addition
142 ///
143 /// Note that this is quite slow since it converts the resulting
144 /// projective point immediately to affine coordinates, which requires a
145 /// field inversion. This can be sufficient when implementing protocols
146 /// that just need to perform a few additions.
147 ///
148 /// In the future a corresponding EC_ProjectivePoint type may be added
149 /// which would avoid the expensive affine conversions
150 EC_AffinePoint add(const EC_AffinePoint& q) const;
151
152 /// Point negation
153 EC_AffinePoint negate() const;
154
155 /// Return the elliptic curve group this point is associated with
156 EC_Group group() const;
157
158 /// Return the number of bytes of a field element
159 ///
160 /// A point consists of two field elements, plus possibly a header
161 size_t field_element_bytes() const;
162
163 /// Return true if this point is the identity element
164 bool is_identity() const;
165
166 /// Convert *this to two BigInts (x, y)
167 std::pair<BigInt, BigInt> to_bigint_xy() const;
168
169 /// Write the fixed length encoding of affine x coordinate
170 ///
171 /// The output span must be exactly field_element_bytes long
172 ///
173 /// This function will fail if this point is the identity element
174 void serialize_x_to(std::span<uint8_t> bytes) const;
175
176 /// Write the fixed length encoding of affine y coordinate
177 ///
178 /// The output span must be exactly field_element_bytes long
179 ///
180 /// This function will fail if this point is the identity element
181 void serialize_y_to(std::span<uint8_t> bytes) const;
182
183 /// Write the fixed length encoding of affine x and y coordinates
184 ///
185 /// The output span must be exactly 2*field_element_bytes long
186 ///
187 /// This function will fail if this point is the identity element
188 void serialize_xy_to(std::span<uint8_t> bytes) const;
189
190 /// Write the fixed length SEC1 compressed encoding
191 ///
192 /// The output span must be exactly 1 + field_element_bytes long
193 ///
194 /// This function will fail if this point is the identity element
195 void serialize_compressed_to(std::span<uint8_t> bytes) const;
196
197 /// Return the fixed length encoding of SEC1 uncompressed encoding
198 ///
199 /// The output span must be exactly 1 + 2*field_element_bytes long
200 ///
201 /// This function will fail if this point is the identity element
202 void serialize_uncompressed_to(std::span<uint8_t> bytes) const;
203
204 /// Return the bytes of the affine x coordinate in a container
205 ///
206 /// This function will fail if this point is the identity element
207 template <concepts::resizable_byte_buffer T = secure_vector<uint8_t>>
208 T x_bytes() const {
209 T bytes(this->field_element_bytes());
210 this->serialize_x_to(bytes);
211 return bytes;
212 }
213
214 /// Return the bytes of the affine y coordinate in a container
215 ///
216 /// This function will fail if this point is the identity element
217 template <concepts::resizable_byte_buffer T = secure_vector<uint8_t>>
218 T y_bytes() const {
219 T bytes(this->field_element_bytes());
220 this->serialize_y_to(bytes);
221 return bytes;
222 }
223
224 /// Return the bytes of the affine x and y coordinates in a container
225 ///
226 /// This function will fail if this point is the identity element
227 template <concepts::resizable_byte_buffer T = secure_vector<uint8_t>>
228 T xy_bytes() const {
229 T bytes(2 * this->field_element_bytes());
230 this->serialize_xy_to(bytes);
231 return bytes;
232 }
233
234 /// Return the bytes of the affine x and y coordinates in a container
235 ///
236 /// This function will fail if this point is the identity element
237 template <concepts::resizable_byte_buffer T = std::vector<uint8_t>>
239 T bytes(1 + 2 * this->field_element_bytes());
240 this->serialize_uncompressed_to(bytes);
241 return bytes;
242 }
243
244 /// Return the bytes of the affine x and y coordinates in a container
245 ///
246 /// This function will fail if this point is the identity element
247 template <concepts::resizable_byte_buffer T = std::vector<uint8_t>>
249 T bytes(1 + this->field_element_bytes());
250 this->serialize_compressed_to(bytes);
251 return bytes;
252 }
253
254 /**
255 * Test if two points are equal
256 * @param other the point to compare against
257 * @return true if the two points are equal
258 */
259 bool operator==(const EC_AffinePoint& other) const;
260
261 /**
262 * Test if two points are unequal
263 * @param other the point to compare against
264 * @return true if the two points are not equal
265 */
266 bool operator!=(const EC_AffinePoint& other) const { return !(*this == other); }
267
268 /// Return an encoding depending on the requested format
269 std::vector<uint8_t> serialize(EC_Point_Format format) const;
270
271 /**
272 * Copy constructor
273 * @param other the point to copy
274 */
275 EC_AffinePoint(const EC_AffinePoint& other);
276
277 /**
278 * Move constructor
279 * @param other the point to move from
280 */
281 EC_AffinePoint(EC_AffinePoint&& other) noexcept;
282
283 /**
284 * Copy assignment
285 * @param other the point to copy
286 * @return reference to this
287 */
288 EC_AffinePoint& operator=(const EC_AffinePoint& other);
289
290 /**
291 * Move assignment
292 * @param other the point to move from
293 * @return reference to this
294 */
295 EC_AffinePoint& operator=(EC_AffinePoint&& other) noexcept;
296
297#if defined(BOTAN_HAS_LEGACY_EC_POINT)
298 /**
299 * Deprecated conversion
300 */
301 EC_AffinePoint(const EC_Group& group, const EC_Point& pt);
302
303 /**
304 * Deprecated conversion
305 */
306 EC_Point to_legacy_point() const;
307#endif
308
309 /**
310 * Multiply by the group generator returning a complete point
311 * @param scalar the scalar to multiply the generator by
312 * @param rng a random number generator, used for blinding
313 * @return the resulting point
314 */
315 BOTAN_DEPRECATED("Use version without workspace arg")
316 static EC_AffinePoint g_mul(const EC_Scalar& scalar, RandomNumberGenerator& rng, std::vector<BigInt>& /*ws*/) {
317 return EC_AffinePoint::g_mul(scalar, rng);
318 }
319
320 /**
321 * Multiply a point by a scalar returning a complete point
322 * @param scalar the scalar to multiply this point by
323 * @param rng a random number generator, used for blinding
324 * @return the resulting point
325 */
326 BOTAN_DEPRECATED("Use version without workspace arg")
327 EC_AffinePoint mul(const EC_Scalar& scalar, RandomNumberGenerator& rng, std::vector<BigInt>& /*ws*/) const {
328 return this->mul(scalar, rng);
329 }
330
331 /// Multiply a point by a scalar, returning the byte encoding of the x coordinate only
334 std::vector<BigInt>& /*ws*/) const {
335 return this->mul_x_only(scalar, rng);
336 }
337
339
340 /**
341 * For internal use only
342 */
343 const EC_AffinePoint_Data& _inner() const { return inner(); }
344
345 /**
346 * For internal use only
347 */
348 static EC_AffinePoint _from_inner(std::unique_ptr<EC_AffinePoint_Data> inner);
349
350 /**
351 * For internal use only
352 */
353 const std::shared_ptr<const EC_Group_Data>& _group() const;
354
355 /**
356 * Mark this point as holding secret data
357 *
358 * @warning this is an implementation detail which is not for
359 * public use and not covered by SemVer.
360 */
361 void _const_time_poison() const;
362
363 /**
364 * Mark this point as no longer holding secret data
365 *
366 * @warning this is an implementation detail which is not for
367 * public use and not covered by SemVer.
368 */
369 void _const_time_unpoison() const;
370
371 private:
372 friend class EC_Mul2Table;
373
374 explicit EC_AffinePoint(std::unique_ptr<EC_AffinePoint_Data> point);
375
376 const EC_AffinePoint_Data& inner() const { return *m_point; }
377
378 std::unique_ptr<EC_AffinePoint_Data> m_point;
379};
380
381} // namespace Botan
382
383#endif
#define BOTAN_PUBLIC_API(maj, min)
Definition api.h:21
#define BOTAN_DEPRECATED(msg)
Definition api.h:73
static EC_AffinePoint hash_to_curve_ro(const EC_Group &group, std::string_view hash_fn, std::span< const uint8_t > input, std::span< const uint8_t > domain_sep)
EC_AffinePoint negate() const
Point negation.
size_t field_element_bytes() const
EC_Group group() const
Return the elliptic curve group this point is associated with.
void serialize_xy_to(std::span< uint8_t > bytes) const
static EC_AffinePoint hash_to_curve_nu(const EC_Group &group, std::string_view hash_fn, std::span< const uint8_t > input, std::span< const uint8_t > domain_sep)
bool operator!=(const EC_AffinePoint &other) const
Definition ec_apoint.h:266
bool is_identity() const
Return true if this point is the identity element.
static std::optional< EC_AffinePoint > deserialize_uncompressed(const EC_Group &group, std::span< const uint8_t > bytes)
static EC_AffinePoint identity(const EC_Group &group)
Return the identity element.
Definition ec_apoint.cpp:80
static std::optional< EC_AffinePoint > from_bigint_xy(const EC_Group &group, const BigInt &x, const BigInt &y)
Definition ec_apoint.cpp:93
static std::optional< EC_AffinePoint > mul_px_qy(const EC_AffinePoint &p, const EC_Scalar &x, const EC_AffinePoint &q, const EC_Scalar &y, RandomNumberGenerator &rng)
static EC_AffinePoint g_mul(const EC_Scalar &scalar, RandomNumberGenerator &rng)
Multiply by the group generator returning a complete point.
std::pair< BigInt, BigInt > to_bigint_xy() const
Convert *this to two BigInts (x, y).
T serialize_uncompressed() const
Definition ec_apoint.h:238
EC_AffinePoint(const EC_Group &group, std::span< const uint8_t > bytes)
Definition ec_apoint.cpp:36
EC_AffinePoint mul(const EC_Scalar &scalar, RandomNumberGenerator &rng) const
Multiply a point by a scalar returning a complete point.
static std::optional< EC_AffinePoint > deserialize(const EC_Group &group, std::span< const uint8_t > bytes)
static std::optional< EC_AffinePoint > deserialize_compressed(const EC_Group &group, std::span< const uint8_t > bytes)
void serialize_x_to(std::span< uint8_t > bytes) const
T serialize_compressed() const
Definition ec_apoint.h:248
void serialize_compressed_to(std::span< uint8_t > bytes) const
secure_vector< uint8_t > mul_x_only(const EC_Scalar &scalar, RandomNumberGenerator &rng) const
Multiply a point by a scalar, returning the byte encoding of the x coordinate only.
const EC_AffinePoint_Data & _inner() const
Definition ec_apoint.h:343
secure_vector< uint8_t > mul_x_only(const EC_Scalar &scalar, RandomNumberGenerator &rng, std::vector< BigInt > &) const
Multiply a point by a scalar, returning the byte encoding of the x coordinate only.
Definition ec_apoint.h:332
void serialize_uncompressed_to(std::span< uint8_t > bytes) const
void serialize_y_to(std::span< uint8_t > bytes) const
EC_AffinePoint add(const EC_AffinePoint &q) const
friend class EC_Mul2Table
Definition ec_apoint.h:372
static EC_AffinePoint generator(const EC_Group &group)
Return the standard group generator.
Definition ec_apoint.cpp:84
std::vector< T, secure_allocator< T > > secure_vector
Definition secmem.h:128
bool operator==(const AlgorithmIdentifier &x, const AlgorithmIdentifier &y)
Definition alg_id.cpp:54