# ECDSA¶

## `Curve` Module¶

class `pycoin.ecdsa.Curve.``Curve`(p, a, b, order=None)[source]

This class implements an Elliptic curve intended for use in Elliptic curve cryptography

An elliptic curve `EC<p, a, b>` for a (usually large) prime p and integers a and b is a group. The members of the group are (x, y) points (where x and y are integers over the field of integers modulo p) that satisfy the relation `y**2 = x**3 + a*x + b (mod p)`. There is a group operation `+` and an extra point known as the “point at infinity” thrown in to act as the identity for the group.

The group operation is a truly marvelous property of this construct, a description of which this margin is too narrow to contain, so please refer to the links above for more information.

Parameters: p – a prime a – an integer coefficient b – an integer constant order – (optional) the order of the group made up by the points on the curve. Any point on the curve times the order is the identity for this group (the point at infinity). Although this is optional, it’s required for some operations.
`Point`(x, y)[source]
Returns: a `Point` object with coordinates `(x, y)`
`add`(p0, p1)[source]
Parameters: p0 – a point p1 – a point the sum of the two points
`contains_point`(x, y)[source]
Parameters: x – x coordinate of a point y – y coordinate of a point True if the point (x, y) is on the curve, False otherwise
`infinity`()[source]
Returns: the “point at infinity” (also known as 0, or the identity).
`inverse_mod`(a, m)[source]
Parameters: a – an integer m – another integer the value `b` such that `a * b == 1 (mod m)`
`multiply`(p, e)[source]

multiply a point by an integer.

Parameters: p – a point e – an integer the result, equivalent to adding p to itself e times
`order`()[source]
Returns: the order of the curve.
`p`()[source]
Returns: the prime modulus of the curve.

## `Generator` Module¶

class `pycoin.ecdsa.Generator.``Generator`(p, a, b, basis, order, entropy_f=<built-in function urandom>)[source]

A Generator is a specific point on an elliptic curve that defines a trapdoor function from integers to curve points.

Parameters: p – the prime for the `Curve` a – the a value for the `Curve` b – the b value for the `Curve` basis – a `Point` on the given `Curve` order – the order for the `Curve`

The constructor raises `NoSuchPointError` if the point is invalid. The point at infinity is `(x, y) == (None, None)`.

`__mul__`(e)[source]

Multiply the generator by an integer. Uses the blinding factor.

`inverse`(a)[source]
Returns: n where `a * n == 1 (mod p) for the curve's prime p`.
`modular_sqrt`(a)[source]
Returns: n where `n * n == a (mod p) for the curve's prime p`. If no such n exists, an arbitrary value will be returned.
`points_for_x`(x)[source]
Param: x: an integer x coordinate (p0, p1) where each p is a `Point` with given x coordinate, and p0’s y value is even.
To get a point with particular parity, use::
points_for_x(x)[1 if is_y_supposed_to_be_odd else 0]
`possible_public_pairs_for_signature`(value, signature, y_parity=None)[source]
Param: value: an integer value signature: an `(r, s)` pair of integers representing an ecdsa signature of `value` y_parity: (optional) for a given value and signature, there are either two points that sign it, or none if the signature is invalid. One of the points has an even y value, the other an odd. If this parameter is set, only points whose y value matches this value will be returned in the list. a list of `Point` objects p where each p is a possible public key for which `signature` correctly signs the given `value`. If something goes wrong, this list will be empty.
`raw_mul`(e)[source]
Param: e: an integer value e * self

This method uses a precomputed table as an optimization.

`sign`(secret_exponent, val, gen_k=None)[source]
Param: secret_exponent: a `Point` on the curve val: an integer value gen_k: a function generating __k values__ a pair of integers `(r, s)` represents an ecdsa signature of `val` with public key `self * secret_exponent`.

If gen_k is set, it will be called with (n, secret_exponent, val), and an unguessable K value should be returned. Otherwise, the default K value, generated according to rfc6979 will be used.

`sign_with_recid`(secret_exponent, val, gen_k=None)[source]
Param: secret_exponent: a `Point` on the curve val: an integer value gen_k: a function generating __k values__ a tuple of integers `(r, s, recid)` where `(r, s)` represents an ecdsa signature of `val` with public key `self * secret_exponent`; and `recid` is the recovery id, a number from 0-3 used to eliminate ambiguity about which public key signed the value.

If gen_k is set, it will be called with (n, secret_exponent, val), and an unguessable K value should be returned. Otherwise, the default K value, generated according to rfc6979 will be used.

