|
Botan 3.14.1
Crypto and TLS for C&
|
#include <ec_group.h>
Classes | |
| class | Mul2Table |
Public Member Functions | |
| const std::shared_ptr< const EC_Group_Data > & | _data () const |
| bool | a_is_minus_3 () const |
| bool | a_is_zero () const |
| BigInt | cube_mod_order (const BigInt &x) const |
| std::vector< uint8_t > | DER_encode () const |
| std::vector< uint8_t > | DER_encode (EC_Group_Encoding form) const |
| EC_Group () | |
| 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()) | |
| EC_Group (const EC_Group &) | |
| EC_Group (const OID &oid) | |
| EC_Group (const OID &oid, const BigInt &p, const BigInt &a, const BigInt &b, const BigInt &base_x, const BigInt &base_y, const BigInt &order) | |
| EC_Group (const uint8_t der[], size_t der_len) | |
| EC_Group (EC_Group &&)=default | |
| EC_Group (std::span< const uint8_t > der) | |
| EC_Group (std::string_view pem_or_oid) | |
| EC_Group_Engine | engine () const |
| const BigInt & | get_a () const |
| const BigInt & | get_b () const |
| const BigInt & | get_cofactor () const |
| const OID & | get_curve_oid () const |
| const BigInt & | get_g_x () const |
| const BigInt & | get_g_y () const |
| const BigInt & | get_order () const |
| size_t | get_order_bits () const |
| size_t | get_order_bytes () const |
| const BigInt & | get_p () const |
| size_t | get_p_bits () const |
| size_t | get_p_bytes () const |
| bool | has_cofactor () const |
| bool | hash_to_curve_supported (std::string_view hash_fn) const |
| bool | initialized () const |
| BigInt | inverse_mod_order (const BigInt &x) const |
| BigInt | mod_order (const BigInt &x) const |
| BigInt | multiply_mod_order (const BigInt &x, const BigInt &y) const |
| BigInt | multiply_mod_order (const BigInt &x, const BigInt &y, const BigInt &z) const |
| EC_Group & | operator= (const EC_Group &) |
| EC_Group & | operator= (EC_Group &&)=default |
| bool | operator== (const EC_Group &other) const |
| std::string | PEM_encode (EC_Group_Encoding form=EC_Group_Encoding::Explicit) const |
| size_t | point_size (EC_Point_Format format) const |
| EC_Group_Source | source () const |
| BigInt | square_mod_order (const BigInt &x) const |
| bool | used_explicit_encoding () const |
| bool | verify_group (RandomNumberGenerator &rng, bool strong=false) const |
| ~EC_Group () | |
Static Public Member Functions | |
| static size_t | clear_registered_curve_data () |
| static EC_Group | EC_Group_from_PEM (std::string_view pem) |
| static OID | EC_group_identity_from_order (const BigInt &order) |
| static std::shared_ptr< EC_Group_Data > | EC_group_info (const OID &oid) |
| static EC_Group | from_name (std::string_view name) |
| static EC_Group | from_OID (const OID &oid) |
| static EC_Group | from_PEM (std::string_view pem) |
| static const std::set< std::string > & | known_named_groups () |
| 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) |
| static bool | supports_application_specific_group () |
| static bool | supports_application_specific_group_with_cofactor () |
| static bool | supports_named_group (std::string_view name) |
| static bool | unregister (const OID &oid) |
Friends | |
| class | EC_AffinePoint |
| class | EC_Group_Data_Map |
| class | EC_Scalar |
Class representing an elliptic curve
The internal representation is stored in a shared_ptr, so copying an EC_Group is inexpensive.
Definition at line 69 of file ec_group.h.
| Botan::EC_Group::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() ) |
Construct elliptic curve from the specified parameters
This is used for example to create custom (application-specific) curves.
Some build configurations do not support application specific curves, in which case this constructor will throw an exception. You can check for this situation beforehand using the function EC_Group::supports_application_specific_group()
| p | the elliptic curve p |
| a | the elliptic curve a param |
| b | the elliptic curve b param |
| base_x | the x coordinate of the base point |
| base_y | the y coordinate of the base point |
| order | the order of the base point |
| cofactor | the cofactor |
| oid | an optional OID used to identify this curve |
Definition at line 577 of file ec_group.cpp.
References Botan::abs(), Botan::BigInt::bits(), BOTAN_ARG_CHECK, Botan::ExternalSource, Botan::Barrett_Reduction::for_public_modulus(), Botan::BigInt::from_s32(), Botan::OID::has_value(), and Botan::is_bailie_psw_probable_prime_vartime().
Referenced by EC_AffinePoint, EC_Group(), EC_Group(), EC_Group(), EC_Group(), EC_Group(), EC_Group(), EC_Group_from_PEM(), from_name(), from_OID(), from_PEM(), operator=(), operator=(), operator==(), register_custom_group(), and ~EC_Group().
| Botan::EC_Group::EC_Group | ( | const OID & | oid, |
| const BigInt & | p, | ||
| const BigInt & | a, | ||
| const BigInt & | b, | ||
| const BigInt & | base_x, | ||
| const BigInt & | base_y, | ||
| const BigInt & | order ) |
Construct elliptic curve from the specified parameters
This is used for example to create custom (application-specific) curves.
Calling this function registers these parameters within the persistent state of the library; for example once this call completes, an ECDSA key specifying its namedCurve matching the provided OID can be decoded, and this remains true even after the EC_Group created has been destroyed. If necessary you can unregister the group using EC_Group::unregister.
Some build configurations do not support application specific curves, in which case this function will throw an exception. You can check for this situation beforehand using the function EC_Group::supports_application_specific_group()
The following constraints are imposed on the parameters:
| oid | an object identifier used to identify this curve |
| p | the elliptic curve prime (at most 521 bits) |
| a | the elliptic curve a param |
| b | the elliptic curve b param |
| base_x | the x coordinate of the group generator |
| base_y | the y coordinate of the group generator |
| order | the order of the group |
Definition at line 620 of file ec_group.cpp.
References EC_Group(), and register_custom_group().
|
explicit |
Decode a DER encoded ECC domain parameter set
| der | the bytes of the DER encoding |
Definition at line 703 of file ec_group.cpp.
References Botan::ExternalSource.
|
inline |
Decode a DER encoded ECC domain parameter set
| der | the bytes of the DER encoding |
| der_len | the length of der in bytes |
Definition at line 230 of file ec_group.h.
References EC_Group().
|
inlineexplicit |
Create an EC domain by OID (or throw if unknown)
| oid | the OID of the EC domain to create |
Definition at line 236 of file ec_group.h.
References EC_Group(), and from_OID().
|
explicit |
Create an EC domain from PEM encoding (as from PEM_encode()), or from an OID name (eg "secp256r1", or "1.2.840.10045.3.1.7")
| pem_or_oid | PEM-encoded data, or an OID |
Definition at line 543 of file ec_group.cpp.
References Botan::PEM_Code::decode_check_label(), Botan::ExternalSource, Botan::fmt(), Botan::OID::from_string(), and Botan::OID::has_value().
|
default |
Create an uninitialized EC_Group
References EC_Group(), and unregister().
Referenced by from_name(), from_OID(), from_PEM(), and register_custom_group().
|
default |
References EC_Group().
|
default |
Copy constructor
References EC_Group().
|
default |
Move constructor
References EC_Group().
|
inline |
For internal use only
Definition at line 604 of file ec_group.h.
|
inline |
Return if a == -3 mod p
Definition at line 804 of file ec_group.h.
References a_is_minus_3(), get_a(), and get_p().
Referenced by a_is_minus_3().
|
inline |
Return if a == 0 mod p
Definition at line 809 of file ec_group.h.
References a_is_zero(), and get_a().
Referenced by a_is_zero().
|
static |
Discard all cached and application registered group data
For internal use only
TODO(Botan4): Move this to an internal header
Definition at line 252 of file ec_group.cpp.
Return x^3 modulo the order
| x | the value to cube |
Definition at line 872 of file ec_group.h.
References cube_mod_order(), and Botan::EC_Scalar::from_bigint().
Referenced by cube_mod_order().
| std::vector< uint8_t > Botan::EC_Group::DER_encode | ( | ) | const |
Create the DER encoding of this domain, using namedCurve format
Definition at line 821 of file ec_group.cpp.
Referenced by DER_encode(), and PEM_encode().
| std::vector< uint8_t > Botan::EC_Group::DER_encode | ( | EC_Group_Encoding | form | ) | const |
Create the DER encoding of this domain
| form | of encoding to use |
Definition at line 831 of file ec_group.cpp.
References DER_encode(), Botan::DER_Encoder::encode(), Botan::DER_Encoder::end_cons(), Botan::Explicit, Botan::EC_AffinePoint::generator(), get_a(), get_b(), get_cofactor(), get_order(), get_p(), get_p_bytes(), Botan::ImplicitCA, Botan::NamedCurve, Botan::OctetString, Botan::EC_AffinePoint::serialize_uncompressed(), and Botan::DER_Encoder::start_sequence().
Referenced by Botan::EC_PublicKey::DER_domain().
|
inlinestatic |
Initialize an EC group from the PEM/ASN.1 encoding
| PEM | the PEM encoded group |
Definition at line 268 of file ec_group.h.
References BOTAN_DEPRECATED, EC_Group(), EC_Group_from_PEM(), and from_PEM().
Referenced by EC_Group_from_PEM().
Identify a builtin group by its order
For internal use only
| order | the group order to look up |
TODO(Botan4): Move this to an internal header
Definition at line 357 of file ec_named.cpp.
References Botan::BigInt::word_at().
|
static |
Look up the parameters of a builtin group by OID
For internal use only
| oid | the OID of the group to look up |
TODO(Botan4): Move this to an internal header
Definition at line 16 of file ec_named.cpp.
Referenced by Botan::EC_Group_Data::EC_Group_Data().
| EC_Group_Engine Botan::EC_Group::engine | ( | ) | const |
Return how this EC_Group is implemented under the hood
This is mostly useful for diagnostic or debugging purposes
Definition at line 813 of file ec_group.cpp.
|
static |
Initialize an EC group from a group common name (eg "secp256r1")
Definition at line 529 of file ec_group.cpp.
References EC_Group(), EC_Group(), Botan::fmt(), Botan::OID::from_name(), and name.
Referenced by botan_ec_group_from_name(), Botan::create_private_key(), Botan::TLS::Callbacks::tls_deserialize_peer_public_key(), and Botan::TLS::Callbacks::tls_generate_ephemeral_key().
Initialize an EC group from a group named by an object identifier
Definition at line 518 of file ec_group.cpp.
References EC_Group(), EC_Group(), Botan::fmt(), and Botan::OID::to_string().
Referenced by botan_ec_group_from_oid(), EC_Group(), and Botan::GOST_3410_PublicKey::GOST_3410_PublicKey().
|
static |
Initialize an EC group from the PEM/ASN.1 encoding
Definition at line 572 of file ec_group.cpp.
References Botan::PEM_Code::decode_check_label(), EC_Group(), and EC_Group().
Referenced by botan_ec_group_from_pem(), and EC_Group_from_PEM().
| const BigInt & Botan::EC_Group::get_a | ( | ) | const |
Return the a parameter of the elliptic curve equation
Definition at line 741 of file ec_group.cpp.
Referenced by a_is_minus_3(), a_is_zero(), DER_encode(), Botan::EC_PublicKey::get_int_field(), operator==(), and verify_group().
| const BigInt & Botan::EC_Group::get_b | ( | ) | const |
Return the b parameter of the elliptic curve equation
Definition at line 745 of file ec_group.cpp.
Referenced by DER_encode(), Botan::EC_PublicKey::get_int_field(), operator==(), and verify_group().
| const BigInt & Botan::EC_Group::get_cofactor | ( | ) | const |
Return the cofactor
Definition at line 797 of file ec_group.cpp.
Referenced by DER_encode(), Botan::EC_PublicKey::get_int_field(), operator==(), and verify_group().
| const OID & Botan::EC_Group::get_curve_oid | ( | ) | const |
Return the OID of these domain parameters
Definition at line 805 of file ec_group.cpp.
Referenced by Botan::GOST_3410_PublicKey::algorithm_identifier(), and Botan::TPM2::EC_PrivateKey::create_unrestricted_transient().
| const BigInt & Botan::EC_Group::get_g_x | ( | ) | const |
Return the x coordinate of the base point
Definition at line 789 of file ec_group.cpp.
Referenced by Botan::EC_PublicKey::get_int_field(), operator==(), and verify_group().
| const BigInt & Botan::EC_Group::get_g_y | ( | ) | const |
Return the y coordinate of the base point
Definition at line 793 of file ec_group.cpp.
Referenced by Botan::EC_PublicKey::get_int_field(), operator==(), and verify_group().
| const BigInt & Botan::EC_Group::get_order | ( | ) | const |
Return the order of the base point
Definition at line 785 of file ec_group.cpp.
Referenced by DER_encode(), Botan::EC_PublicKey::get_int_field(), operator==(), and verify_group().
| size_t Botan::EC_Group::get_order_bits | ( | ) | const |
Return the size of group order in bits (same as get_order().bits())
Definition at line 729 of file ec_group.cpp.
| size_t Botan::EC_Group::get_order_bytes | ( | ) | const |
Return the size of the group order in bytes (same as get_order().bytes())
Definition at line 733 of file ec_group.cpp.
Referenced by Botan::ECDSA_PublicKey::_signature_element_size_for_DER_encoding(), Botan::GOST_3410_PublicKey::_signature_element_size_for_DER_encoding(), Botan::SM2_PublicKey::_signature_element_size_for_DER_encoding(), and Botan::SPAKE2p::RegistrationRecord::deserialize().
| const BigInt & Botan::EC_Group::get_p | ( | ) | const |
Return the prime modulus of the field
Definition at line 737 of file ec_group.cpp.
Referenced by a_is_minus_3(), DER_encode(), Botan::EC_PublicKey::get_int_field(), operator==(), and verify_group().
| size_t Botan::EC_Group::get_p_bits | ( | ) | const |
Return the size of p in bits (same as get_p().bits())
Definition at line 721 of file ec_group.cpp.
Referenced by Botan::GOST_3410_PublicKey::algo_name(), and Botan::EC_PublicKey::key_length().
| size_t Botan::EC_Group::get_p_bytes | ( | ) | const |
Return the size of p in bytes (same as get_p().bytes())
Definition at line 725 of file ec_group.cpp.
Referenced by DER_encode(), and point_size().
| bool Botan::EC_Group::has_cofactor | ( | ) | const |
Return true if the cofactor is > 1 TODO(Botan4): Remove this
Definition at line 801 of file ec_group.cpp.
Referenced by verify_group().
| bool Botan::EC_Group::hash_to_curve_supported | ( | std::string_view | hash_fn | ) | const |
Return true if RFC 9380 hash to curve is supported for this group with the specified hash function
If this returns true then EC_AffinePoint::hash_to_curve_ro and EC_AffinePoint::hash_to_curve_nu will work for this group and hash.
This checks that the hash function is available and satisfies the RFC 9380 requirements for this group (in particular that the hash output is at least twice the target security level), that the curve implementation supports hash to curve, and that the required message expansion (currently just expand_message_xmd) is included in the build.
Definition at line 817 of file ec_group.cpp.
|
inline |
Return true if this group has been initialized with domain parameters
This is only false for groups created using the deprecated default constructor.
Definition at line 317 of file ec_group.h.
References initialized().
Referenced by initialized().
Return inverse of x modulo the order
| x | the value to invert |
Definition at line 825 of file ec_group.h.
References Botan::EC_Scalar::from_bigint(), and inverse_mod_order().
Referenced by inverse_mod_order().
|
static |
Return a set of known named EC groups
This returns a set of groups for which from_name should succeed.
Note that the set of included groups can vary based on the build configuration, and that this list does not include any groups registered by the application at runtime.
Definition at line 477 of file ec_named.cpp.
Referenced by supports_named_group().
Reduce x modulo the order
| x | the value to reduce |
Definition at line 816 of file ec_group.h.
References Botan::EC_Scalar::from_bytes_mod_order(), and mod_order().
Referenced by mod_order().
Reduce (x*y) modulo the order
| x | the first factor |
| y | the second factor |
Definition at line 846 of file ec_group.h.
References Botan::EC_Scalar::from_bigint(), and multiply_mod_order().
Referenced by multiply_mod_order(), and multiply_mod_order().
|
inline |
Reduce (x*y*z) modulo the order
| x | the first factor |
| y | the second factor |
| z | the third factor |
Definition at line 860 of file ec_group.h.
References Botan::EC_Scalar::from_bigint(), and multiply_mod_order().
| bool Botan::EC_Group::operator== | ( | const EC_Group & | other | ) | const |
Test if two groups describe the same curve
| other | the group to compare against |
Definition at line 871 of file ec_group.cpp.
References EC_Group(), get_a(), get_b(), get_cofactor(), get_g_x(), get_g_y(), get_order(), and get_p().
| std::string Botan::EC_Group::PEM_encode | ( | EC_Group_Encoding | form = EC_Group_Encoding::Explicit | ) | const |
Return the PEM encoding
TODO(Botan4) remove the argument
Definition at line 866 of file ec_group.cpp.
References DER_encode(), and Botan::PEM_Code::encode().
|
inline |
Return the size in bytes of a point encoded in the given format
| format | the point encoding format |
Definition at line 882 of file ec_group.h.
References Botan::Compressed, get_p_bytes(), and point_size().
Referenced by point_size().
|
static |
Construct elliptic curve from the specified parameters
This is used for example to create custom (application-specific) curves.
This function registers these parameters within the persistent state of the library; for example once this call completes, an ECDSA key specifying its namedCurve matching the provided OID can be decoded, and this remains true even after the EC_Group returned here has been destroyed. If necessary you can unregister the group using EC_Group::unregister.
Some build configurations do not support application specific curves, in which case this function will throw an exception. You can check for this situation beforehand using the function EC_Group::supports_application_specific_group()
Unlike the deprecated constructor, this function imposes additional restrictions on the parameters, namely:
| oid | an object identifier used to identify this curve |
| p | the elliptic curve prime (at most 521 bits) |
| a | the elliptic curve a param |
| b | the elliptic curve b param |
| base_x | the x coordinate of the group generator |
| base_y | the y coordinate of the group generator |
| order | the order of the group |
Definition at line 630 of file ec_group.cpp.
References Botan::abs(), Botan::BigInt::bits(), BOTAN_ARG_CHECK, EC_Group(), EC_Group(), Botan::ExternalSource, Botan::Barrett_Reduction::for_public_modulus(), Botan::BigInt::from_s32(), Botan::OID::has_value(), Botan::is_bailie_psw_probable_prime_vartime(), Botan::BigInt::power_of_2(), and Botan::BigInt::set_bit().
Referenced by botan_ec_group_from_params(), and EC_Group().
| EC_Group_Source Botan::EC_Group::source | ( | ) | const |
Return how this group was created, eg from a builtin table or by decoding an external encoding
Definition at line 809 of file ec_group.cpp.
Referenced by EC_AffinePoint, and verify_group().
Reduce (x*x) modulo the order
| x | the value to square |
Definition at line 834 of file ec_group.h.
References Botan::EC_Scalar::from_bigint(), and square_mod_order().
Referenced by square_mod_order().
|
static |
Return true if in this build configuration it is possible to register an application specific elliptic curve.
Definition at line 500 of file ec_group.cpp.
Referenced by botan_ec_group_supports_application_specific_group().
|
static |
Return true if in this build configuration it is possible to register an application specific elliptic curve with a cofactor larger than 1.
Definition at line 509 of file ec_group.cpp.
|
static |
Return true if EC_Group::from_name(name) should succeed for this name either because it is a group compiled into the library or it is a group which has already been registered by the application at runtime.
Definition at line 473 of file ec_group.cpp.
References Botan::OID::from_name(), known_named_groups(), and name.
Referenced by botan_ec_group_supports_named_group(), Botan::HPKE::KEM_Ops::create(), Botan::create_private_key(), and Botan::TLS::Group_Params::is_available().
|
static |
Unregister a previously registered group.
Using this is discouraged for normal use. This is only useful or necessary if you are registering a very large number of distinct groups, and need to worry about memory constraints.
Returns true if the group was found and unregistered.
Definition at line 710 of file ec_group.cpp.
Referenced by botan_ec_group_unregister(), and EC_Group().
|
inline |
Return true if this EC_Group was derived from an explicit encoding
Explicit encoding of groups is deprecated; when support for explicit curves is removed in a future major release, this function will also be removed.
Definition at line 364 of file ec_group.h.
Referenced by botan_pubkey_ecc_key_used_explicit_encoding().
| bool Botan::EC_Group::verify_group | ( | RandomNumberGenerator & | rng, |
| bool | strong = false ) const |
Verify EC_Group domain
Definition at line 881 of file ec_group.cpp.
References Botan::abs(), Botan::BigInt::bits(), Botan::Builtin, Botan::Barrett_Reduction::for_public_modulus(), Botan::BigInt::from_s32(), get_a(), get_b(), get_cofactor(), get_g_x(), get_g_y(), get_order(), get_p(), has_cofactor(), Botan::is_prime_vartime(), source(), and Botan::BigInt::square().
Referenced by Botan::EC_PublicKey::check_key().
|
friend |
Definition at line 894 of file ec_group.h.
References EC_AffinePoint, EC_Group(), EC_Group_Data_Map, and source().
Referenced by EC_AffinePoint, and Botan::EC_Group::Mul2Table::Mul2Table().
|
friend |
Definition at line 892 of file ec_group.h.
References EC_Group_Data_Map.
Referenced by EC_AffinePoint, and EC_Group_Data_Map.
|
friend |
Definition at line 893 of file ec_group.h.
References EC_Scalar.
Referenced by EC_Scalar, Botan::EC_Group::Mul2Table::mul2_vartime(), Botan::EC_Group::Mul2Table::mul2_vartime_x_mod_order_eq(), and Botan::EC_Group::Mul2Table::mul2_vartime_x_mod_order_eq().