Metadata-Version: 2.4
Name: fastecdsa
Version: 3.0.1
Summary: Fast elliptic curve digital signatures
Author-email: Anton Kueltz <kueltz.anton@gmail.com>
License: This is free and unencumbered software released into the public domain.
        
        Anyone is free to copy, modify, publish, use, compile, sell, or
        distribute this software, either in source code form or as a compiled
        binary, for any purpose, commercial or non-commercial, and by any
        means.
        
        In jurisdictions that recognize copyright laws, the author or authors
        of this software dedicate any and all copyright interest in the
        software to the public domain. We make this dedication for the benefit
        of the public at large and to the detriment of our heirs and
        successors. We intend this dedication to be an overt act of
        relinquishment in perpetuity of all present and future rights to this
        software under copyright law.
        
        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
        EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
        MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
        IN NO EVENT SHALL THE AUTHORS BE LIABLE FOR ANY CLAIM, DAMAGES OR
        OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE,
        ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR
        OTHER DEALINGS IN THE SOFTWARE.
        
        For more information, please refer to <http://unlicense.org/>
        
Project-URL: repo, https://github.com/AntonKueltz/fastecdsa
Project-URL: docs, https://fastecdsa.readthedocs.io
Project-URL: pypi, https://pypi.org/project/fastecdsa/
Keywords: elliptic,curve,cryptography,ecdsa,ecc
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Topic :: Security :: Cryptography
Classifier: License :: CC0 1.0 Universal (CC0 1.0) Public Domain Dedication
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Operating System :: MacOS :: MacOS X
Classifier: Operating System :: POSIX :: Linux
Requires-Python: >=3.9
Description-Content-Type: text/x-rst
License-File: LICENSE
Dynamic: license-file

fastecdsa
=========
.. image:: https://img.shields.io/pypi/v/fastecdsa.svg
    :target: https://pypi.org/project/fastecdsa/
    :alt: PyPI

.. image:: https://readthedocs.org/projects/fastecdsa/badge/?version=stable
    :target: https://fastecdsa.readthedocs.io/en/stable/?badge=stable
    :alt: Documentation Status

.. contents::

About
-----
This is a python package for doing fast elliptic curve cryptography, specifically
digital signatures.

Security
--------
There is no nonce reuse, no branching on secret material,
and all points are validated before any operations are performed on them. Timing side challenges
are mitigated via Montgomery point multiplication. Nonces are generated per RFC6979_. The default
curve used throughout the package is P256 which provides 128 bits of security. If you require a
higher level of security you can specify the curve parameter in a method to use a curve over a
bigger field e.g. P384. All that being said, crypto is tricky and I'm not beyond making mistakes.
Please use a more established and reviewed library for security critical applications. Open an
issue or email me if you see any security issue or risk with this library.

Python Versions Supported
-------------------------
The initial release of this package was targeted at python2.7. Earlier versions may work but have
no guarantee of correctness or stability. As of release 1.2.1+ python3 is supported as well. Due to
python2's EOL on January 1st 2020 release 2.x of this package only supports python3.5+.

Operating Systems Supported
---------------------------
This package is targeted at the Linux and MacOS operating systems. Due to the the dependency on
the GMP C library building this package on Windows is difficult and no official support or
distributions are provided for Windows OSes. See issue11_ for what users have done to get things
building.

Supported Primitives
--------------------
Curves over Prime Fields
~~~~~~~~~~~~~~~~~~~~~~~~

