{"id":22281051,"url":"https://github.com/antonkueltz/fastecdsa","last_synced_at":"2025-05-14T20:05:12.816Z","repository":{"id":40775681,"uuid":"54668669","full_name":"AntonKueltz/fastecdsa","owner":"AntonKueltz","description":"Python library for fast elliptic curve crypto","archived":false,"fork":false,"pushed_at":"2025-01-28T00:19:34.000Z","size":1555,"stargazers_count":272,"open_issues_count":5,"forks_count":76,"subscribers_count":12,"default_branch":"main","last_synced_at":"2025-04-03T03:08:24.534Z","etag":null,"topics":["cryptography","digital-signature","ecdsa","elliptic-curves","python"],"latest_commit_sha":null,"homepage":"https://pypi.python.org/pypi/fastecdsa","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"unlicense","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/AntonKueltz.png","metadata":{"files":{"readme":"README.rst","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2016-03-24T19:28:53.000Z","updated_at":"2025-03-04T19:31:13.000Z","dependencies_parsed_at":"2025-01-29T02:31:12.704Z","dependency_job_id":"12be30f4-bf65-4b1d-9a0a-29977bf0693f","html_url":"https://github.com/AntonKueltz/fastecdsa","commit_stats":{"total_commits":289,"total_committers":18,"mean_commits":"16.055555555555557","dds":0.2698961937716263,"last_synced_commit":"06b879e802047f98bc61fc9dd13e39fcd4614056"},"previous_names":[],"tags_count":41,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/AntonKueltz%2Ffastecdsa","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/AntonKueltz%2Ffastecdsa/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/AntonKueltz%2Ffastecdsa/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/AntonKueltz%2Ffastecdsa/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/AntonKueltz","download_url":"https://codeload.github.com/AntonKueltz/fastecdsa/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248161254,"owners_count":21057553,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["cryptography","digital-signature","ecdsa","elliptic-curves","python"],"created_at":"2024-12-03T16:13:09.545Z","updated_at":"2025-04-10T04:54:14.422Z","avatar_url":"https://github.com/AntonKueltz.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"fastecdsa\n=========\n.. image:: https://img.shields.io/pypi/v/fastecdsa.svg\n    :target: https://pypi.org/project/fastecdsa/\n    :alt: PyPI\n\n.. image:: https://readthedocs.org/projects/fastecdsa/badge/?version=stable\n    :target: https://fastecdsa.readthedocs.io/en/stable/?badge=stable\n    :alt: Documentation Status\n\n.. contents::\n\nAbout\n-----\nThis is a python package for doing fast elliptic curve cryptography, specifically\ndigital signatures.\n\nSecurity\n--------\nThere is no nonce reuse, no branching on secret material,\nand all points are validated before any operations are performed on them. Timing side challenges\nare mitigated via Montgomery point multiplication. Nonces are generated per RFC6979_. The default\ncurve used throughout the package is P256 which provides 128 bits of security. If you require a\nhigher level of security you can specify the curve parameter in a method to use a curve over a\nbigger field e.g. P384. All that being said, crypto is tricky and I'm not beyond making mistakes.\nPlease use a more established and reviewed library for security critical applications. Open an\nissue or email me if you see any security issue or risk with this library.\n\nPython Versions Supported\n-------------------------\nThe initial release of this package was targeted at python2.7. Earlier versions may work but have\nno guarantee of correctness or stability. As of release 1.2.1+ python3 is supported as well. Due to\npython2's EOL on January 1st 2020 release 2.x of this package only supports python3.5+.\n\nOperating Systems Supported\n---------------------------\nThis package is targeted at the Linux and MacOS operating systems. Due to the the dependency on\nthe GMP C library building this package on Windows is difficult and no official support or\ndistributions are provided for Windows OSes. See issue11_ for what users have done to get things\nbuilding.\n\nSupported Primitives\n--------------------\nCurves over Prime Fields\n~~~~~~~~~~~~~~~~~~~~~~~~\n\n+---------------------------+-----------------------------------------+-------------+\n| Name                      | Class                                   | Proposed By |\n+===========================+=========================================+=============+\n| P192 / secp192r1          | :code:`fastecdsa.curve.P192`            | NIST / NSA  |\n+---------------------------+-----------------------------------------+-------------+\n| P224 / secp224r1          | :code:`fastecdsa.curve.P224`            | NIST / NSA  |\n+---------------------------+-----------------------------------------+-------------+\n| P256 / secp256r1          | :code:`fastecdsa.curve.P256`            | NIST / NSA  |\n+---------------------------+-----------------------------------------+-------------+\n| P384 / secp384r1          | :code:`fastecdsa.curve.P384`            | NIST / NSA  |\n+---------------------------+-----------------------------------------+-------------+\n| P521 / secp521r1          | :code:`fastecdsa.curve.P521`            | NIST / NSA  |\n+---------------------------+-----------------------------------------+-------------+\n| secp192k1                 | :code:`fastecdsa.curve.secp192k1`       | Certicom    |\n+---------------------------+-----------------------------------------+-------------+\n| secp224k1                 | :code:`fastecdsa.curve.secp224k1`       | Certicom    |\n+---------------------------+-----------------------------------------+-------------+\n| secp256k1 (bitcoin curve) | :code:`fastecdsa.curve.secp256k1`       | Certicom    |\n+---------------------------+-----------------------------------------+-------------+\n| brainpoolP160r1           | :code:`fastecdsa.curve.brainpoolP160r1` | BSI         |\n+---------------------------+-----------------------------------------+-------------+\n| brainpoolP192r1           | :code:`fastecdsa.curve.brainpoolP192r1` | BSI         |\n+---------------------------+-----------------------------------------+-------------+\n| brainpoolP224r1           | :code:`fastecdsa.curve.brainpoolP224r1` | BSI         |\n+---------------------------+-----------------------------------------+-------------+\n| brainpoolP256r1           | :code:`fastecdsa.curve.brainpoolP256r1` | BSI         |\n+---------------------------+-----------------------------------------+-------------+\n| brainpoolP320r1           | :code:`fastecdsa.curve.brainpoolP320r1` | BSI         |\n+---------------------------+-----------------------------------------+-------------+\n| brainpoolP384r1           | :code:`fastecdsa.curve.brainpoolP384r1` | BSI         |\n+---------------------------+-----------------------------------------+-------------+\n| brainpoolP512r1           | :code:`fastecdsa.curve.brainpoolP512r1` | BSI         |\n+---------------------------+-----------------------------------------+-------------+\n\nArbitrary Curves\n~~~~~~~~~~~~~~~~\nAs of version 1.5.1 construction of arbitrary curves in Weierstrass form\n(:code:`y^2 = x^3 + ax + b (mod p)`) is supported. I advise against using custom curves for any\nsecurity critical applications. It's up to you to make sure that the parameters you pass here are\ncorrect, no validation of the base point is done, and in general no sanity checks are done. Use\nat your own risk.\n\n.. code:: python\n\n    from fastecdsa.curve import Curve\n    curve = Curve(\n        name,  # (str): The name of the curve\n        p,  # (long): The value of p in the curve equation.\n        a,  # (long): The value of a in the curve equation.\n        b,  # (long): The value of b in the curve equation.\n        q,  # (long): The order of the base point of the curve.\n        gx,  # (long): The x coordinate of the base point of the curve.\n        gy,  # (long): The y coordinate of the base point of the curve.\n        oid  # (str): The object identifier of the curve (optional).\n    )\n\nHash Functions\n~~~~~~~~~~~~~~\nAny hash function in the :code:`hashlib` module (:code:`md5, sha1, sha224, sha256, sha384, sha512`)\nwill work, as will any hash function that implements the same interface / core functionality as the\nthose in :code:`hashlib`. For instance, if you wish to use SHA3 as the hash function the\n:code:`pysha3` package will work with this library as long as it is at version \u003e=1.0b1 (as previous\nversions didn't work with the :code:`hmac` module which is used in nonce generation). Note\nthat :code:`sha3_224, sha3_256, sha3_384, sha3_512` are all in :code:`hashlib` as of python3.6.\n\nPerformance\n-----------\n\nCurves over Prime Fields\n~~~~~~~~~~~~~~~~~~~~~~~~\nCurrently it does elliptic curve arithmetic significantly faster than the :code:`ecdsa`\npackage. You can see the times for 1,000 signature and verification operations over\nvarious curves below. These were run on an early 2014 MacBook Air with a 1.4 GHz Intel\nCore i5.\n\n+-----------+------------------------+--------------------+---------+\n| Curve     | :code:`fastecdsa` time | :code:`ecdsa` time | Speedup |\n+-----------+------------------------+--------------------+---------+\n| P192      | 3.62s                  | 1m35.49s           | ~26x    |\n+-----------+------------------------+--------------------+---------+\n| P224      | 4.50s                  | 2m13.42s           | ~29x    |\n+-----------+------------------------+--------------------+---------+\n| P256      | 6.15s                  | 2m52.43s           | ~28x    |\n+-----------+------------------------+--------------------+---------+\n| P384      | 12.11s                 | 6m21.01s           | ~31x    |\n+-----------+------------------------+--------------------+---------+\n| P521      | 22.21s                 | 11m39.53s          | ~31x    |\n+-----------+------------------------+--------------------+---------+\n| secp256k1 | 5.92s                  | 2m57.19s           | ~30x    |\n+-----------+------------------------+--------------------+---------+\n\nInstalling\n----------\nYou can use pip: :code:`$ pip install fastecdsa` or clone the repo and use\n:code:`$ python setup.py install`. Note that you need to have a C compiler.\nYou  also need to have GMP_ on your system as the underlying\nC code in this package includes the :code:`gmp.h` header (and links against gmp\nvia the :code:`-lgmp` flag). You can install all dependencies as follows:\n\napt\n~~~\n\n.. code:: bash\n\n    $ sudo apt-get install python3-dev libgmp3-dev\n\nbrew\n~~~~\n\n.. code:: bash\n\n    $ brew install gmp\n\nyum\n~~~\n\n.. code:: bash\n\n    $ sudo yum install python-devel gmp-devel\n\nDevelopment\n-----------\nThis package uses :code:`uv` for package management. You can install it via `pip install uv`. First build\nthe C extension modules\n\n.. code:: bash\n\n    $ uv run python setup.py build_ext --inplace\n\nTo run the test suite use the following command\n\n.. code:: bash\n\n    $ uv run pytest\n\nInstall pre-commit hooks to ensure type checking and autoformatting happens before you commit your code\n\n.. code:: bash\n\n    $ uv run pre-commit install\n\nTo build the docs use the following command, which will create a :code:`docs/_build` directory with the\ndocs built as HTML files\n\n.. code:: bash\n\n    $ cd docs\n    $ uv run make html\n\nPublishing\n~~~~~~~~~~\nNote that currently only the package owner is able to publish releases to PyPI. The following steps\ncan still be used to generate source and wheel distributions, but note that the publish command will\nnot work.\n\nTo build a release first install all supported versions of python into the environment (double check\n:code:`pyproject.toml` for which python versions are supported)\n\n.. code:: bash\n\n   $ uv python install 3.9 3.10 3.11 3.12 3.13\n\nThen build a source distribution, followed by wheels for each supported python version\n\n.. code:: bash\n\n    $ uv build --sdist\n    $ uv build --wheel -p 3.x  # do this for each supported python version\n\nThen publish the source and wheels distributions to the test PyPI account.\n\n.. code:: bash\n\n    $ uv publish --token {token} --url https://test.pypi.org/simple/\n\nBenchmarking\n------------\nIf you'd like to benchmark performance on your machine you can do so using the command:\n\n.. code:: bash\n\n    $ uv run benchmark\n\nThis will use the :code:`timeit` module to benchmark 1000 signature and verification operations\nfor each curve supported by this package. Alternatively, if you have not cloned the repo but\nhave installed the package via e.g. :code:`pip` you can use the following command:\n\n.. code:: bash\n\n    $ python -m fastecdsa.benchmark\n\nUsage\n-----\nGenerating Keys\n~~~~~~~~~~~~~~~\nYou can use this package to generate keys if you like. Recall that private keys on elliptic curves\nare integers, and public keys are points i.e. integer pairs.\n\n.. code:: python\n\n    from fastecdsa import keys, curve\n\n    \"\"\"The reason there are two ways to generate a keypair is that generating the public key requires\n    a point multiplication, which can be expensive. That means sometimes you may want to delay\n    generating the public key until it is actually needed.\"\"\"\n\n    # generate a keypair (i.e. both keys) for curve P256\n    priv_key, pub_key = keys.gen_keypair(curve.P256)\n\n    # generate a private key for curve P256\n    priv_key = keys.gen_private_key(curve.P256)\n\n    # get the public key corresponding to the private key we just generated\n    pub_key = keys.get_public_key(priv_key, curve.P256)\n\n\nSigning and Verifying\n~~~~~~~~~~~~~~~~~~~~~\nSome basic usage is shown below:\n\n.. code:: python\n\n    from fastecdsa import curve, ecdsa, keys\n    from hashlib import sha384\n\n    m = \"a message to sign via ECDSA\"  # some message\n\n    ''' use default curve and hash function (P256 and SHA2) '''\n    private_key = keys.gen_private_key(curve.P256)\n    public_key = keys.get_public_key(private_key, curve.P256)\n    # standard signature, returns two integers\n    r, s = ecdsa.sign(m, private_key)\n    # should return True as the signature we just generated is valid.\n    valid = ecdsa.verify((r, s), m, public_key)\n\n    ''' specify a different hash function to use with ECDSA '''\n    r, s = ecdsa.sign(m, private_key, hashfunc=sha384)\n    valid = ecdsa.verify((r, s), m, public_key, hashfunc=sha384)\n\n    ''' specify a different curve to use with ECDSA '''\n    private_key = keys.gen_private_key(curve.P224)\n    public_key = keys.get_public_key(private_key, curve.P224)\n    r, s = ecdsa.sign(m, private_key, curve=curve.P224)\n    valid = ecdsa.verify((r, s), m, public_key, curve=curve.P224)\n\n    ''' using SHA3 via pysha3\u003e=1.0b1 package '''\n    import sha3  # pip install [--user] pysha3==1.0b1\n    from hashlib import sha3_256\n    private_key, public_key = keys.gen_keypair(curve.P256)\n    r, s = ecdsa.sign(m, private_key, hashfunc=sha3_256)\n    valid = ecdsa.verify((r, s), m, public_key, hashfunc=sha3_256)\n\nArbitrary Elliptic Curve Arithmetic\n~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~\nThe :code:`Point` class allows arbitrary arithmetic to be performed over curves. The two main\noperations are point addition and point multiplication (by a scalar) which can be done via the\nstandard python operators (:code:`+` and :code:`*` respectively):\n\n.. code:: python\n\n    # example taken from the document below (section 4.3.2):\n    # https://koclab.cs.ucsb.edu/teaching/cren/docs/w02/nist-routines.pdf\n\n    from fastecdsa.curve import P256\n    from fastecdsa.point import Point\n\n    xs = 0xde2444bebc8d36e682edd27e0f271508617519b3221a8fa0b77cab3989da97c9\n    ys = 0xc093ae7ff36e5380fc01a5aad1e66659702de80f53cec576b6350b243042a256\n    S = Point(xs, ys, curve=P256)\n\n    xt = 0x55a8b00f8da1d44e62f6b3b25316212e39540dc861c89575bb8cf92e35e0986b\n    yt = 0x5421c3209c2d6c704835d82ac4c3dd90f61a8a52598b9e7ab656e9d8c8b24316\n    T = Point(xt, yt, curve=P256)\n\n    # Point Addition\n    R = S + T\n\n    # Point Subtraction: (xs, ys) - (xt, yt) = (xs, ys) + (xt, -yt)\n    R = S - T\n\n    # Point Doubling\n    R = S + S  # produces the same value as the operation below\n    R = 2 * S  # S * 2 works fine too i.e. order doesn't matter\n\n    d = 0xc51e4753afdec1e6b6c6a5b992f43f8dd0c7a8933072708b6522468b2ffb06fd\n\n    # Scalar Multiplication\n    R = d * S  # S * d works fine too i.e. order doesn't matter\n\n    e = 0xd37f628ece72a462f0145cbefe3f0b355ee8332d37acdd83a358016aea029db7\n\n    # Joint Scalar Multiplication\n    R = d * S + e * T\n\nImporting and Exporting Keys\n~~~~~~~~~~~~~~~~~~~~~~~~~~~~\nYou can also export keys as files, ASN.1 encoded and formatted per RFC5480_ and RFC5915_. Both\nprivate keys and public keys can be exported as follows:\n\n.. code:: python\n\n    from fastecdsa.curve import P256\n    from fastecdsa.keys import export_key, gen_keypair\n\n    d, Q = gen_keypair(P256)\n    # save the private key to disk\n    export_key(d, curve=P256, filepath='/path/to/exported/p256.key')\n    # save the public key to disk\n    export_key(Q, curve=P256, filepath='/path/to/exported/p256.pub')\n\nKeys stored in this format can also be imported. The import function will figure out if the key\nis a public or private key and parse it accordingly:\n\n.. code:: python\n\n    from fastecdsa.keys import import_key\n\n    # if the file is a private key then parsed_d is a long and parsed_Q is a Point object\n    # if the file is a public key then parsed_d will be None\n    parsed_d, parsed_Q = import_key('/path/to/file.key')\n\nOther encoding formats can also be specified, such as SEC1_ for public keys. This is done using\nclasses found in the :code:`fastecdsa.encoding` package, and passing them as keyword args to\nthe key functions:\n\n.. code:: python\n\n    from fastecdsa.curve import P256\n    from fastecdsa.encoding.sec1 import SEC1Encoder\n    from fastecdsa.keys import export_key, gen_keypair, import_key\n\n    _, Q = gen_keypair(P256)\n    export_key(Q, curve=P256, filepath='/path/to/p256.key', encoder=SEC1Encoder)\n    parsed_Q = import_key('/path/to/p256.key', curve=P256, public=True, decoder=SEC1Encoder)\n\nEncoding Signatures\n~~~~~~~~~~~~~~~~~~~\nDER encoding of ECDSA signatures as defined in RFC2459_ is also supported. The\n:code:`fastecdsa.encoding.der` provides the :code:`DEREncoder` class which encodes signatures:\n\n.. code:: python\n\n    from fastecdsa.encoding.der import DEREncoder\n\n    r, s = 0xdeadc0de, 0xbadc0de\n    encoded = DEREncoder.encode_signature(r, s)\n    decoded_r, decoded_s = DEREncoder.decode_signature(encoded)\n\nAcknowledgements\n----------------\nThanks to those below for contributing improvements:\n\n- boneyard93501\n- clouds56\n- m-kus\n- sirk390\n- targon\n- NotStatilko\n- bbbrumley\n- luinxz\n- JJChiDguez\n- J08nY\n- trevor-crypto\n- sylvainpelissier\n- akaIDIOT\n- Peter-Bergman\n\n.. _issue11: https://github.com/AntonKueltz/fastecdsa/issues/11\n.. _GMP: https://gmplib.org/\n.. _RFC2459: https://tools.ietf.org/html/rfc2459\n.. _RFC5480: https://tools.ietf.org/html/rfc5480\n.. _RFC5915: https://tools.ietf.org/html/rfc5915\n.. _RFC6979: https://tools.ietf.org/html/rfc6979\n.. _SEC1: http://www.secg.org/sec1-v2.pdf\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fantonkueltz%2Ffastecdsa","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fantonkueltz%2Ffastecdsa","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fantonkueltz%2Ffastecdsa/lists"}