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.
-
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
andy
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
andy
. Note this function does not verify thatx
andy
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
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 BigInt &scalar)¶ Point multiplication using Montgomery ladder.
Warning
Prefer the blinded functions in
EC_Group
-
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.
-
std::vector<uint8_t>