coincurve 7.1.0

Cross-platform Python CFFI bindings for libsecp256k1

---

This library provides well-tested Python CFFI bindings for libsecp256k1, the heavily optimized C library used by Bitcoin Core for operations on elliptic curve secp256k1.

Coincurve replaces secp256k1-py.

New features include:

• Cleaner API
• Uses newest version of libsecp256k1
• Support for Windows
• Linux, macOS, and Windows all have binary packages for both 64 and 32-bit architectures
• Linux & macOS use GMP for faster computation
• A global context is used by default, drastically increasing performance
• Fixed ECDH
• A fix to remove CFFI warnings
• Implements a fix for https://bugs.python.org/issue28150 to support Python 3.6+ on macOS

Table of Contents

• Installation
• API
  • coincurve.verify_signature
  • coincurve.PrivateKey
  • coincurve.PublicKey
• License
• Credits
• Changelog
  • 7.1.0
  • 7.0.0
  • 6.0.0
  • 5.2.0
  • 5.1.0
  • 5.0.1
  • 5.0.0
  • 4.5.1

Installation

Coincurve is distributed on PyPI and is available on Linux/macOS and Windows and supports Python 2.7/3.5+ and PyPy3.5-v5.8.1+.

$ pip install coincurve

If you are on a system that doesn’t have a precompiled binary wheel (e.g. FreeBSD) then pip will fetch source to build yourself. You must have the necessary packages.

On Debian/Ubuntu for example the necessary packages are:

• build-essential
• automake
• pkg-config
• libtool
• libffi-dev
• libgmp-dev

API

Coincurve provides a simple API.

coincurve.verify_signature

verify_signature(signature, message, public_key, hasher=sha256, context=GLOBAL_CONTEXT)

Verifies some message was signed by the owner of a public key.

• Parameters:

  • signature (bytes) - The signature to verify.
  • message (bytes) - The message that was supposedly signed.
  • public_key (bytes) - A public key in compressed or uncompressed form.
  • hasher - The hash function to use, can be None. hasher(message) must return 32 bytes.
  • context (coincurve.Context)

• Returns: bool

coincurve.PrivateKey

All instances have a public_key of type coincurve.PublicKey

PrivateKey(secret=None, context=GLOBAL_CONTEXT)

• Parameters:

  • secret (bytes) - The secret to use.
  • context (coincurve.Context)

Methods:

classmethod from_hex(hexed, context=GLOBAL_CONTEXT)

classmethod from_int(num, context=GLOBAL_CONTEXT)

classmethod from_pem(pem, context=GLOBAL_CONTEXT)

classmethod from_der(der, context=GLOBAL_CONTEXT)

sign(message, hasher=sha256, custom_nonce=None)

• Parameters:

  • message (bytes) - The message to sign.
  • hasher - The hash function to use, can be None. hasher(message) must return 32 bytes.
  • custom_nonce - A tuple of arity 2 in the form of (nonce_fn, nonce_data). Refer to: secp256k1.h

• Returns: bytes. 68 <= len(signature) <= 71

sign_recoverable(message, hasher=sha256)

• Parameters:

  • message (bytes) - The message to sign.
  • hasher - The hash function to use, can be None. hasher(message) must return 32 bytes.

• Returns: bytes

ecdh(public_key)

Computes a Diffie-Hellman secret in constant time. Note: This prevents malleability by returning sha256(x) instead of the x coordinate directly. See https://github.com/ofek/coincurve/issues/9.

• Parameters:

  • public_key (bytes) - Another party’s public key in compressed or uncompressed form.

• Returns: bytes

add(scalar, update=False)

• Parameters:

  • scalar (bytes) - The scalar to add.
  • update (bool) - If True, will update and return self.

• Returns: coincurve.PrivateKey

multiply(scalar, update=False)

• Parameters:

  • scalar (bytes) - The scalar to multiply.
  • update (bool) - If True, will update and return self.

• Returns: coincurve.PrivateKey

to_hex()

to_int()

to_pem()

to_der()

coincurve.PublicKey

PublicKey(data, context=GLOBAL_CONTEXT)

• Parameters:

  • data (bytes) - The public key in compressed or uncompressed form.
  • context (coincurve.Context)

Methods:

classmethod from_secret(secret, context=GLOBAL_CONTEXT)

classmethod from_valid_secret(secret, context=GLOBAL_CONTEXT)

classmethod from_point(x, y, context=GLOBAL_CONTEXT)

classmethod from_signature_and_message(serialized_sig, message, hasher=sha256, context=GLOBAL_CONTEXT)

classmethod combine_keys(public_keys, context=GLOBAL_CONTEXT)

• Parameters:

  • public_keys (list) - A list of coincurve.PublicKey to add.
  • context (coincurve.Context)

• Returns: coincurve.PublicKey

format(compressed=True)

• Parameters:

  • compressed (bool)

• Returns: The public key serialized to bytes.

point()

• Returns: (x, y)

verify(signature, message, hasher=sha256)

Verifies some message was signed by the owner of this public key.

• Parameters:

  • signature (bytes) - The signature to verify.
  • message (bytes) - The message that was supposedly signed.
  • hasher - The hash function to use, can be None. hasher(message) must return 32 bytes.

• Returns: bool

add(scalar, update=False)

• Parameters:

  • scalar (bytes) - The scalar to add.
  • update (bool) - If True, will update and return self.

• Returns: coincurve.PublicKey

multiply(scalar, update=False)

• Parameters:

  • scalar (bytes) - The scalar to multiply.
  • update (bool) - If True, will update and return self.

• Returns: coincurve.PublicKey

combine(public_keys, update=False)

• Parameters:

  • public_keys (list) - A list of coincurve.PublicKey to add.
  • update (bool) - If True, will update and return self.

• Returns: coincurve.PublicKey

License

Coincurve is distributed under the terms of both

• Apache License, Version 2.0
• MIT License

at your option.

Credits

• Contributors of libsecp256k1.
• Contributors of secp256k1-py. While Coincurve is nearly a complete rewrite, much of the build system provided by ulope remains.

Changelog

Important changes are emphasized.

7.1.0

• Pin version of libsecp256k1
• Improve docs

7.0.0

• Improvements from libsecp256k1 master
• Fix build script

6.0.0

• Resolved #6. You can choose to use this or remain on 5.2.0. This will only be a temporary change. See https://github.com/ofek/coincurve/commit/3e93480b3e38c6b9beb0bc2de83bc3630fc74c46

5.2.0

• Added support for supplying a custom nonce to PrivateKey.sign.

5.1.0

• Added PublicKey.combine_keys class method.
• Improvements to documentation.

5.0.1

• Fixed an issue where validate_secret would occasionally erroneously error on user-provided secrets (secrets not generated by Coincurve itself) if there were not exactly 256 bits of entropy. See #5

5.0.0

• Breaking: Coincurve is now dual-licensed under the terms of MIT and Apache v2.0.
• Performance improvements from libsecp256k1 master: 1 2 3 4 5 6
• Improvements to documentation.

4.5.1

• First public stable release