fastecdsa

fastecdsa.asn1

fastecdsa.asn1.decode_key(pemdata)

Decode an EC key as described in RFC 5915 and RFC 5480.

Args:
pemdata (bytes): A sequence of bytes representing an encoded EC key.
Returns:
(long, fastecdsa.point.Point): A private key, public key tuple. If the encoded key was a public key the first entry in the tuple is None.
fastecdsa.asn1.encode_keypair(d, Q)

Encode an EC keypair as described in RFC 5915.

Args:
d (long): An ECDSA private key.
Q (fastecdsa.point.Point): The ECDSA public key.
Returns:
str: The ASCII armored encoded EC keypair.
fastecdsa.asn1.encode_public_key(Q)

Encode an EC public key as described in RFC 5480.

Args:
Q (fastecdsa.point.Point): The ECDSA public key.
Returns:
str: The ASCII armored encoded EC public key.

fastecdsa.curve

class fastecdsa.curve.Curve(name, p, a, b, q, gx, gy, oid=None)

Bases: object

Representation of an elliptic curve.

Defines a group for the arithmetic operations of point addition and scalar multiplication. Currently only curves defined via the equation \(y^2 \equiv x^3 + ax + b \pmod{p}\) are supported.

Attributes:
name (string): The name of the curve
p (long): The value of \(p\) in the curve equation.
a (long): The value of \(a\) in the curve equation.
b (long): The value of \(b\) in the curve equation.
q (long): The order of the base point of the curve.
oid (long): The object identifier of the curve.
G

The base point of the curve.

For the purposes of ECDSA this point is multiplied by a private key to obtain the corresponding public key. Make a property to avoid cyclic dependency of Point on Curve (a point lies on a curve) and Curve on Point (curves have a base point).

__init__(name, p, a, b, q, gx, gy, oid=None)

Initialize the parameters of an elliptic curve.

WARNING: Do not generate your own parameters unless you know what you are doing or you could generate a curve severely less secure than you think. Even then, consider using a standardized curve for the sake of interoperability.

Currently only curves defined via the equation \(y^2 \equiv x^3 + ax + b \pmod{p}\) are supported.

Args:
name (string): The name of the curve
p (long): The value of \(p\) in the curve equation.
a (long): The value of \(a\) in the curve equation.
b (long): The value of \(b\) in the curve equation.
q (long): The order of the base point of the curve.
gx (long): The x coordinate of the base point of the curve.
gy (long): The y coordinate of the base point of the curve.
oid (str): The object identifier of the curve.
__repr__()

Return repr(self).

__weakref__

list of weak references to the object (if defined)

classmethod get_curve_by_oid(oid)

Get a curve via it’s object identifier.

is_point_on_curve(P)

Check if a point lies on this curve.

The check is done by evaluating the curve equation \(y^2 \equiv x^3 + ax + b \pmod{p}\) at the given point \((x,y)\) with this curve’s domain parameters \((a, b, p)\). If the congruence holds, then the point lies on this curve.

Args:
P (long, long): A tuple representing the point \(P\) as an \((x, y)\) coordinate pair.
Returns:
bool: True if the point lies on this curve, otherwise False.

fastecdsa.ecdsa

exception fastecdsa.ecdsa.EcdsaError(msg)

Bases: Exception

fastecdsa.ecdsa.sign(msg, d, curve=P256, hashfunc=<built-in function openssl_sha256>)

Sign a message using the elliptic curve digital signature algorithm.

The elliptic curve signature algorithm is described in full in FIPS 186-4 Section 6. Please refer to http://nvlpubs.nist.gov/nistpubs/FIPS/NIST.FIPS.186-4.pdf for more information.

Args:
msg (str): A message to be signed.
d (long): The ECDSA private key of the signer.
curve (fastecdsa.curve.Curve): The curve to be used to sign the message.
hashfunc (_hashlib.HASH): The hash function used to compress the message.
fastecdsa.ecdsa.verify(sig, msg, Q, curve=P256, hashfunc=<built-in function openssl_sha256>)

Verify a message signature using the elliptic curve digital signature algorithm.

The elliptic curve signature algorithm is described in full in FIPS 186-4 Section 6. Please refer to http://nvlpubs.nist.gov/nistpubs/FIPS/NIST.FIPS.186-4.pdf for more information.

Args:
sig (long, long): The signature for the message.
msg (str): A message to be signed.
Q (fastecdsa.point.Point): The ECDSA public key of the signer.
curve (fastecdsa.curve.Curve): The curve to be used to sign the message.
hashfunc (_hashlib.HASH): The hash function used to compress the message.
Returns:
bool: True if the signature is valid, False otherwise.
Raises:
fastecdsa.ecdsa.EcdsaError: If the signature or public key are invalid. Invalid signature
in this case means that it has values less than 1 or greater than the curve order.

fastecdsa.keys

fastecdsa.keys.export_key(key, curve=None, filepath=None)

Export a public or private EC key in PEM format.

Args:
key (fastecdsa.point.Point | long): A public or private EC key
curve (fastecdsa.curve.Curve): The curve corresponding to the key (required if the key is a private key)
filepath (str): Where to save the exported key. If None the key is simply printed.
fastecdsa.keys.gen_keypair(curve)

Generate a keypair that consists of a private key and a public key.

The private key \(d\) is an integer generated via a cryptographically secure random number generator that lies in the range \([1,n)\), where \(n\) is the curve order. The public key \(Q\) is a point on the curve calculated as \(Q = dG\), where \(G\) is the curve’s base point.

