ec_group.rst - mozsearch

Enable keyboard shortcuts

EC_Group

========================

This class represents a set of elliptic curve parameters. Only curves over prime

fields are supported.

.. cpp:class:: EC_Group

      .. cpp:function:: static bool EC_Group::supports_named_group(std::string_view name)

         Check if the named group is supported.

      .. cpp:function:: static bool EC_Group::supports_application_specific_group()

         Check if application specific groups are supported.

      .. cpp:function:: EC_Group::from_OID(const OID& oid)

         Initialize an ``EC_Group`` using an OID referencing the curve

         parameters.

      .. cpp:function:: EC_Group::from_name(std::string_view name)

         Initialize an ``EC_Group`` using a name (such as "secp256r1")

         The curve may not be available, based on the build configuration.

         If this is the case this function will throw `Not_Implemented`.

      .. cpp:function:: EC_Group::from_PEM(std::string_view pem)

         Initialize an ``EC_Group`` using a PEM encoded parameter block

      .. cpp:function:: 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)

          Create an application specific elliptic curve.

          .. warning::

             Using application specific curves may be hazardous to your health.

          This constructor imposes the following restrictions:

          * The prime must be between 192 and 512 bits, and a multiple of 32 bits.

          * As a special extension regarding the above restriction, the prime may

            alternately be 521 bits, in which case it must be exactly 2**521-1.

            It can also be 239 bits, in which case it must be the X9.63 239-bit prime.

          * The prime must be congruent to 3 modulo 4

          * The group order must have identical bitlength to the prime

          * No cofactor is allowed

          * An object identifier must be specified

      .. cpp:function:: 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())

          This is a deprecated alternative interface for creating application

          specific elliptic curves.

          This does not impose the same restrictions regarding use of

          arbitrary sized groups, use of a cofactor, etc, and the

          object identifier is optional.

          .. warning::

             If you are using this constructor, and cannot use the

             non-deprecated constructor due to the restrictions it places on the

             curve parameters, be aware that this constructor will be dropped

             in Botan 4. Please open an issue on Github describing your usecase.

      .. cpp:function:: EC_Group(std::span<const uint8_t> ber_encoding)

         Initialize an ``EC_Group`` by decoding a DER encoded parameter block.

      .. cpp:function:: std::vector<uint8_t> DER_encode() const

         Return the DER encoding of this group.

      .. cpp:function:: std::vector<uint8_t> DER_encode(EC_Group_Encoding form) const

         Return the DER encoding of this group. This variant is deprecated, but allows

         the curve to be encoded using the explicit (vs OID) encoding. All support for

         explicitly encoded elliptic curves is deprecated and will be removed in Botan4.

      .. cpp:function:: std::string PEM_encode() const

         Return the PEM encoding of this group (base64 of DER encoding plus

         header/trailer).

      .. cpp:function:: const BigInt& get_p() const

         Return the prime modulus as a :cpp:class:`BigInt`

      .. cpp:function:: const BigInt& get_a() const

         Return the ``a`` parameter of the elliptic curve equation as a :cpp:class:`BigInt`

      .. cpp:function:: const BigInt& get_b() const

         Return the ``b`` parameter of the elliptic curve equation as a :cpp:class:`BigInt`

      .. cpp:function:: const BigInt& get_g_x() const

         Return the x coordinate of the base point element as a :cpp:class:`BigInt`

      .. cpp:function:: const BigInt& get_g_y() const

         Return the y coordinate of the base point element as a :cpp:class:`BigInt`

      .. cpp:function:: const BigInt& get_order() const

         Return the order of the group generated by the base point as a :cpp:class:`BigInt`

      .. cpp:function:: const BigInt& get_cofactor() const

         Return the cofactor of the curve. In most cases this will be 1.

         .. warning::

            In Botan4 all support for elliptic curves group with a

            cofactor > 1 will be removed.

      .. cpp:function:: const OID& get_curve_oid() const

         Return the OID used to identify this curve. May be empty.

         .. note::

            Botan4 will remove the ability to create elliptic curves without an

            object identifier.

      .. cpp:function:: bool verify_group(RandomNumberGenerator& rng, bool strong = false) const

         Attempt to verify the group seems valid.

      .. cpp:function:: static const std::set<std::string>& known_named_groups()

         Return a list of known groups, ie groups for which ``EC_Group::from_name(name)``

         will succeed.