ecdsa.util module

This module includes some utility functions.

The methods most typically used are the sigencode and sigdecode functions to be used with sign() and verify() respectively. See the sigencode_strings(), sigdecode_string(), sigencode_der(), sigencode_strings_canonize(), sigencode_string_canonize(), sigencode_der_canonize(), sigdecode_strings(), sigdecode_string(), and sigdecode_der() functions.

exception ecdsa.util.MalformedSignature

Bases: Exception

Raised by decoding functions when the signature is malformed.

Malformed in this context means that the relevant strings or integers do not match what a signature over provided curve would create. Either because the byte strings have incorrect lengths or because the encoded values are too large.

add_note()

Exception.add_note(note) – add a note to the exception

args

with_traceback()

Exception.with_traceback(tb) – set self.__traceback__ to tb and return self.

class ecdsa.util.PRNG(seed)

Bases: object

block_generator(seed)

ecdsa.util.bit_length(x)

ecdsa.util.bits_and_bytes(order)

ecdsa.util.entropy_to_bits(ent_256)

Convert a bytestring to string of 0’s and 1’s

ecdsa.util.int2byte()

S.pack(v1, v2, …) -> bytes

Return a bytes object containing values v1, v2, … packed according to the format string S.format. See help(struct) for more on format strings.

ecdsa.util.lsb_of_ones(numbits)

ecdsa.util.number_to_string(num, order)

ecdsa.util.number_to_string_crop(num, order)

ecdsa.util.orderlen(order)

ecdsa.util.randrange(order, entropy=None)

Return a random integer k such that 1 <= k < order, uniformly distributed across that range. Worst case should be a mean of 2 loops at (2**k)+2.

Note that this function is not declared to be forwards-compatible: we may change the behavior in future releases. The entropy= argument (which should get a callable that behaves like os.urandom) can be used to achieve stability within a given release (for repeatable unit tests), but should not be used as a long-term-compatible key generation algorithm.

ecdsa.util.randrange_from_seed__overshoot_modulo(seed, order)

ecdsa.util.randrange_from_seed__truncate_bits(seed, order, hashmod=<built-in function openssl_sha256>)

ecdsa.util.randrange_from_seed__truncate_bytes(seed, order, hashmod=<built-in function openssl_sha256>)

ecdsa.util.randrange_from_seed__trytryagain(seed, order)

ecdsa.util.sigdecode_der(sig_der, order)

Decoder for DER format of ECDSA signatures.

DER format of signature is one that uses the ASN.1 DER rules to encode it as a sequence of two integers:

Ecdsa-Sig-Value ::= SEQUENCE {
    r       INTEGER,
    s       INTEGER
}

It’s expected that this function will be used as as the sigdecode= parameter to the ecdsa.keys.VerifyingKey.verify() method.

Parameters:

• sig_der (bytes like object) – encoded signature

• order (int) – order of the curve over which the signature was computed

Raises:

UnexpectedDER – when the encoding of signature is invalid

Returns:

tuple with decoded r and s values of signature

Return type:

tuple of ints

ecdsa.util.sigdecode_string(signature, order)

Decoder for raw encoding of ECDSA signatures.

raw encoding is a simple concatenation of the two integers that comprise the signature, with each encoded using the same amount of bytes depending on curve size/order.

It’s expected that this function will be used as the sigdecode= parameter to the ecdsa.keys.VerifyingKey.verify() method.

Parameters:

• signature (bytes like object) – encoded signature

• order (int) – order of the curve over which the signature was computed

Raises:

MalformedSignature – when the encoding of the signature is invalid

Returns:

tuple with decoded r and s values of signature

Return type:

tuple of ints

ecdsa.util.sigdecode_strings(rs_strings, order)

Decode the signature from two strings.

First string needs to be a big endian encoding of r, second needs to be a big endian encoding of the s parameter of an ECDSA signature.

It’s expected that this function will be used as the sigdecode= parameter to the ecdsa.keys.VerifyingKey.verify() method.

