# Elliptic Curve Operations

In addition to high level operations for signatures, key agreement, and message encryption using elliptic curve cryptography, the library contains lower level interfaces for performing operations such as elliptic curve point multiplication.

Only curves over prime fields are supported.

Many of these functions take a workspace, either a vector of words or a vector of BigInts. These are used to minimize memory allocations during common operations.

Warning

You should only use these interfaces if you know what you are doing.

class `EC_Group`
  `EC_Group`(const OID &oid)

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

  `EC_Group`(const std::string &name)

    Initialize an `EC_Group` using a name or OID (for example “secp256r1”, or “1.2.840.10045.3.1.7”)

  `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())

    Initialize an elliptic curve group from the relevant parameters. This is used for example to create custom (application-specific) curves.

  `EC_Group`(const std::vector<uint8_t> &ber_encoding)

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

  std::vector<uint8_t> `DER_encode`(EC_Group_Encoding form) const

    Return the DER encoding of this group.

  std::string `PEM_encode`() const

    Return the PEM encoding of this group (base64 of DER encoding plus header/trailer).

  bool `a_is_minus_3`() const

    Return true if the `a` parameter is congruent to -3 mod p.

  bool `a_is_zero`() const

    Return true if the `a` parameter is congruent to 0 mod p.

  size_t `get_p_bits`() const

    Return size of the prime in bits.

  size_t `get_p_bytes`() const

    Return size of the prime in bytes.

  size_t `get_order_bits`() const

    Return size of the group order in bits.

  size_t `get_order_bytes`() const

    Return size of the group order in bytes.

  const BigInt &`get_p`() const

    Return the prime modulus.

  const BigInt &`get_a`() const

    Return the `a` parameter of the elliptic curve equation.

  const BigInt &`get_b`() const

    Return the `b` parameter of the elliptic curve equation.

  const PointGFp &`get_base_point`() const

    Return the groups base point element.

  const BigInt &`get_g_x`() const

    Return the x coordinate of the base point element.

  const BigInt &`get_g_y`() const

    Return the y coordinate of the base point element.

  const BigInt &`get_order`() const

    Return the order of the group generated by the base point.

  const BigInt &`get_cofactor`() const

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

  BigInt `mod_order`(const BigInt &x) const

    Reduce argument `x` modulo the curve order.

  BigInt `inverse_mod_order`(const BigInt &x) const

    Return inverse of argument `x` modulo the curve order.

  BigInt `multiply_mod_order`(const BigInt &x, const BigInt &y) const

    Multiply `x` and `y` and reduce the result modulo the curve order.

  bool `verify_public_element`(const PointGFp &y) const

    Return true if `y` seems to be a valid group element.

  const OID &`get_curve_oid`() const

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

  PointGFp `point`(const BigInt &x, const BigInt &y) const

    Create and return a point with affine elements `x` and `y`. Note this function does not verify that `x` and `y` satisfy the curve equation.

  PointGFp `point_multiply`(const BigInt &x, const PointGFp &pt, const BigInt &y) const

    Multi-exponentiation. Returns base_point*x + pt*y. Not constant time. (Ordinarily used for signature verification.)

  PointGFp `blinded_base_point_multiply`(const BigInt &k, RandomNumberGenerator &rng, std::vector<BigInt> &ws) const

    Return `base_point*k` in a way that attempts to resist side channels.

  BigInt `blinded_base_point_multiply_x`(const BigInt &k, RandomNumberGenerator &rng, std::vector<BigInt> &ws) const

    Like blinded_base_point_multiply but returns only the x coordinate.

  PointGFp `blinded_var_point_multiply`(const PointGFp &point, const BigInt &k, RandomNumberGenerator &rng, std::vector<BigInt> &ws) const

    Return `point*k` in a way that attempts to resist side channels.

  BigInt `random_scalar`(RandomNumberGenerator &rng) const

    Return a random scalar (ie an integer between 1 and the group order).

  PointGFp `zero_point`() const

    Return the zero point (aka the point at infinity).

  PointGFp `OS2ECP`(const uint8_t bits[], size_t len) const

    Decode a point from the binary encoding. This function verifies that the decoded point is a valid element on the curve.

  bool `verify_group`(RandomNumberGenerator &rng, bool strong = false) const

    Attempt to verify the group seems valid.

  static const std::set<std::string> &`known_named_groups`()

    Return a list of known groups, ie groups for which `EC_Group(name)` will succeed.

class `PointGFp`

  Stores elliptic curve points in Jacobian representation.

  std::vector<uint8_t> `encode`(PointGFp::Compression_Type format) const

    Encode a point in a way that can later be decoded with EC_Group::OS2ECP.

  PointGFp &`operator+=`(const PointGFp &rhs)

    Point addition.

  PointGFp &`operator-=`(const PointGFp &rhs)

    Point subtraction.

  PointGFp &`operator*=`(const BigInt &scalar)

    Point multiplication using Montgomery ladder.

    Warning

    Prefer the blinded functions in `EC_Group`

  PointGFp &`negate`()

    Negate this point.

  BigInt `get_affine_x`() const

    Return the affine `x` coordinate of the point.

  BigInt `get_affine_y`() const

    Return the affine `y` coordinate of the point.

  void `force_affine`()

    Convert the point to its equivalent affine coordinates. Throws if this is the point at infinity.

  static void `force_all_affine`(std::vector<PointGFp> &points, secure_vector<word> &ws)

    Force several points to be affine at once. Uses Montgomery’s trick to reduce number of inversions required, so this is much faster than calling `force_affine` on each point in sequence.

  bool `is_affine`() const

    Return true if this point is in affine coordinates.

  bool `is_zero`() const

    Return true if this point is zero (aka point at infinity).

  bool `on_the_curve`() const

    Return true if this point is on the curve.

  void `randomize_repr`(RandomNumberGenerator &rng)

    Randomize the point representation.

  bool `operator==`(const PointGFp &other) const

    Point equality. This compares the affine representations.

  void `add`(const PointGFp &other, std::vector<BigInt> &workspace)

    Point addition, taking a workspace.

  void `add_affine`(const PointGFp &other, std::vector<BigInt> &workspace)

    Mixed (Jacobian+affine) addition, taking a workspace.

    Warning

    This function assumes that `other` is affine, if this is not correct the result will be invalid.

  void `mult2`(std::vector<BigInt> &workspace)

    Point doubling.

  void `mult2i`(size_t i, std::vector<BigInt> &workspace)

    Repeated point doubling.

  PointGFp `plus`(const PointGFp &other, std::vector<BigInt> &workspace) const

    Point addition, returning the result.

  PointGFp `double_of`(std::vector<BigInt> &workspace) const

    Point doubling, returning the result.

  PointGFp `zero`() const

    Return the point at infinity