DOCSEARCHbyAlgolia
Submit Docs

fastecdsa

repository·main·Indexed 43 days ago

https://github.com/antonkueltz/fastecdsa

A high-performance Python package for elliptic curve digital signatures (ECDSA) optimized with the GMP C library. Version 3.1.0a2 provides tools for keypair generation, signing and verifying messages using deterministic nonce generation (RFC6979), and support for standardized curves including NIST, Brainpool, and secp256k1. It includes classes for Curve and Point arithmetic, as well as extensible KeyEncoder and SigEncoder for key and signature persistence.

Tokens
6.4K
Snippets
26
Records
32
Agent score
55%

What's inside fastecdsa

  1. Use custom hash functions

    main

    The library supports any hash function from the hashlib module (e.g., md5, sha1, sha224, sha256, sha384, sha512). It also works with any third-party hash function that implements the same interface as hashlib.

    For example, pysha3 is compatible as long as it is version $\ge$ 1.0b1.

  2. Implement a custom KeyEncoder

    main

    To implement a new encoder for elliptic curve keys, create a class that inherits from fastecdsa.encoding.KeyEncoder. You must implement all abstract methods defined in the base class.

    If your specific encoder implementation only supports a subset of key types (for example, if it only operates on public keys or only on private keys), you should raise NotImplementedError in the methods that are not applicable to your implementation. This ensures compatibility with high-level functions that interact with keys and signatures.

  5. Import and export keys (PEM and SEC1)

    main

    You can export and import keys using various encoding formats via the fastecdsa.keys and fastecdsa.encoding modules.

    PEM Encoding

    Use PEMEncoder to save keys to disk in formats compliant with RFC5480 and RFC5915.

    • export_private_key(d, curve, encoder, filepath): Saves a private key (integer d).
    • export_public_key(Q, encoder, filepath): Saves a public key (point Q).
    • import_private_key(filepath, decoder): Returns the private key as an integer.
    • import_public_key(filepath, curve, decoder): Returns the public key as a Point object.

    SEC1 Encoding

    For public keys, you can use SEC1Encoder from fastecdsa.encoding.sec1.

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

# Exporting
d, Q = gen_keypair(P256)
encoder = PEMEncoder()
export_private_key(d, curve=P256, encoder=encoder, filepath='/path/to/p256.key')
export_public_key(Q, encoder=encoder, filepath='/path/to/p256.pub')

# Importing
parsed_d = import_private_key('/path/to/p256.key', decoder=encoder)
parsed_Q = import_public_key('/path/to/p256.pub', curve=P256, decoder=encoder)

  6. Install fastecdsa

    main

    You can install fastecdsa using pip. Note that a C compiler and the GMP C library must be installed on your system because the package includes gmp.h and links against gmp via -lgmp.

    System Dependencies

    Ubuntu/Debian (apt):

    $ sudo apt-get install python3-dev libgmp3-dev

    macOS (brew):

    $ brew install gmp

    CentOS/RHEL (yum):

    $ sudo yum install python-devel gmp-devel
    $ pip install fastecdsa

  7. Install GMP dependencies for fastecdsa

    main

    Depending on your operating system, you must install the GMP library and necessary development headers to allow the C extensions to compile correctly.

    MacOS

    Use Homebrew to install gmp.

    Ubuntu / Debian

    Install gcc, python-dev, and libgmp3-dev.

    RHEL / CentOS

    Install gcc, python-devel, and gmp-devel.

    # MacOS
$ brew install gmp

# Ubuntu / Debian
$ sudo apt-get install gcc python-dev libgmp3-dev

# RHEL / CentOS
$ sudo yum install gcc python-devel gmp-devel

  8. Implement a custom SigEncoder

    main
    To implement a new encoder for elliptic curve signatures, create a class that inherits from fastecdsa.encoding.SigEncoder. You must implement all abstract methods defined in the base class to ensure the encoder works correctly with the library's high-level signature interaction functions.

  9. Benchmark fastecdsa performance

    main

    You can benchmark the performance of signature and verification operations on your local machine.

    If you have cloned the repository and are using uv:

    $ uv run benchmark

    If you have installed the package via pip:

    $ python -m fastecdsa.benchmark

    This will use the timeit module to benchmark 1,000 signature and verification operations for each supported curve.

    python -m fastecdsa.benchmark

  10. Perform arbitrary elliptic curve arithmetic with Point

    main

    The fastecdsa.point.Point class allows you to perform manual elliptic curve operations using standard Python operators:

    • Point Addition: S + T
    • Point Subtraction: S - T
    • Point Doubling: S + S or 2 * S
    • Scalar Multiplication: d * S or S * d
    • Joint Scalar Multiplication: d * S + e * T
    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
R = S - T

# Point Doubling
R = 2 * S

# Scalar Multiplication
d = 0xc51e4753afdec1e6b6c6a5b992f43f8dd0c7a8933072708b6522468b2ffb06fd
R = d * S

  11. Construct arbitrary Weierstrass curves

    main

    You can construct arbitrary curves in Weierstrass form ($y^2 = x^3 + ax + b \pmod{p}$) using the fastecdsa.curve.Curve class.

    Warning: Using custom curves is not recommended for security-critical applications. The library does not perform validation of the base point or other sanity checks on the parameters provided. Use at your own risk.

    from fastecdsa.curve import Curve
curve = Curve(
    name,  # (str): 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 (optional).
)

  12. Encode and decode ECDSA signatures (DER)

    main

    The fastecdsa.encoding.der module provides the DEREncoder class to handle DER encoding of ECDSA signatures as defined in RFC2459.

    • DEREncoder.encode_signature(r, s): Encodes the signature tuple (r, s) into DER format.
    • DEREncoder.decode_signature(encoded): Decodes a DER-encoded signature back into the (r, s) tuple.
    from fastecdsa.encoding.der import DEREncoder

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