Args:
curve (fastecdsa.curve.Curve): The curve over which the keypair will be calulated.
Returns:
long, fastecdsa.point.Point: Returns a tuple with the private key first and public key second.
fastecdsa.keys.gen_private_key(curve)

Generate a private key to sign data with.

The private key \(d\) is an integer generated via a cryptographically secure random number generator that lies in the range \([1,n)\), where \(n\) is the curve order. The specific random number generator used is /dev/urandom.

Args:
curve (fastecdsa.curve.Curve): The curve over which the key will be calulated.
Returns:
long: Returns a positive integer smaller than the curve order.
fastecdsa.keys.get_public_key(d, curve)

Generate a public key from a private key.

The public key \(Q\) is a point on the curve calculated as \(Q = dG\), where \(d\) is the private key and \(G\) is the curve’s base point.

Args:
d (long): An integer representing the private key.
curve (fastecdsa.curve.Curve): The curve over which the key will be calulated.
Returns:
fastecdsa.point.Point: The public key, a point on the given curve.
fastecdsa.keys.get_public_keys_from_sig(sig, msg, curve=P256, hashfunc=<built-in function openssl_sha256>)

Recover the public keys that can verify a signature / message pair.

Args:
sig (long, long): A ECDSA signature.
msg (str): The message corresponding to the signature.
curve (fastecdsa.curve.Curve): The curve used to sign the message.
hashfunc (_hashlib.HASH): The hash function used to compress the message.
Returns:
(fastecdsa.point.Point, fastecdsa.point.Point): The public keys that can verify the
signature for the message.
fastecdsa.keys.import_key(filepath)

Import a public or private EC key in PEM format.

Args:
filepath (str): The location of the key file
Returns:
(long, fastecdsa.point.Point): A (private key, public key) tuple. If a public key was imported then the first value will be None.

fastecdsa.point

exception fastecdsa.point.CurveMismatchError(curve1, curve2)

Bases: Exception

__init__(curve1, curve2)

Initialize self. See help(type(self)) for accurate signature.

__weakref__

list of weak references to the object (if defined)

class fastecdsa.point.Point(x, y, curve=P256)

Bases: object

Representation of a point on an elliptic curve.

Attributes:
x (long): The x coordinate of the point.
y (long): The y coordinate of the point.
curve (Curve): The curve that the point lies on.
__add__(other)

Add two points on the same elliptic curve.

Args:
self (Point): a point \(P\) on the curve
other (Point): a point \(Q\) on the curve
Returns:
Point: A point \(R\) such that \(R = P + Q\)
__eq__(other)

Return self==value.

__init__(x, y, curve=P256)

Initialize a point on an elliptic curve.

The x and y parameters must satisfy the equation \(y^2 \equiv x^3 + ax + b \pmod{p}\), where a, b, and p are attributes of the curve parameter.

Args:
x (long): The x coordinate of the point.
y (long): The y coordinate of the point.
curve (Curve): The curve that the point lies on.
__mul__(scalar)

Multiply a Point on an elliptic curve by an integer.

Args:
self (Point): a point \(P\) on the curve
other (long): an integer \(d \in \mathbb{Z_q}\) where \(q\) is the order of the curve that \(P\) is on
Returns:
Point: A point \(R\) such that \(R = P * d\)
__neg__()

Return the negation of a Point i.e. the points reflection over the x-axis.

Args:
self (Point): a point \(P\) on the curve
Returns:
Point: A point \(R = (P_x, -P_y)\)
__radd__(other)

Add two points on the same elliptic curve.

Args:
self (Point): a point \(P\) on the curve
other (Point): a point \(Q\) on the curve
Returns:
Point: A point \(R\) such that \(R = P + Q\)
__repr__()

Return repr(self).

__rmul__(scalar)

Multiply a Point on an elliptic curve by an integer.

Args:
self (Point): a point \(P\) on the curve
other (long): an integer \(d \in \mathbb{Z_q}\) where \(q\) is the order of the curve that \(P\) is on
Returns:
Point: A point \(R\) such that \(R = d * P\)
__str__()

Return str(self).

__sub__(other)

Subtract two points on the same elliptic curve.

Args:
self (Point): a point \(P\) on the curve
other (Point): a point \(Q\) on the curve
Returns:
Point: A point \(R\) such that \(R = P - Q\)
__weakref__

list of weak references to the object (if defined)

fastecdsa.util

class fastecdsa.util.RFC6979(msg, x, q, hashfunc)

Bases: object

Generate a nonce per RFC6979.

In order to avoid reusing a nonce with the same key when signing two different messages (which leaks the private key) RFC6979 provides a deterministic method for generating nonces. This is based on using a pseudo-random function (HMAC) to derive a nonce from the message and private key. More info here: http://tools.ietf.org/html/rfc6979.

Attributes:
msg (string): A message being signed.
x (long): An ECDSA private key.
q (long): The order of the generator point of the curve being used to sign the message.
hashfunc (_hashlib.HASH): The hash function used to compress the message.
gen_nonce()

http://tools.ietf.org/html/rfc6979#section-3.2

fastecdsa.util.mod_sqrt(a, p)

Compute the square root of \(a \pmod{p}\)

In other words, find a value \(x\) such that \(x^2 \equiv a \pmod{p}\).

Args:
a (long): The value whose root to take.
p (long): The prime whose field to perform the square root in.
Returns:
(long, long): the two values of \(x\) satisfying \(x^2 \equiv a \pmod{p}\).