`verify`(public_pair, val, sig)[source]
Param: public_pair: a `Point` on the curve val: an integer value sig: a pair of integers `(r, s)` representing an ecdsa signature True if and only if the signature `sig` is a valid signature of `val` using `public_pair` public key.

## `Point` Module¶

exception `pycoin.ecdsa.Point.``NoSuchPointError`[source]

Bases: `exceptions.ValueError`

class `pycoin.ecdsa.Point.``Point`(x, y, curve)[source]

Bases: `tuple`

A point on an elliptic curve. This is a subclass of tuple (forced to a 2-tuple), and also includes a reference to the underlying Curve.

This class supports the operators `+`, `-` (unary and binary) and `*`.

Parameters: x – x coordinate y – y coordinate curve – the `Curve` this point must be on

The constructor raises `NoSuchPointError` if the point is invalid. The point at infinity is `(x, y) == (None, None)`.

`__add__`(other)[source]

Add one point to another point.

`__mul__`(e)[source]

Multiply a point by an integer.

`__neg__`()[source]

Unary negation

`__sub__`(other)[source]

Subtract one point from another point.

`check_on_curve`()[source]

raise `NoSuchPointError` if the point is not actually on the curve.

`curve`()[source]
Returns: the `Curve` this point is on

## `encrypt` Module¶

`pycoin.ecdsa.encrypt.``generate_shared_public_key`(my_private_key, their_public_pair, generator)[source]

Two parties each generate a private key and share their public key with the other party over an insecure channel. The shared public key can be generated by either side, but not by eavesdroppers. You can then use the entropy from the shared public key to created a common symmetric key for encryption. (This is beyond of the scope of pycoin.)

Parameters: my_private_key – an integer private key their_public_pair – a pair `(x, y)` representing a public key for the `generator` generator – a `Generator` a `Point`, which can be used as a shared public key.

## `intstream` Module¶

`pycoin.ecdsa.intstream.``from_bytes`(bytes, byteorder='big', signed=False)[source]

This is the same functionality as `int.from_bytes` in python 3

`pycoin.ecdsa.intstream.``to_bytes`(v, length, byteorder='big')[source]

This is the same functionality as `int.to_bytes` in python 3

## `rfc6979` Module¶

`pycoin.ecdsa.rfc6979.``bit_length`(v)[source]

the `int.bit_length` in python 3

`pycoin.ecdsa.rfc6979.``deterministic_generate_k`(generator_order, secret_exponent, val, hash_f=<built-in function openssl_sha256>)[source]
Parameters: generator_order – result from pycoin.ecdsa.Generator.Generator.order, necessary to ensure the k value is within bound secret_exponent – an integer secret_exponent to generate the k value for val – the value to be signed, also used as an entropy source for the k value an integer k such that `1 <= k < generator_order`, complying with

## `secp256k1` Module¶

class `pycoin.ecdsa.secp256k1.``GeneratorWithOptimizations`(p, a, b, basis, order, entropy_f=<built-in function urandom>)[source]

Bases: `pycoin.ecdsa.native.secp256k1.noop`, `pycoin.ecdsa.native.openssl.Optimizations`, `pycoin.ecdsa.Generator.Generator`

## `secp256r1` Module¶

class `pycoin.ecdsa.secp256r1.``GeneratorWithOptimizations`(p, a, b, basis, order, entropy_f=<built-in function urandom>)[source]

Bases: `pycoin.ecdsa.native.openssl.Optimizations`, `pycoin.ecdsa.Generator.Generator`

## `native.bignum` Module¶

Arrange to access a shared-object version of the bignum library using Python ctypes.

`pycoin.ecdsa.native.bignum.``bignum_type_for_library`(library)[source]

## `native.openssl` Module¶

class `pycoin.ecdsa.native.openssl.``BignumContext`[source]

Bases: `_ctypes.Structure`

`pycoin.ecdsa.native.openssl.``create_OpenSSLOptimizations`(curve_id)[source]
`pycoin.ecdsa.native.openssl.``load_library`()[source]
`pycoin.ecdsa.native.openssl.``set_api`(library, api_info)[source]

## `native.secp256k1` Module¶

`pycoin.ecdsa.native.secp256k1.``LibSECP256K1Optimizations`

alias of `pycoin.ecdsa.native.secp256k1.noop`

class `pycoin.ecdsa.native.secp256k1.``Optimizations`[source]
`multiply`(p, e)[source]

Multiply a point by an integer.

`sign`(secret_exponent, val, gen_k=None)[source]
`verify`(public_pair, val, signature_pair)[source]
`pycoin.ecdsa.native.secp256k1.``create_LibSECP256K1Optimizations`()[source]
`pycoin.ecdsa.native.secp256k1.``load_library`()[source]