Parameters:

• rs_strings (list) – list of two bytes-like objects, each encoding one parameter of signature

• order (int) – order of the curve over which the signature was computed

Raises:

MalformedSignature – when the encoding of the signature is invalid

Returns:

tuple with decoded r and s values of signature

Return type:

tuple of ints

ecdsa.util.sigencode_der(r, s, order)

Encode the signature into the ECDSA-Sig-Value structure using DER.

Encodes the signature to the following ASN.1 structure:

Ecdsa-Sig-Value ::= SEQUENCE {
    r       INTEGER,
    s       INTEGER
}

It’s expected that this function will be used as a sigencode= parameter in ecdsa.keys.SigningKey.sign() method.

Parameters:

• r (int) – first parameter of the signature

• s (int) – second parameter of the signature

• order (int) – the order of the curve over which the signature was computed

Returns:

DER encoding of ECDSA signature

Return type:

bytes

ecdsa.util.sigencode_der_canonize(r, s, order)

Encode the signature into the ECDSA-Sig-Value structure using DER.

Makes sure that the signature is encoded in the canonical format, where the s parameter is always smaller than order / 2. Most commonly used in bitcoin.

Encodes the signature to the following ASN.1 structure:

Ecdsa-Sig-Value ::= SEQUENCE {
    r       INTEGER,
    s       INTEGER
}

It’s expected that this function will be used as a sigencode= parameter in ecdsa.keys.SigningKey.sign() method.

Parameters:

• r (int) – first parameter of the signature

• s (int) – second parameter of the signature

• order (int) – the order of the curve over which the signature was computed

Returns:

DER encoding of ECDSA signature

Return type:

bytes

ecdsa.util.sigencode_string(r, s, order)

Encode the signature to raw format (raw encoding)

It’s expected that this function will be used as a sigencode= parameter in ecdsa.keys.SigningKey.sign() method.

Parameters:

• r (int) – first parameter of the signature

• s (int) – second parameter of the signature

• order (int) – the order of the curve over which the signature was computed

Returns:

raw encoding of ECDSA signature

Return type:

bytes

ecdsa.util.sigencode_string_canonize(r, s, order)

Encode the signature to raw format (raw encoding)

Makes sure that the signature is encoded in the canonical format, where the s parameter is always smaller than order / 2. Most commonly used in bitcoin.

It’s expected that this function will be used as a sigencode= parameter in ecdsa.keys.SigningKey.sign() method.

Parameters:

• r (int) – first parameter of the signature

• s (int) – second parameter of the signature

• order (int) – the order of the curve over which the signature was computed

Returns:

raw encoding of ECDSA signature

Return type:

bytes

ecdsa.util.sigencode_strings(r, s, order)

Encode the signature to a pair of strings in a tuple

Encodes signature into raw encoding (raw encoding) with the r and s parts of the signature encoded separately.

It’s expected that this function will be used as a sigencode= parameter in ecdsa.keys.SigningKey.sign() method.

Parameters:

• r (int) – first parameter of the signature

• s (int) – second parameter of the signature

• order (int) – the order of the curve over which the signature was computed

Returns:

raw encoding of ECDSA signature

Return type:

tuple(bytes, bytes)

ecdsa.util.sigencode_strings_canonize(r, s, order)

Encode the signature to a pair of strings in a tuple

Encodes signature into raw encoding (raw encoding) with the r and s parts of the signature encoded separately.

Makes sure that the signature is encoded in the canonical format, where the s parameter is always smaller than order / 2. Most commonly used in bitcoin.

It’s expected that this function will be used as a sigencode= parameter in ecdsa.keys.SigningKey.sign() method.

Parameters:

• r (int) – first parameter of the signature

• s (int) – second parameter of the signature

• order (int) – the order of the curve over which the signature was computed

Returns:

raw encoding of ECDSA signature

Return type:

tuple(bytes, bytes)

ecdsa.util.string_to_number(string)

ecdsa.util.string_to_number_fixedlen(string, order)