ECDSA

EdDSA

Arbitrary Weierstrass Curves

As of version 1.5.1 construction of arbitrary curves in Weierstrass form (y^2 = x^3 + ax + b (mod p)) is supported. I advise against using custom curves for any security sensitive applications. In versions before release 4.0.0 no checks on the curve parameters are done. In 4.0.0+ some sanity checks are applied -

• p must be a non-even (not 2) prime

• The curve cannot be singular (discriminant equal to 0)

• (gx, gy) must be a point on the curve

• q must be prime

Exhaustive validation checks are not performed e.g., no check that q is actually the order of point (gx, gy) is performed.

from fastecdsa.curve import Curve
curve = Curve(
    name,  # (str): The name of the curve
    p,     # (int): The value of p in the curve equation.
    a,     # (int): The value of a in the curve equation.
    b,     # (int): The value of b in the curve equation.
    q,     # (int): The order of the base point of the curve.
    gx,    # (int): The x coordinate of the base point of the curve.
    gy,    # (int): The y coordinate of the base point of the curve.
)

Hash Functions

Any hash function in the hashlib module (md5, sha1, sha224, sha256, sha384, sha512) will work, as will any hash function that implements the same interface / core functionality as the those in hashlib. For instance, if you wish to use SHA3 as the hash function the pysha3 package will work with this library as long as it is at version >=1.0b1 (as previous versions didn’t work with the hmac module which is used in nonce generation). Note that sha3_224, sha3_256, sha3_384, sha3_512 are all in hashlib as of python3.6.

ECDSA

EdDSA

If you’d like to benchmark performance on your machine you can do so using the command:

$ uv run benchmark

This will use the timeit module to benchmark 1000 signature and verification operations for each curve supported by this package. Alternatively, if you have not cloned the repo but have installed the package to your site packages you can use the following command:

$ python -m fastecdsa.benchmark

Publishing

Note that currently only the package owner is able to publish releases to PyPI. The following steps can still be used to generate source and wheel distributions, but note that the publish command will not work.

To build a release first install all supported versions of python into the environment (double check pyproject.toml for which python versions are supported)

$ uv python install 3.11 3.12 3.13 3.14

Then build a source distribution, followed by wheels for each supported python version

$ uv run maturin sdist
$ uv run maturin build -r -i python3.x

Generating Keys

You can use this package to generate keys if you like. Recall that private keys on elliptic curves are integers, and public keys are points i.e. integer pairs.

from fastecdsa import keys, curve

"""The reason there are two ways to generate a keypair is that generating the public key requires
a point multiplication, which can be expensive. That means sometimes you may want to delay
generating the public key until it is actually needed."""

# generate a keypair (i.e. both keys) for curve P256
priv_key, pub_key = keys.gen_keypair(curve.P256)

# generate a private key for curve P256
priv_key = keys.gen_private_key(curve.P256)

# get the public key corresponding to the private key we just generated
pub_key = keys.get_public_key(priv_key, curve.P256)

Signing and Verifying

Some basic usage is shown below:

from fastecdsa import curve, ecdsa, keys
from hashlib import sha384

m = "a message to sign via ECDSA"  # some message

''' use default curve and hash function (P256 and SHA2) '''
private_key = keys.gen_private_key(curve.P256)
public_key = keys.get_public_key(private_key, curve.P256)
# standard signature, returns two integers
r, s = ecdsa.sign(m, private_key)
# should return True as the signature we just generated is valid.
valid = ecdsa.verify((r, s), m, public_key)

''' specify a different hash function to use with ECDSA '''
r, s = ecdsa.sign(m, private_key, hashfunc=sha384)
valid = ecdsa.verify((r, s), m, public_key, hashfunc=sha384)

''' specify a different curve to use with ECDSA '''
private_key = keys.gen_private_key(curve.P224)
public_key = keys.get_public_key(private_key, curve.P224)
r, s = ecdsa.sign(m, private_key, curve=curve.P224)
valid = ecdsa.verify((r, s), m, public_key, curve=curve.P224)

