Botan 3.14.1
Crypto and TLS for C&
ec_group.h
Go to the documentation of this file.
1/*
2* ECC Domain Parameters
3*
4* (C) 2007 Falko Strenzke, FlexSecure GmbH
5* 2008-2010,2024 Jack Lloyd
6*
7* Botan is released under the Simplified BSD License (see license.txt)
8*/
9
10#ifndef BOTAN_ECC_DOMAIN_PARAMETERS_H_
11#define BOTAN_ECC_DOMAIN_PARAMETERS_H_
12
13#include <botan/asn1_obj.h>
14#include <botan/bigint.h>
15#include <botan/ec_apoint.h>
16#include <botan/ec_point_format.h>
17#include <botan/ec_scalar.h>
18#include <memory>
19#include <set>
20#include <span>
21
22#if defined(BOTAN_HAS_LEGACY_EC_POINT)
23 #include <botan/ec_point.h>
24#endif
25
26namespace Botan {
27
28/**
29* This enum indicates the source of the elliptic curve parameters
30* in use.
31*
32* Builtin means the curve is a known standard one which was compiled
33* in the library.
34*
35* ExternalSource means the curve parameters came from either an explicit
36* curve encoding or an application defined curve.
37*/
38enum class EC_Group_Source : uint8_t {
41};
42
43/**
44* Enum indicating the way the group in question is implemented
45*
46* This is returned by EC_Group::engine
47*/
48enum class EC_Group_Engine : uint8_t {
49 /// Using per curve implementation; fastest available
51 /// A generic implementation that handles many curves in one implementation
53 /// The old implementation, used as a fallback if none of the other
54 /// implementations can be used
55 /// TODO(Botan4) remove this
57};
58
59class EC_Mul2Table_Data;
60class EC_Group_Data;
61class EC_Group_Data_Map;
62
63/**
64* Class representing an elliptic curve
65*
66* The internal representation is stored in a shared_ptr, so copying an
67* EC_Group is inexpensive.
68*/
69class BOTAN_PUBLIC_API(2, 0) EC_Group final {
70 public:
71 /**
72 * Construct elliptic curve from the specified parameters
73 *
74 * This is used for example to create custom (application-specific) curves.
75 *
76 * Some build configurations do not support application specific curves, in
77 * which case this constructor will throw an exception. You can check for
78 * this situation beforehand using the function
79 * EC_Group::supports_application_specific_group()
80 *
81 * @param p the elliptic curve p
82 * @param a the elliptic curve a param
83 * @param b the elliptic curve b param
84 * @param base_x the x coordinate of the base point
85 * @param base_y the y coordinate of the base point
86 * @param order the order of the base point
87 * @param cofactor the cofactor
88 * @param oid an optional OID used to identify this curve
89 *
90 * @warning This constructor is deprecated and will be removed in Botan 4
91 *
92 * @warning support for cofactors > 1 is deprecated and will be removed
93 *
94 * @warning support for prime fields > 521 bits is deprecated and
95 * will be removed.
96 *
97 * @warning Support for explicitly encoded curve parameters is deprecated.
98 * An OID must be assigned.
99 */
100 BOTAN_DEPRECATED("Use EC_Group::register_custom_group")
101 EC_Group(const BigInt& p,
102 const BigInt& a,
103 const BigInt& b,
104 const BigInt& base_x,
105 const BigInt& base_y,
106 const BigInt& order,
107 const BigInt& cofactor,
108 const OID& oid = OID());
109
110 /**
111 * Construct elliptic curve from the specified parameters
112 *
113 * This is used for example to create custom (application-specific) curves.
114 *
115 * Calling this function registers these parameters within the persistent state
116 * of the library; for example once this call completes, an ECDSA key
117 * specifying its namedCurve matching the provided OID can be decoded, and
118 * this remains true even after the EC_Group created has been destroyed.
119 * If necessary you can unregister the group using EC_Group::unregister.
120 *
121 * Some build configurations do not support application specific curves, in
122 * which case this function will throw an exception. You can check for
123 * this situation beforehand using the function
124 * EC_Group::supports_application_specific_group()
125 *
126 * The following constraints are imposed on the parameters:
127 *
128 * - An object identifier must be provided
129 *
130 * - The prime must be at least 192 bits and at most 512 bits, and a multiple
131 * of 32 bits.
132 *
133 * - As an extension of the above restriction, the prime can also be exactly
134 * the 521-bit Mersenne prime (2**521-1) or exactly the 239-bit prime used in
135 * X9.62 239 bit groups (2**239 - 2**143 - 2**95 + 2**47 - 1)
136 *
137 * - The prime must be congruent to 3 modulo 4
138 *
139 * - The group order must have the same bit length as the prime. It is allowed
140 * for the order to be larger than p, but they must have the same bit length.
141 *
142 * - Only prime order curves (with cofactor == 1) are allowed
143 *
144 * @warning use only elliptic curve parameters that you trust
145 *
146 * @param oid an object identifier used to identify this curve
147 * @param p the elliptic curve prime (at most 521 bits)
148 * @param a the elliptic curve a param
149 * @param b the elliptic curve b param
150 * @param base_x the x coordinate of the group generator
151 * @param base_y the y coordinate of the group generator
152 * @param order the order of the group
153 */
154 BOTAN_DEPRECATED("Use EC_Group::register_custom_group")
155 EC_Group(const OID& oid,
156 const BigInt& p,
157 const BigInt& a,
158 const BigInt& b,
159 const BigInt& base_x,
160 const BigInt& base_y,
161 const BigInt& order);
162
163 /**
164 * Construct elliptic curve from the specified parameters
165 *
166 * This is used for example to create custom (application-specific) curves.
167 *
168 * This function registers these parameters within the persistent state
169 * of the library; for example once this call completes, an ECDSA key
170 * specifying its namedCurve matching the provided OID can be decoded, and
171 * this remains true even after the EC_Group returned here has been destroyed.
172 * If necessary you can unregister the group using EC_Group::unregister.
173 *
174 * Some build configurations do not support application specific curves, in
175 * which case this function will throw an exception. You can check for
176 * this situation beforehand using the function
177 * EC_Group::supports_application_specific_group()
178 *
179 * Unlike the deprecated constructor, this function imposes additional
180 * restrictions on the parameters, namely:
181 *
182 * - An object identifier must be provided
183 *
184 * - The prime must be at least 192 bits and at most 512 bits, and a multiple
185 * of 32 bits. Currently, as long as BOTAN_DISABLE_DEPRECATED_FEATURES is not
186 * set, this function will accept primes as small as 128 bits - this lower
187 * bound will be removed in the next major release.
188 *
189 * - As an extension of the above restriction, the prime can also be exactly
190 * the 521-bit Mersenne prime (2**521-1) or exactly the 239-bit prime used in
191 * X9.62 239 bit groups (2**239 - 2**143 - 2**95 + 2**47 - 1)
192 *
193 * - The prime must be congruent to 3 modulo 4
194 *
195 * - The group order must have the same bit length as the prime. It is allowed
196 * for the order to be larger than p, but they must have the same bit length.
197 *
198 * - Only prime order curves (with cofactor == 1) are allowed
199 *
200 * @warning use only elliptic curve parameters that you trust
201 *
202 * @param oid an object identifier used to identify this curve
203 * @param p the elliptic curve prime (at most 521 bits)
204 * @param a the elliptic curve a param
205 * @param b the elliptic curve b param
206 * @param base_x the x coordinate of the group generator
207 * @param base_y the y coordinate of the group generator
208 * @param order the order of the group
209 */
210 static EC_Group register_custom_group(const OID& oid,
211 const BigInt& p,
212 const BigInt& a,
213 const BigInt& b,
214 const BigInt& base_x,
215 const BigInt& base_y,
216 const BigInt& order);
217
218 /**
219 * Decode a DER encoded ECC domain parameter set
220 * @param der the bytes of the DER encoding
221 */
222 explicit EC_Group(std::span<const uint8_t> der);
223
224 /**
225 * Decode a DER encoded ECC domain parameter set
226 * @param der the bytes of the DER encoding
227 * @param der_len the length of der in bytes
228 */
229 BOTAN_DEPRECATED("Use EC_Group(std::span)")
230 EC_Group(const uint8_t der[], size_t der_len) : EC_Group(std::span{der, der_len}) {}
231
232 /**
233 * Create an EC domain by OID (or throw if unknown)
234 * @param oid the OID of the EC domain to create
235 */
236 BOTAN_DEPRECATED("Use EC_Group::from_OID") explicit EC_Group(const OID& oid) { *this = EC_Group::from_OID(oid); }
237
238 /**
239 * Create an EC domain from PEM encoding (as from PEM_encode()), or
240 * from an OID name (eg "secp256r1", or "1.2.840.10045.3.1.7")
241 * @param pem_or_oid PEM-encoded data, or an OID
242 *
243 * @warning Support for PEM in this function is deprecated. Use
244 * EC_Group::from_PEM or EC_Group::from_OID or EC_Group::from_name
245 */
246 BOTAN_DEPRECATED("Use EC_Group::from_{name,OID,PEM}") explicit EC_Group(std::string_view pem_or_oid);
247
248 /**
249 * Initialize an EC group from the PEM/ASN.1 encoding
250 */
251 static EC_Group from_PEM(std::string_view pem);
252
253 /**
254 * Initialize an EC group from a group named by an object identifier
255 */
256 static EC_Group from_OID(const OID& oid);
257
258 /**
259 * Initialize an EC group from a group common name (eg "secp256r1")
260 */
261 static EC_Group from_name(std::string_view name);
262
263 /**
264 * Initialize an EC group from the PEM/ASN.1 encoding
265 * @param pem the PEM encoded group
266 * @return the decoded group
267 */
268 BOTAN_DEPRECATED("Use EC_Group::from_PEM") static EC_Group EC_Group_from_PEM(std::string_view pem) {
269 return EC_Group::from_PEM(pem);
270 }
271
272 /**
273 * Create an uninitialized EC_Group
274 */
275 BOTAN_DEPRECATED("Deprecated no replacement") EC_Group();
276
277 /**
278 * Unregister a previously registered group.
279 *
280 * Using this is discouraged for normal use. This is only useful or necessary if
281 * you are registering a very large number of distinct groups, and need to worry about memory constraints.
282 *
283 * Returns true if the group was found and unregistered.
284 */
285 static bool unregister(const OID& oid);
286
288
289 /**
290 * Copy constructor
291 */
293
294 /**
295 * Move constructor
296 */
297 EC_Group(EC_Group&&) = default;
298
299 /**
300 * Copy assignment
301 * @return reference to this
302 */
303 EC_Group& operator=(const EC_Group&);
304
305 /**
306 * Move assignment
307 * @return reference to this
308 */
309 EC_Group& operator=(EC_Group&&) = default;
310
311 /**
312 * Return true if this group has been initialized with domain parameters
313 *
314 * This is only false for groups created using the deprecated default
315 * constructor.
316 */
317 bool initialized() const { return (m_data != nullptr); }
318
319 /**
320 * Verify EC_Group domain
321 * @returns true if group is valid. false otherwise
322 */
323 bool verify_group(RandomNumberGenerator& rng, bool strong = false) const;
324
325 /**
326 * Test if two groups describe the same curve
327 * @param other the group to compare against
328 * @return true if the two groups are equal
329 */
330 bool operator==(const EC_Group& other) const;
331
332 /**
333 * Return how this group was created, eg from a builtin table or by
334 * decoding an external encoding
335 */
336 EC_Group_Source source() const;
337
338 /**
339 * Return true if in this build configuration it is possible to
340 * register an application specific elliptic curve.
341 */
342 static bool supports_application_specific_group();
343
344 /**
345 * Return true if in this build configuration it is possible to
346 * register an application specific elliptic curve with a cofactor
347 * larger than 1.
348 */
349 static bool supports_application_specific_group_with_cofactor();
350
351 /**
352 * Return true if EC_Group::from_name(name) should succeed for this name
353 * either because it is a group compiled into the library or it is a group
354 * which has already been registered by the application at runtime.
355 */
356 static bool supports_named_group(std::string_view name);
357
358 /**
359 * Return true if this EC_Group was derived from an explicit encoding
360 *
361 * Explicit encoding of groups is deprecated; when support for explicit curves
362 * is removed in a future major release, this function will also be removed.
363 */
364 bool used_explicit_encoding() const { return m_explicit_encoding; }
365
366 /**
367 * Return how this EC_Group is implemented under the hood
368 *
369 * This is mostly useful for diagnostic or debugging purposes
370 */
371 EC_Group_Engine engine() const;
372
373 /**
374 * Return a set of known named EC groups
375 *
376 * This returns a set of groups for which from_name should succeed.
377 *
378 * Note that the set of included groups can vary based on the build
379 * configuration, and that this list does not include any groups registered
380 * by the application at runtime.
381 */
382 static const std::set<std::string>& known_named_groups();
383
384 /**
385 * Create the DER encoding of this domain
386 * @param form of encoding to use
387 * @returns the group information encoded as DER
388 */
389 BOTAN_DEPRECATED("Use the variant that does not take EC_Group_Encoding")
390 std::vector<uint8_t> DER_encode(EC_Group_Encoding form) const;
391
392 /**
393 * Create the DER encoding of this domain, using namedCurve format
394 * @returns the group information encoded as DER
395 */
396 std::vector<uint8_t> DER_encode() const;
397
398 /**
399 * Return the PEM encoding
400 * @return string containing PEM data
401 *
402 * @warning In Botan4 the form parameter will be removed and only
403 * namedCurve will be supported
404 *
405 * TODO(Botan4) remove the argument
406 */
407 std::string PEM_encode(EC_Group_Encoding form = EC_Group_Encoding::Explicit) const;
408
409 /**
410 * Return the size of p in bits (same as get_p().bits())
411 */
412 size_t get_p_bits() const;
413
414 /**
415 * Return the size of p in bytes (same as get_p().bytes())
416 */
417 size_t get_p_bytes() const;
418
419 /**
420 * Return the size of group order in bits (same as get_order().bits())
421 */
422 size_t get_order_bits() const;
423
424 /**
425 * Return the size of the group order in bytes (same as get_order().bytes())
426 */
427 size_t get_order_bytes() const;
428
429 /**
430 * Table for computing g*x + h*y
431 */
432 class BOTAN_PUBLIC_API(3, 6) Mul2Table final {
433 public:
434 /**
435 * Create a table for computing g*x + h*y
436 */
438
439 /**
440 * Return the elliptic curve point g*x + h*y
441 *
442 * Where g is the group generator and h is the value passed to the constructor
443 *
444 * Returns nullopt if g*x + h*y was the point at infinity
445 *
446 * @warning this function is variable time with respect to x and y
447 */
448 std::optional<EC_AffinePoint> mul2_vartime(const EC_Scalar& x, const EC_Scalar& y) const;
449
450 /**
451 * Check if v equals the x coordinate of g*x + h*y reduced modulo the order
452 *
453 * Where g is the group generator and h is the value passed to the constructor
454 *
455 * Returns false if unequal, including if g*x + h*y was the point at infinity
456 *
457 * @warning this function is variable time with respect to x and y
458 */
459 bool mul2_vartime_x_mod_order_eq(const EC_Scalar& v, const EC_Scalar& x, const EC_Scalar& y) const;
460
461 /**
462 * Check if v equals the x coordinate of g*x*c + h*y*c reduced modulo the order
463 *
464 * Where g is the group generator and h is the value passed to the constructor
465 *
466 * Returns false if unequal, including if g*x*c + h*y*c was the point at infinity
467 *
468 * @warning this function is variable time with respect to x and y
469 */
471 const EC_Scalar& c,
472 const EC_Scalar& x,
473 const EC_Scalar& y) const;
474
476
477 Mul2Table(const Mul2Table& other) = delete;
478 Mul2Table& operator=(const Mul2Table& other) = delete;
479
480 /**
481 * Move constructor
482 * @param other the table to move from
483 */
484 Mul2Table(Mul2Table&& other) noexcept;
485
486 /**
487 * Move assignment
488 * @param other the table to move from
489 * @return reference to this
490 */
491 Mul2Table& operator=(Mul2Table&& other) noexcept;
492
493 private:
494 std::unique_ptr<EC_Mul2Table_Data> m_tbl;
495 };
496
497 /**
498 * Return true if RFC 9380 hash to curve is supported for this group
499 * with the specified hash function
500 *
501 * If this returns true then EC_AffinePoint::hash_to_curve_ro and
502 * EC_AffinePoint::hash_to_curve_nu will work for this group and hash.
503 *
504 * This checks that the hash function is available and satisfies the
505 * RFC 9380 requirements for this group (in particular that the hash
506 * output is at least twice the target security level), that the curve
507 * implementation supports hash to curve, and that the required message
508 * expansion (currently just expand_message_xmd) is included in the build.
509 */
510 bool hash_to_curve_supported(std::string_view hash_fn) const;
511
512 /**
513 * Return the OID of these domain parameters
514 * @result the OID
515 */
516 const OID& get_curve_oid() const;
517
518 /**
519 * Return the prime modulus of the field
520 */
521 const BigInt& get_p() const;
522
523 /**
524 * Return the a parameter of the elliptic curve equation
525 */
526 const BigInt& get_a() const;
527
528 /**
529 * Return the b parameter of the elliptic curve equation
530 */
531 const BigInt& get_b() const;
532
533 /**
534 * Return the x coordinate of the base point
535 */
536 const BigInt& get_g_x() const;
537
538 /**
539 * Return the y coordinate of the base point
540 */
541 const BigInt& get_g_y() const;
542
543 /**
544 * Return the order of the base point
545 * @result order of the base point
546 */
547 const BigInt& get_order() const;
548
549 /**
550 * Return the cofactor
551 * @result the cofactor
552 * TODO(Botan4): Remove this
553 */
554 const BigInt& get_cofactor() const;
555
556 /**
557 * Return true if the cofactor is > 1
558 * TODO(Botan4): Remove this
559 */
560 bool has_cofactor() const;
561
562 /**
563 * Look up the parameters of a builtin group by OID
564 *
565 * For internal use only
566 *
567 * @param oid the OID of the group to look up
568 * @return the group data, or nullptr if the OID is not a known group
569 *
570 * TODO(Botan4): Move this to an internal header
571 */
572 static std::shared_ptr<EC_Group_Data> EC_group_info(const OID& oid);
573
574 /**
575 * Discard all cached and application registered group data
576 *
577 * For internal use only
578 *
579 * @warning this invalidates pointers and can cause memory corruption.
580 * This function exists only to be called in tests.
581 *
582 * @return the number of groups which were discarded
583 *
584 * TODO(Botan4): Move this to an internal header
585 */
586 static size_t clear_registered_curve_data();
587
588 /**
589 * Identify a builtin group by its order
590 *
591 * For internal use only
592 *
593 * @param order the group order to look up
594 * @return the OID of the matching group, or an empty OID if none matches
595 *
596 * TODO(Botan4): Move this to an internal header
597 */
598 static OID EC_group_identity_from_order(const BigInt& order);
599
600 /**
601 * For internal use only
602 * @return the inner representation of this group
603 */
604 const std::shared_ptr<const EC_Group_Data>& _data() const { return m_data; }
605
606#if defined(BOTAN_HAS_LEGACY_EC_POINT)
607 /**
608 * Check if y is a plausible point on the curve
609 *
610 * In particular, checks that it is a point on the curve, not infinity,
611 * and that it has order matching the group.
612 */
613 bool verify_public_element(const EC_Point& y) const;
614
615 /**
616 * OS2ECP (Octet String To Elliptic Curve Point)
617 *
618 * Deserialize an encoded point. Verifies that the point is on the curve.
619 */
620 BOTAN_DEPRECATED("Use EC_AffinePoint::deserialize") EC_Point OS2ECP(const uint8_t bits[], size_t len) const {
621 return EC_AffinePoint(*this, std::span{bits, len}).to_legacy_point();
622 }
623
624 /**
625 * OS2ECP (Octet String To Elliptic Curve Point)
626 *
627 * Deserialize an encoded point. Verifies that the point is on the curve.
628 *
629 * @param encoded_point the encoded point
630 * @return the decoded point
631 */
632 BOTAN_DEPRECATED("Use EC_AffinePoint::deserialize")
633 EC_Point OS2ECP(std::span<const uint8_t> encoded_point) const {
634 return EC_AffinePoint(*this, encoded_point).to_legacy_point();
635 }
636
637 /**
638 * Return group base point
639 * @result base point
640 */
641 BOTAN_DEPRECATED("Use EC_AffinePoint::generator") const EC_Point& get_base_point() const;
642
643 // Everything below here will be removed in a future release:
644
645 /**
646 * Return the canonical group generator
647 * @result standard generator of the curve
648 */
649 BOTAN_DEPRECATED("Use EC_AffinePoint::generator") const EC_Point& generator() const;
650
651 /**
652 * Multi exponentiate. Not constant time.
653 * @return base_point*x + h*y
654 */
655 BOTAN_DEPRECATED("Use EC_Group::Mul2Table")
656 EC_Point point_multiply(const BigInt& x_bn, const EC_Point& h_pt, const BigInt& y_bn) const {
657 const auto x = EC_Scalar::from_bigint(*this, x_bn);
658 const auto y = EC_Scalar::from_bigint(*this, y_bn);
659 const auto h = EC_AffinePoint(*this, h_pt);
660
661 const Mul2Table gh_mul(h);
662
663 if(auto r = gh_mul.mul2_vartime(x, y)) {
664 return r->to_legacy_point();
665 } else {
666 return EC_AffinePoint::identity(*this).to_legacy_point();
667 }
668 }
669
670 /**
671 * Blinded point multiplication, attempts resistance to side channels
672 * @param k_bn the scalar
673 * @param rng a random number generator
674 * @return base_point*k
675 */
676 BOTAN_DEPRECATED("Use EC_AffinePoint and EC_Scalar")
677 EC_Point blinded_base_point_multiply(const BigInt& k_bn,
678 RandomNumberGenerator& rng,
679 std::vector<BigInt>& /*ws*/) const {
680 const auto k = EC_Scalar::from_bigint(*this, k_bn);
681 const auto pt = EC_AffinePoint::g_mul(k, rng);
682 return pt.to_legacy_point();
683 }
684
685 /**
686 * Blinded point multiplication, attempts resistance to side channels
687 * Returns just the x coordinate of the point
688 *
689 * @param k_bn the scalar
690 * @param rng a random number generator
691 * @return x coordinate of base_point*k
692 */
693 BOTAN_DEPRECATED("Use EC_AffinePoint and EC_Scalar")
694 BigInt blinded_base_point_multiply_x(const BigInt& k_bn,
695 RandomNumberGenerator& rng,
696 std::vector<BigInt>& /*ws*/) const {
697 const auto k = EC_Scalar::from_bigint(*this, k_bn);
698 return BigInt(EC_AffinePoint::g_mul(k, rng).x_bytes());
699 }
700
701 /**
702 * Blinded point multiplication, attempts resistance to side channels
703 * @param point input point
704 * @param k_bn the scalar
705 * @param rng a random number generator
706 * @return point*k
707 */
708 BOTAN_DEPRECATED("Use EC_AffinePoint and EC_Scalar")
709 EC_Point blinded_var_point_multiply(const EC_Point& point,
710 const BigInt& k_bn,
711 RandomNumberGenerator& rng,
712 std::vector<BigInt>& /*ws*/) const {
713 const auto k = EC_Scalar::from_bigint(*this, k_bn);
714 const auto pt = EC_AffinePoint(*this, point);
715 return pt.mul(k, rng).to_legacy_point();
716 }
717
718 /**
719 * Return a random scalar ie an integer in [1,order)
720 */
721 BOTAN_DEPRECATED("Use EC_Scalar::random") BigInt random_scalar(RandomNumberGenerator& rng) const {
722 return EC_Scalar::random(*this, rng).to_bigint();
723 }
724
725 /**
726 * Hash onto the curve.
727 * For some curve types no mapping is currently available, in this
728 * case this function will throw an exception.
729 *
730 * @param hash_fn the hash function to use (typically "SHA-256" or "SHA-512")
731 * @param input the input to hash
732 * @param input_len length of input in bytes
733 * @param domain_sep a domain separator
734 * @param domain_sep_len length of domain_sep in bytes
735 * @param random_oracle if the mapped point must be uniform (use
736 "true" here unless you know what you are doing)
737 */
738 BOTAN_DEPRECATED("Use EC_AffinePoint")
739 EC_Point hash_to_curve(std::string_view hash_fn,
740 const uint8_t input[],
741 size_t input_len,
742 const uint8_t domain_sep[],
743 size_t domain_sep_len,
744 bool random_oracle = true) const {
745 const auto inp = std::span{input, input_len};
746 const auto dst = std::span{domain_sep, domain_sep_len};
747
748 if(random_oracle) {
749 return EC_AffinePoint::hash_to_curve_ro(*this, hash_fn, inp, dst).to_legacy_point();
750 } else {
751 return EC_AffinePoint::hash_to_curve_nu(*this, hash_fn, inp, dst).to_legacy_point();
752 }
753 }
754
755 /**
756 * Hash onto the curve.
757 * For some curve types no mapping is currently available, in this
758 * case this function will throw an exception.
759 *
760 * @param hash_fn the hash function to use (typically "SHA-256" or "SHA-512")
761 * @param input the input to hash
762 * @param input_len length of input in bytes
763 * @param domain_sep a domain separator
764 * @param random_oracle if the mapped point must be uniform (use
765 "true" here unless you know what you are doing)
766 */
767 BOTAN_DEPRECATED("Use EC_AffinePoint")
768 EC_Point hash_to_curve(std::string_view hash_fn,
769 const uint8_t input[],
770 size_t input_len,
771 std::string_view domain_sep,
772 bool random_oracle = true) const {
773 const auto inp = std::span{input, input_len};
774
775 if(random_oracle) {
776 return EC_AffinePoint::hash_to_curve_ro(*this, hash_fn, inp, domain_sep).to_legacy_point();
777 } else {
778 return EC_AffinePoint::hash_to_curve_nu(*this, hash_fn, inp, domain_sep).to_legacy_point();
779 }
780 }
781
782 /**
783 * Return a point on this curve with the affine values x, y
784 */
785 BOTAN_DEPRECATED("Deprecated - use EC_AffinePoint") EC_Point point(const BigInt& x, const BigInt& y) const {
786 if(auto pt = EC_AffinePoint::from_bigint_xy(*this, x, y)) {
787 return pt->to_legacy_point();
788 } else {
789 throw Decoding_Error("Invalid x/y coordinates for elliptic curve point");
790 }
791 }
792
793 /**
794 * Return the zero (or infinite) point on this curve
795 */
796 BOTAN_DEPRECATED("Deprecated no replacement") EC_Point zero_point() const {
797 return EC_AffinePoint::identity(*this).to_legacy_point();
798 }
799#endif
800
801 /**
802 * Return if a == -3 mod p
803 */
804 BOTAN_DEPRECATED("Deprecated no replacement") bool a_is_minus_3() const { return get_a() + 3 == get_p(); }
805
806 /**
807 * Return if a == 0 mod p
808 */
809 BOTAN_DEPRECATED("Deprecated no replacement") bool a_is_zero() const { return get_a().is_zero(); }
810
811 /**
812 * Reduce x modulo the order
813 * @param x the value to reduce
814 * @return x reduced modulo the group order
815 */
816 BOTAN_DEPRECATED("Use EC_Scalar") BigInt mod_order(const BigInt& x) const {
817 return EC_Scalar::from_bytes_mod_order(*this, x.serialize()).to_bigint();
818 }
819
820 /**
821 * Return inverse of x modulo the order
822 * @param x the value to invert
823 * @return the multiplicative inverse of x modulo the group order
824 */
825 BOTAN_DEPRECATED("Use EC_Scalar") BigInt inverse_mod_order(const BigInt& x) const {
826 return EC_Scalar::from_bigint(*this, x).invert().to_bigint();
827 }
828
829 /**
830 * Reduce (x*x) modulo the order
831 * @param x the value to square
832 * @return (x*x) reduced modulo the group order
833 */
834 BOTAN_DEPRECATED("Use EC_Scalar") BigInt square_mod_order(const BigInt& x) const {
835 auto xs = EC_Scalar::from_bigint(*this, x);
836 xs.square_self();
837 return xs.to_bigint();
838 }
839
840 /**
841 * Reduce (x*y) modulo the order
842 * @param x the first factor
843 * @param y the second factor
844 * @return (x*y) reduced modulo the group order
845 */
846 BOTAN_DEPRECATED("Use EC_Scalar") BigInt multiply_mod_order(const BigInt& x, const BigInt& y) const {
847 const auto xs = EC_Scalar::from_bigint(*this, x);
848 const auto ys = EC_Scalar::from_bigint(*this, y);
849 return (xs * ys).to_bigint();
850 }
851
852 /**
853 * Reduce (x*y*z) modulo the order
854 * @param x the first factor
855 * @param y the second factor
856 * @param z the third factor
857 * @return (x*y*z) reduced modulo the group order
858 */
859 BOTAN_DEPRECATED("Use EC_Scalar")
860 BigInt multiply_mod_order(const BigInt& x, const BigInt& y, const BigInt& z) const {
861 const auto xs = EC_Scalar::from_bigint(*this, x);
862 const auto ys = EC_Scalar::from_bigint(*this, y);
863 const auto zs = EC_Scalar::from_bigint(*this, z);
864 return (xs * ys * zs).to_bigint();
865 }
866
867 /**
868 * Return x^3 modulo the order
869 * @param x the value to cube
870 * @return (x*x*x) reduced modulo the group order
871 */
872 BOTAN_DEPRECATED("Deprecated no replacement") BigInt cube_mod_order(const BigInt& x) const {
873 const auto xs = EC_Scalar::from_bigint(*this, x);
874 return (xs * xs * xs).to_bigint();
875 }
876
877 /**
878 * Return the size in bytes of a point encoded in the given format
879 * @param format the point encoding format
880 * @return the length of the encoding in bytes
881 */
882 BOTAN_DEPRECATED("Just serialize the point and check") size_t point_size(EC_Point_Format format) const {
883 // Hybrid and standard format are (x,y), compressed is y, +1 format byte
884 if(format == EC_Point_Format::Compressed) {
885 return (1 + get_p_bytes());
886 } else {
887 return (1 + 2 * get_p_bytes());
888 }
889 }
890
891 private:
892 friend class EC_Group_Data_Map;
893 friend class EC_Scalar;
894 friend class EC_AffinePoint;
895
896 static EC_Group_Data_Map& ec_group_data();
897
898 explicit EC_Group(std::shared_ptr<const EC_Group_Data> data);
899
900 static bool verify_generator_order(std::shared_ptr<const EC_Group_Data> data);
901
902 static std::pair<std::shared_ptr<EC_Group_Data>, bool> DER_decode_EC_group(std::span<const uint8_t> der,
904
905 static std::shared_ptr<EC_Group_Data> load_EC_group_info(const char* p,
906 const char* a,
907 const char* b,
908 const char* g_x,
909 const char* g_y,
910 const char* order,
911 const OID& oid);
912
913 const EC_Group_Data& data() const;
914
915 // Member data
916 std::shared_ptr<const EC_Group_Data> m_data;
917 bool m_explicit_encoding = false;
918};
919
920/**
921* Test if two groups describe different curves
922* @param lhs the first group
923* @param rhs the second group
924* @return true if the two groups are not equal
925*/
926inline bool operator!=(const EC_Group& lhs, const EC_Group& rhs) {
927 return !(lhs == rhs);
928}
929
930} // namespace Botan
931
932#endif
#define BOTAN_PUBLIC_API(maj, min)
Definition api.h:21
#define BOTAN_DEPRECATED(msg)
Definition api.h:73
#define BOTAN_FUTURE_EXPLICIT
Definition api.h:52
Mul2Table & operator=(const Mul2Table &other)=delete
Mul2Table(const Mul2Table &other)=delete
Mul2Table(Mul2Table &&other) noexcept
std::optional< EC_AffinePoint > mul2_vartime(const EC_Scalar &x, const EC_Scalar &y) const
Definition ec_group.cpp:978
BOTAN_FUTURE_EXPLICIT Mul2Table(const EC_AffinePoint &h)
Definition ec_group.cpp:974
Mul2Table & operator=(Mul2Table &&other) noexcept
bool mul2_vartime_x_mod_order_eq(const EC_Scalar &v, const EC_Scalar &x, const EC_Scalar &y) const
Definition ec_group.cpp:987
bool a_is_minus_3() const
Definition ec_group.h:804
static EC_Group EC_Group_from_PEM(std::string_view pem)
Definition ec_group.h:268
static EC_Group from_PEM(std::string_view pem)
Definition ec_group.cpp:572
const BigInt & get_b() const
Definition ec_group.cpp:745
const BigInt & get_a() const
Definition ec_group.cpp:741
bool initialized() const
Definition ec_group.h:317
const std::shared_ptr< const EC_Group_Data > & _data() const
Definition ec_group.h:604
const BigInt & get_g_y() const
Definition ec_group.cpp:793
friend class EC_Scalar
Definition ec_group.h:893
const BigInt & get_cofactor() const
Definition ec_group.cpp:797
BigInt mod_order(const BigInt &x) const
Definition ec_group.h:816
BigInt cube_mod_order(const BigInt &x) const
Definition ec_group.h:872
static EC_Group register_custom_group(const OID &oid, const BigInt &p, const BigInt &a, const BigInt &b, const BigInt &base_x, const BigInt &base_y, const BigInt &order)
Definition ec_group.cpp:630
BigInt multiply_mod_order(const BigInt &x, const BigInt &y) const
Definition ec_group.h:846
EC_Group_Source source() const
Definition ec_group.cpp:809
bool a_is_zero() const
Definition ec_group.h:809
const BigInt & get_p() const
Definition ec_group.cpp:737
const BigInt & get_order() const
Definition ec_group.cpp:785
static EC_Group from_OID(const OID &oid)
Definition ec_group.cpp:518
static std::shared_ptr< EC_Group_Data > EC_group_info(const OID &oid)
Definition ec_named.cpp:16
const BigInt & get_g_x() const
Definition ec_group.cpp:789
bool used_explicit_encoding() const
Definition ec_group.h:364
EC_Group(const BigInt &p, const BigInt &a, const BigInt &b, const BigInt &base_x, const BigInt &base_y, const BigInt &order, const BigInt &cofactor, const OID &oid=OID())
Definition ec_group.cpp:577
const OID & get_curve_oid() const
Definition ec_group.cpp:805
BigInt square_mod_order(const BigInt &x) const
Definition ec_group.h:834
bool has_cofactor() const
Definition ec_group.cpp:801
static size_t clear_registered_curve_data()
Definition ec_group.cpp:252
BigInt inverse_mod_order(const BigInt &x) const
Definition ec_group.h:825
static bool unregister(const OID &oid)
Definition ec_group.cpp:710
friend class EC_Group_Data_Map
Definition ec_group.h:892
size_t point_size(EC_Point_Format format) const
Definition ec_group.h:882
size_t get_p_bytes() const
Definition ec_group.cpp:725
static OID EC_group_identity_from_order(const BigInt &order)
Definition ec_named.cpp:357
bool hash_to_curve_supported(std::string_view hash_fn) const
Definition ec_group.cpp:817
friend class EC_AffinePoint
Definition ec_group.h:894
static EC_Scalar from_bigint(const EC_Group &group, const BigInt &bn)
Definition ec_scalar.cpp:84
static EC_Scalar from_bytes_mod_order(const EC_Group &group, std::span< const uint8_t > bytes)
Definition ec_scalar.cpp:68
const char * name
Definition ffi_tls.h:59
EC_Group_Engine
Definition ec_group.h:48
@ Optimized
Using per curve implementation; fastest available.
Definition ec_group.h:50
@ Generic
A generic implementation that handles many curves in one implementation.
Definition ec_group.h:52
bool operator!=(const AlgorithmIdentifier &x, const AlgorithmIdentifier &y)
Definition alg_id.cpp:58
bool operator==(const AlgorithmIdentifier &x, const AlgorithmIdentifier &y)
Definition alg_id.cpp:54
EC_Group_Source
Definition ec_group.h:38
EC_Point OS2ECP(std::span< const uint8_t > data, const CurveGFp &curve)
Definition ec_point.cpp:866