+---------------------------+-----------------------------------------+-------------+
| Name                      | Class                                   | Proposed By |
+===========================+=========================================+=============+
| P192 / secp192r1          | :code:`fastecdsa.curve.P192`            | NIST / NSA  |
+---------------------------+-----------------------------------------+-------------+
| P224 / secp224r1          | :code:`fastecdsa.curve.P224`            | NIST / NSA  |
+---------------------------+-----------------------------------------+-------------+
| P256 / secp256r1          | :code:`fastecdsa.curve.P256`            | NIST / NSA  |
+---------------------------+-----------------------------------------+-------------+
| P384 / secp384r1          | :code:`fastecdsa.curve.P384`            | NIST / NSA  |
+---------------------------+-----------------------------------------+-------------+
| P521 / secp521r1          | :code:`fastecdsa.curve.P521`            | NIST / NSA  |
+---------------------------+-----------------------------------------+-------------+
| secp192k1                 | :code:`fastecdsa.curve.secp192k1`       | Certicom    |
+---------------------------+-----------------------------------------+-------------+
| secp224k1                 | :code:`fastecdsa.curve.secp224k1`       | Certicom    |
+---------------------------+-----------------------------------------+-------------+
| secp256k1 (bitcoin curve) | :code:`fastecdsa.curve.secp256k1`       | Certicom    |
+---------------------------+-----------------------------------------+-------------+
| brainpoolP160r1           | :code:`fastecdsa.curve.brainpoolP160r1` | BSI         |
+---------------------------+-----------------------------------------+-------------+
| brainpoolP192r1           | :code:`fastecdsa.curve.brainpoolP192r1` | BSI         |
+---------------------------+-----------------------------------------+-------------+
| brainpoolP224r1           | :code:`fastecdsa.curve.brainpoolP224r1` | BSI         |
+---------------------------+-----------------------------------------+-------------+
| brainpoolP256r1           | :code:`fastecdsa.curve.brainpoolP256r1` | BSI         |
+---------------------------+-----------------------------------------+-------------+
| brainpoolP320r1           | :code:`fastecdsa.curve.brainpoolP320r1` | BSI         |
+---------------------------+-----------------------------------------+-------------+
| brainpoolP384r1           | :code:`fastecdsa.curve.brainpoolP384r1` | BSI         |
+---------------------------+-----------------------------------------+-------------+
| brainpoolP512r1           | :code:`fastecdsa.curve.brainpoolP512r1` | BSI         |
+---------------------------+-----------------------------------------+-------------+

Arbitrary Curves
~~~~~~~~~~~~~~~~
As of version 1.5.1 construction of arbitrary curves in Weierstrass form
(:code:`y^2 = x^3 + ax + b (mod p)`) is supported. I advise against using custom curves for any
security critical applications. It's up to you to make sure that the parameters you pass here are
correct, no validation of the base point is done, and in general no sanity checks are done. Use
at your own risk.

.. code:: python

    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).
    )

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

Performance
-----------

Curves over Prime Fields
~~~~~~~~~~~~~~~~~~~~~~~~
Currently it does elliptic curve arithmetic significantly faster than the :code:`ecdsa`
package. You can see the times for 1,000 signature and verification operations over
various curves below. These were run on an early 2014 MacBook Air with a 1.4 GHz Intel
Core i5.

+-----------+------------------------+--------------------+---------+
| Curve     | :code:`fastecdsa` time | :code:`ecdsa` time | Speedup |
+-----------+------------------------+--------------------+---------+
| P192      | 3.62s                  | 1m35.49s           | ~26x    |
+-----------+------------------------+--------------------+---------+
| P224      | 4.50s                  | 2m13.42s           | ~29x    |
+-----------+------------------------+--------------------+---------+
| P256      | 6.15s                  | 2m52.43s           | ~28x    |
+-----------+------------------------+--------------------+---------+
| P384      | 12.11s                 | 6m21.01s           | ~31x    |
+-----------+------------------------+--------------------+---------+
| P521      | 22.21s                 | 11m39.53s          | ~31x    |
+-----------+------------------------+--------------------+---------+
| secp256k1 | 5.92s                  | 2m57.19s           | ~30x    |
+-----------+------------------------+--------------------+---------+