''' using SHA3 via pysha3>=1.0b1 package '''
import sha3  # pip install [--user] pysha3==1.0b1
from hashlib import sha3_256
private_key, public_key = keys.gen_keypair(curve.P256)
r, s = ecdsa.sign(m, private_key, hashfunc=sha3_256)
valid = ecdsa.verify((r, s), m, public_key, hashfunc=sha3_256)

Arbitrary Elliptic Curve Arithmetic

The Point class allows arbitrary arithmetic to be performed over curves. The two main operations are point addition and point multiplication (by a scalar) which can be done via the standard python operators (+ and * respectively):

# example taken from the document below (section 4.3.2):
# https://koclab.cs.ucsb.edu/teaching/cren/docs/w02/nist-routines.pdf

from fastecdsa.curve import P256
from fastecdsa.point import Point

xs = 0xde2444bebc8d36e682edd27e0f271508617519b3221a8fa0b77cab3989da97c9
ys = 0xc093ae7ff36e5380fc01a5aad1e66659702de80f53cec576b6350b243042a256
S = Point(xs, ys, curve=P256)

xt = 0x55a8b00f8da1d44e62f6b3b25316212e39540dc861c89575bb8cf92e35e0986b
yt = 0x5421c3209c2d6c704835d82ac4c3dd90f61a8a52598b9e7ab656e9d8c8b24316
T = Point(xt, yt, curve=P256)

# Point Addition
R = S + T

# Point Subtraction: (xs, ys) - (xt, yt) = (xs, ys) + (xt, -yt)
R = S - T

# Point Doubling
R = S + S  # produces the same value as the operation below
R = 2 * S  # S * 2 works fine too i.e. order doesn't matter

d = 0xc51e4753afdec1e6b6c6a5b992f43f8dd0c7a8933072708b6522468b2ffb06fd

# Scalar Multiplication
R = d * S  # S * d works fine too i.e. order doesn't matter

e = 0xd37f628ece72a462f0145cbefe3f0b355ee8332d37acdd83a358016aea029db7

# Joint Scalar Multiplication
R = d * S + e * T

In [1]: from fastecdsa.eddsa import Ed25519Point as e25519

In [2]: G = e25519.g()

In [3]: G
Out[3]:
X: 0x216936d3cd6e53fec0a4e231fdd6dc5c692cc7609525a7b2c9562d608f25d51a
Y: 0x6666666666666666666666666666666666666666666666666666666666666658
(Affine point on curve Edwards25519)

In [4]: G * 2
Out[4]:
X: 0x36ab384c9f5a046c3d043b7d1833e7ac080d8e4515d7a45f83c5a14e2843ce0e
Y: 0x2260cdf3092329c21da25ee8c9a21f5697390f51643851560e5f46ae6af8a3c9
(Affine point on curve Edwards25519)

In [5]: G + G
Out[5]:
X: 0x36ab384c9f5a046c3d043b7d1833e7ac080d8e4515d7a45f83c5a14e2843ce0e
Y: 0x2260cdf3092329c21da25ee8c9a21f5697390f51643851560e5f46ae6af8a3c9
(Affine point on curve Edwards25519)

In [6]: e25519.scale_base(2)
Out[6]:
X: 0x5881d418cc897a3a0eb49cdb9e6859fe2c55894bcdf7f8095714be2d5cf2e79a
Y: 0x27e006a46c706615d5ef0e2ff33fb48a6fbc113c77c0bd916574e8d0e2c42106
Z: 0x1f7616052c96e0810d7ff513e392dfbad03e66e0a95c8d2796a29516b07725f4
T: 0x5dec8aec83e2c5266dd025b8da706eed6a2729713b3f035372c8624d35caa7b
(Extended projective point on curve Edwards25519)

