285 lines
9.2 KiB
ReStructuredText
285 lines
9.2 KiB
ReStructuredText
|
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.
|
||
|
|
|
||
|
|
.. cpp:class:: EC_Group
|
||
|
|
|
||
|
|
.. cpp:function:: EC_Group(const OID& oid)
|
||
|
|
|
||
|
|
Initialize an ``EC_Group`` using an OID referencing the curve
|
||
|
|
parameters.
|
||
|
|
|
||
|
|
.. cpp:function:: 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")
|
||
|
|
|
||
|
|
.. 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())
|
||
|
|
|
||
|
|
Initialize an elliptic curve group from the relevant parameters. This
|
||
|
|
is used for example to create custom (application-specific) curves.
|
||
|
|
|
||
|
|
.. cpp:function:: EC_Group(const std::vector<uint8_t>& ber_encoding)
|
||
|
|
|
||
|
|
Initialize an ``EC_Group`` by decoding a DER encoded parameter block.
|
||
|
|
|
||
|
|
.. cpp:function:: std::vector<uint8_t> DER_encode(EC_Group_Encoding form) const
|
||
|
|
|
||
|
|
Return the DER encoding of this group.
|
||
|
|
|
||
|
|
.. cpp:function:: std::string PEM_encode() const
|
||
|
|
|
||
|
|
Return the PEM encoding of this group (base64 of DER encoding plus
|
||
|
|
header/trailer).
|
||
|
|
|
||
|
|
.. cpp:function:: bool a_is_minus_3() const
|
||
|
|
|
||
|
|
Return true if the ``a`` parameter is congruent to -3 mod p.
|
||
|
|
|
||
|
|
.. cpp:function:: bool a_is_zero() const
|
||
|
|
|
||
|
|
Return true if the ``a`` parameter is congruent to 0 mod p.
|
||
|
|
|
||
|
|
.. cpp:function:: size_t get_p_bits() const
|
||
|
|
|
||
|
|
Return size of the prime in bits.
|
||
|
|
|
||
|
|
.. cpp:function:: size_t get_p_bytes() const
|
||
|
|
|
||
|
|
Return size of the prime in bytes.
|
||
|
|
|
||
|
|
.. cpp:function:: size_t get_order_bits() const
|
||
|
|
|
||
|
|
Return size of the group order in bits.
|
||
|
|
|
||
|
|
.. cpp:function:: size_t get_order_bytes() const
|
||
|
|
|
||
|
|
Return size of the group order in bytes.
|
||
|
|
|
||
|
|
.. cpp:function:: const BigInt& get_p() const
|
||
|
|
|
||
|
|
Return the prime modulus.
|
||
|
|
|
||
|
|
.. cpp:function:: const BigInt& get_a() const
|
||
|
|
|
||
|
|
Return the ``a`` parameter of the elliptic curve equation.
|
||
|
|
|
||
|
|
.. cpp:function:: const BigInt& get_b() const
|
||
|
|
|
||
|
|
Return the ``b`` parameter of the elliptic curve equation.
|
||
|
|
|
||
|
|
.. cpp:function:: const EC_Point& get_base_point() const
|
||
|
|
|
||
|
|
Return the groups base point element.
|
||
|
|
|
||
|
|
.. cpp:function:: const BigInt& get_g_x() const
|
||
|
|
|
||
|
|
Return the x coordinate of the base point element.
|
||
|
|
|
||
|
|
.. cpp:function:: const BigInt& get_g_y() const
|
||
|
|
|
||
|
|
Return the y coordinate of the base point element.
|
||
|
|
|
||
|
|
.. cpp:function:: const BigInt& get_order() const
|
||
|
|
|
||
|
|
Return the order of the group generated by the base point.
|
||
|
|
|
||
|
|
.. cpp:function:: const BigInt& get_cofactor() const
|
||
|
|
|
||
|
|
Return the cofactor of the curve. In most cases this will be 1.
|
||
|
|
|
||
|
|
.. cpp:function:: BigInt mod_order(const BigInt& x) const
|
||
|
|
|
||
|
|
Reduce argument ``x`` modulo the curve order.
|
||
|
|
|
||
|
|
.. cpp:function:: BigInt inverse_mod_order(const BigInt& x) const
|
||
|
|
|
||
|
|
Return inverse of argument ``x`` modulo the curve order.
|
||
|
|
|
||
|
|
.. cpp:function:: BigInt multiply_mod_order(const BigInt& x, const BigInt& y) const
|
||
|
|
|
||
|
|
Multiply ``x`` and ``y`` and reduce the result modulo the curve order.
|
||
|
|
|
||
|
|
.. cpp:function:: bool verify_public_element(const EC_Point& y) const
|
||
|
|
|
||
|
|
Return true if ``y`` seems to be a valid group element.
|
||
|
|
|
||
|
|
.. cpp:function:: const OID& get_curve_oid() const
|
||
|
|
|
||
|
|
Return the OID used to identify the curve. May be empty.
|
||
|
|
|
||
|
|
.. cpp:function:: EC_Point 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.
|
||
|
|
|
||
|
|
.. cpp:function:: EC_Point point_multiply(const BigInt& x, const EC_Point& pt, const BigInt& y) const
|
||
|
|
|
||
|
|
Multi-exponentiation. Returns base_point*x + pt*y. Not constant time.
|
||
|
|
(Ordinarily used for signature verification.)
|
||
|
|
|
||
|
|
.. cpp:function:: EC_Point 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.
|
||
|
|
|
||
|
|
.. cpp:function:: 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.
|
||
|
|
|
||
|
|
.. cpp:function:: EC_Point blinded_var_point_multiply(const EC_Point& point, \
|
||
|
|
const BigInt& k, \
|
||
|
|
RandomNumberGenerator& rng, \
|
||
|
|
std::vector<BigInt>& ws) const
|
||
|
|
|
||
|
|
Return ``point*k`` in a way that attempts to resist side channels.
|
||
|
|
|
||
|
|
.. cpp:function:: BigInt random_scalar(RandomNumberGenerator& rng) const
|
||
|
|
|
||
|
|
Return a random scalar (ie an integer between 1 and the group order).
|
||
|
|
|
||
|
|
.. cpp:function:: EC_Point zero_point() const
|
||
|
|
|
||
|
|
Return the zero point (aka the point at infinity).
|
||
|
|
|
||
|
|
.. cpp:function:: EC_Point 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.
|
||
|
|
|
||
|
|
.. 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(name)``
|
||
|
|
will succeed.
|
||
|
|
|
||
|
|
.. cpp:class:: EC_Point
|
||
|
|
|
||
|
|
Stores elliptic curve points in Jacobian representation.
|
||
|
|
|
||
|
|
.. cpp:function:: std::vector<uint8_t> encode(EC_Point::Compression_Type format) const
|
||
|
|
|
||
|
|
Encode a point in a way that can later be decoded with `EC_Group::OS2ECP`.
|
||
|
|
|
||
|
|
.. cpp:function:: EC_Point& operator+=(const EC_Point& rhs)
|
||
|
|
|
||
|
|
Point addition.
|
||
|
|
|
||
|
|
.. cpp:function:: EC_Point& operator-=(const EC_Point& rhs)
|
||
|
|
|
||
|
|
Point subtraction.
|
||
|
|
|
||
|
|
.. cpp:function:: EC_Point& operator*=(const BigInt& scalar)
|
||
|
|
|
||
|
|
Point multiplication using Montgomery ladder.
|
||
|
|
|
||
|
|
.. warning::
|
||
|
|
Prefer the blinded functions in ``EC_Group``
|
||
|
|
|
||
|
|
.. cpp:function:: EC_Point& negate()
|
||
|
|
|
||
|
|
Negate this point.
|
||
|
|
|
||
|
|
.. cpp:function:: BigInt get_affine_x() const
|
||
|
|
|
||
|
|
Return the affine ``x`` coordinate of the point.
|
||
|
|
|
||
|
|
.. cpp:function:: BigInt get_affine_y() const
|
||
|
|
|
||
|
|
Return the affine ``y`` coordinate of the point.
|
||
|
|
|
||
|
|
.. cpp:function:: void force_affine()
|
||
|
|
|
||
|
|
Convert the point to its equivalent affine coordinates. Throws
|
||
|
|
if this is the point at infinity.
|
||
|
|
|
||
|
|
.. cpp:function:: static void force_all_affine(std::vector<EC_Point>& 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.
|
||
|
|
|
||
|
|
.. cpp:function:: bool is_affine() const
|
||
|
|
|
||
|
|
Return true if this point is in affine coordinates.
|
||
|
|
|
||
|
|
.. cpp:function:: bool is_zero() const
|
||
|
|
|
||
|
|
Return true if this point is zero (aka point at infinity).
|
||
|
|
|
||
|
|
.. cpp:function:: bool on_the_curve() const
|
||
|
|
|
||
|
|
Return true if this point is on the curve.
|
||
|
|
|
||
|
|
.. cpp:function:: void randomize_repr(RandomNumberGenerator& rng)
|
||
|
|
|
||
|
|
Randomize the point representation.
|
||
|
|
|
||
|
|
.. cpp:function:: bool operator==(const EC_Point& other) const
|
||
|
|
|
||
|
|
Point equality. This compares the affine representations.
|
||
|
|
|
||
|
|
.. cpp:function:: void add(const EC_Point& other, std::vector<BigInt>& workspace)
|
||
|
|
|
||
|
|
Point addition, taking a workspace.
|
||
|
|
|
||
|
|
.. cpp:function:: void add_affine(const EC_Point& 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.
|
||
|
|
|
||
|
|
.. cpp:function:: void mult2(std::vector<BigInt>& workspace)
|
||
|
|
|
||
|
|
Point doubling.
|
||
|
|
|
||
|
|
.. cpp:function:: void mult2i(size_t i, std::vector<BigInt>& workspace)
|
||
|
|
|
||
|
|
Repeated point doubling.
|
||
|
|
|
||
|
|
.. cpp:function:: EC_Point plus(const EC_Point& other, std::vector<BigInt>& workspace) const
|
||
|
|
|
||
|
|
Point addition, returning the result.
|
||
|
|
|
||
|
|
.. cpp:function:: EC_Point double_of(std::vector<BigInt>& workspace) const
|
||
|
|
|
||
|
|
Point doubling, returning the result.
|
||
|
|
|
||
|
|
.. cpp:function:: EC_Point zero() const
|
||
|
|
|
||
|
|
Return the point at infinity
|
||
|
|
|
||
|
|
|
||
|
|
|