Installing
----------
You can use pip: :code:`$ pip install fastecdsa` or clone the repo and use
:code:`$ python setup.py install`. Note that you need to have a C compiler.
You  also need to have GMP_ on your system as the underlying
C code in this package includes the :code:`gmp.h` header (and links against gmp
via the :code:`-lgmp` flag). You can install all dependencies as follows:

apt
~~~

.. code:: bash

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

brew
~~~~

.. code:: bash

    $ brew install gmp

yum
~~~

.. code:: bash

    $ sudo yum install python-devel gmp-devel

Development
-----------
This package uses :code:`uv` for package management. You can install it via `pip install uv`. First build
the C extension modules

.. code:: bash

    $ uv run python setup.py build_ext --inplace

To run the test suite use the following command

.. code:: bash

    $ uv run pytest

Install pre-commit hooks to ensure type checking and autoformatting happens before you commit your code

.. code:: bash

    $ uv run pre-commit install

To build the docs use the following command, which will create a :code:`docs/_build` directory with the
docs built as HTML files

.. code:: bash

    $ cd docs
    $ uv run make html

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
:code:`pyproject.toml` for which python versions are supported)

.. code:: bash

   $ uv python install 3.9 3.10 3.11 3.12 3.13

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

.. code:: bash

    $ uv build --sdist
    $ uv build --wheel -p 3.x  # do this for each supported python version

Then publish the source and wheels distributions to the test PyPI account.

.. code:: bash

    $ uv publish --token {token} --url https://test.pypi.org/simple/

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

.. code:: bash

    $ uv run benchmark

This will use the :code:`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 via e.g. :code:`pip` you can use the following command:

.. code:: bash

    $ python -m fastecdsa.benchmark

Usage
-----
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.

.. code:: python

    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:

.. code:: python

    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 :code:`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 (:code:`+` and :code:`*` respectively):

.. code:: python

    # 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

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:

.. code:: python

    from fastecdsa.curve import P256
    from fastecdsa.keys import export_key, gen_keypair

    d, Q = gen_keypair(P256)
    # save the private key to disk
    export_key(d, curve=P256, filepath='/path/to/exported/p256.key')
    # save the public key to disk
    export_key(Q, curve=P256, 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:

.. code:: python

    from fastecdsa.keys import import_key

    # if the file is a private key then parsed_d is a long and parsed_Q is a Point object
    # if the file is a public key then parsed_d will be None
    parsed_d, parsed_Q = import_key('/path/to/file.key')

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

.. code:: python

    from fastecdsa.curve import P256
    from fastecdsa.encoding.sec1 import SEC1Encoder
    from fastecdsa.keys import export_key, gen_keypair, import_key

    _, Q = gen_keypair(P256)
    export_key(Q, curve=P256, filepath='/path/to/p256.key', encoder=SEC1Encoder)
    parsed_Q = import_key('/path/to/p256.key', curve=P256, public=True, decoder=SEC1Encoder)

Encoding Signatures
~~~~~~~~~~~~~~~~~~~
DER encoding of ECDSA signatures as defined in RFC2459_ is also supported. The
:code:`fastecdsa.encoding.der` provides the :code:`DEREncoder` class which encodes signatures:

.. code:: python

    from fastecdsa.encoding.der import DEREncoder

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

Acknowledgements
----------------
Thanks to those below for contributing improvements:

- boneyard93501
- clouds56
- m-kus
- sirk390
- targon
- NotStatilko
- bbbrumley
- luinxz
- JJChiDguez
- J08nY
- trevor-crypto
- sylvainpelissier
- akaIDIOT
- Peter-Bergman

.. _issue11: https://github.com/AntonKueltz/fastecdsa/issues/11
.. _GMP: https://gmplib.org/
.. _RFC2459: https://tools.ietf.org/html/rfc2459
.. _RFC5480: https://tools.ietf.org/html/rfc5480
.. _RFC5915: https://tools.ietf.org/html/rfc5915
.. _RFC6979: https://tools.ietf.org/html/rfc6979
.. _SEC1: http://www.secg.org/sec1-v2.pdf