In [7]: _.normalize()
Out[7]:
X: 0x36ab384c9f5a046c3d043b7d1833e7ac080d8e4515d7a45f83c5a14e2843ce0e
Y: 0x2260cdf3092329c21da25ee8c9a21f5697390f51643851560e5f46ae6af8a3c9
(Affine point on curve Edwards25519

Projective Points

As of release 4.0.0 you can also use the projective representation of points. This may be desirable if you are doing a lot of intermediate calculations with points before you need an affine representation as arithmetic on projective points is cheaper. Note that comparisons between projective points and affine points are also possible, but they are less performant than comparisons between two affine points. By default all representations and operations on points are affine. To convert a projective point back to an affine point use the normalize method.

In [1]: from fastecdsa.curve import P256

In [2]: from fastecdsa.point import Point

In [3]: x = 0xdeadc0de

In [4]: x * P256.G
Out[4]:
X: 0x32079326d26449f8b36bde4410f805eb520c0120da1585c79c369f356c8a298f
Y: 0x249daa2c57c8d6a90575630635aa5448fa56d21f5e363c155fe98c597b1c70ae
(Affine point on curve "P256")

In [5]: g_ = Point(P256.G.x, P256.G.y, P256, projective=True)

In [6]: h = x * g_

In [7]: h
Out[7]:
X: 0x15819ed127c46b11b751a1d575a6e7712fe72c03e693ea0783268e2f0d4bdfac
Y: 0x879367bd0ebcf1b97fdb0841c33333f7c321a41c2ced6ab14a1cd2cc7684f6bf
Z: 0x99682c948ddc2ddd15966aecfe83fe52b1df7d76255d460f90d7bd615bb80cfc
(Projective point on curve "P256")

In [8]: h.normalize()  # gives the same result as x * P256.G
Out[8]:
X: 0x32079326d26449f8b36bde4410f805eb520c0120da1585c79c369f356c8a298f
Y: 0x249daa2c57c8d6a90575630635aa5448fa56d21f5e363c155fe98c597b1c70ae
(Affine point on curve "P256")

Importing and Exporting Keys

You can also export keys as files, ASN.1 encoded and formatted per RFC5480 and RFC5915. Both private keys and public keys can be exported as follows:

from fastecdsa.curve import P256
from fastecdsa.encoding.pem import PEMEncoder
from fastecdsa.keys import export_private_key, export_public_key, gen_keypair

d, Q = gen_keypair(P256)
encoder = PEMEncoder()

# save the private key to disk
export_private_key(d, curve=P256, encoder=encoder, filepath='/path/to/exported/p256.key')
# save the public key to disk (curve inferred from Q)
export_public_key(Q, encoder=encoder, filepath='/path/to/exported/p256.pub')

Keys stored in this format can also be imported. The import function will figure out if the key is a public or private key and parse it accordingly:

from fastecdsa.curve import P256
from fastecdsa.encoding.pem import PEMEncoder
from fastecdsa.keys import import_public_key, import_private_key

decoder = PEMEncoder()
# returns an int
parsed_d = import_private_key('/path/to/exported/p256.key', decoder=decoder)
# returns a fastecdsa.point.Point
parsed_Q = import_public_key('/path/to/exported/p256.pub', curve=P256, decoder=decoder)

Other encoding formats can also be specified, such as SEC1 for public keys. This is done using classes found in the fastecdsa.encoding package, and passing them as keyword args to the key functions:

from fastecdsa.curve import P256
from fastecdsa.encoding.sec1 import SEC1Encoder
from fastecdsa.keys import export_public_key, gen_keypair, import_public_key

_, Q = gen_keypair(P256)
encoder = SEC1Encoder()

export_public_key(Q, encoder=encoder, filepath='/path/to/exported/p256.pub')
parsed_Q = import_public_key('/path/to/exported/p256.pub', curve=P256, decoder=encoder)

Encoding Signatures

DER encoding of ECDSA signatures as defined in RFC2459 is also supported. The fastecdsa.encoding.der provides the DEREncoder class which encodes signatures:

from fastecdsa.encoding.der import DEREncoder

r, s = 0xdeadc0de, 0xbadc0de
encoded = DEREncoder.encode_signature(r, s)
decoded_r, decoded_s = DEREncoder.decode_signature(encoded)