ecdsa.keys module 

classmethod from_pem(string, hashfunc=<built-in function openssl_sha1>, valid_curve_encodings=None)[source]

Initialise from key stored in PEM format.

The PEM formats supported are the un-encrypted RFC5915 (the ssleay format) supported by OpenSSL, and the more common un-encrypted RFC5958 (the PKCS #8 format).

The legacy format files have the header with the string BEGIN EC PRIVATE KEY. PKCS#8 files have the header BEGIN PRIVATE KEY. Encrypted files (ones that include the string Proc-Type: 4,ENCRYPTED right after the PEM header) are not supported.

See from_der() for ASN.1 syntax of the objects in this files.

Parameters:

string (str) – text with PEM-encoded private ECDSA key
valid_curve_encodings (set-like object) – list of allowed encoding formats for curve parameters. By default (None) all are supported: named_curve and explicit.

Raises:

MalformedPointError – if the length of encoding doesn’t match the provided curve or the encoded values is too large
RuntimeError – if the generation of public key from private key failed
UnexpectedDER – if the encoding of the PEM file is incorrect

Returns:

Initialised SigningKey object

Return type:

classmethod from_secret_exponent(secexp, curve=NIST192p, hashfunc=<built-in function openssl_sha1>)[source]

Create a private key from a random integer.

Note: it’s a low level method, it’s recommended to use the generate() method to create private keys.

Parameters:

secexp (int) – secret multiplier (the actual private key in ECDSA). Needs to be an integer between 1 and the curve order.
curve (Curve) – The curve on which the point needs to reside
hashfunc (callable) – The default hash function that will be used for signing, needs to implement the same interface as hashlib.sha1

Raises:

MalformedPointError – when the provided secexp is too large or too small for the curve selected
RuntimeError – if the generation of public key from private key failed

Returns:

Initialised SigningKey object

Return type:

classmethod from_string(string, curve=NIST192p, hashfunc=<built-in function openssl_sha1>)[source]

Decode the private key from raw encoding.

Note: the name of this method is a misnomer coming from days of Python 2, when binary strings and character strings shared a type. In Python 3, the expected type is bytes.

Parameters:

string (bytes-like object) – the raw encoding of the private key
curve (Curve) – The curve on which the point needs to reside
hashfunc (callable) – The default hash function that will be used for signing, needs to implement the same interface as hashlib.sha1

Raises:

MalformedPointError – if the length of encoding doesn’t match the provided curve or the encoded values is too large
RuntimeError – if the generation of public key from private key failed

Returns:

Initialised SigningKey object

Return type:

classmethod generate(curve=NIST192p, entropy=None, hashfunc=<built-in function openssl_sha1>)[source]

Generate a random private key.

Parameters:

curve (Curve) – The curve on which the point needs to reside, defaults to NIST192p
entropy (callable) – Source of randomness for generating the private keys, should provide cryptographically secure random numbers if the keys need to be secure. Uses os.urandom() by default.
hashfunc (callable) – The default hash function that will be used for signing, needs to implement the same interface as hashlib.sha1

Returns:

Initialised SigningKey object

Return type:

get_verifying_key()[source]

Return the VerifyingKey associated with this private key.

Equivalent to reading the verifying_key field of an instance.

Returns:: a public key that can be used to verify the signatures made with this SigningKey
Return type:: VerifyingKey

sign(data, entropy=None, hashfunc=None, sigencode=<function sigencode_string>, k=None, allow_truncate=True)[source]

Create signature over data.

Uses the probabilistic ECDSA algorithm for Weierstrass curves (NIST256p, etc.) and the deterministic EdDSA algorithm for the Edwards curves (Ed25519, Ed448).

This method uses the standard ECDSA algorithm that requires a cryptographically secure random number generator.

It’s recommended to use the sign_deterministic() method instead of this one.

Parameters:

data (bytes-like object) – data that will be hashed for signing
entropy (callable) – randomness source, os.urandom() by default. Ignored with EdDSA.
hashfunc (callable) – hash function to use for hashing the provided data. If unspecified the default hash function selected during object initialisation will be used (see VerifyingKey.default_hashfunc). Should behave like sha1() from hashlib. The output length of the hash (in bytes) must not be longer than the length of the curve order (rounded up to the nearest byte), so using SHA256 with NIST256p is ok, but SHA256 with NIST192p is not. (In the 2**-96ish unlikely event of a hash output larger than the curve order, the hash will effectively be wrapped mod n). If you want to explicitly allow use of large hashes with small curves set the allow_truncate to True. Use hashfunc=hashlib.sha1 to match openssl’s -ecdsa-with-SHA1 mode, or hashfunc=hashlib.sha256 for openssl-1.0.0’s -ecdsa-with-SHA256. Ignored for EdDSA
sigencode (callable) – function used to encode the signature. The function needs to accept three parameters: the two integers that are the signature and the order of the curve over which the signature was computed. It needs to return an encoded signature. See sigencode_string() and sigencode_der() as examples of such functions. Ignored for EdDSA
k (int) – a pre-selected nonce for calculating the signature. In typical use cases, it should be set to None (the default) to allow its generation from an entropy source. Ignored for EdDSA.
allow_truncate (bool) – if True, the provided digest can have bigger bit-size than the order of the curve, the extra bits (at the end of the digest) will be truncated. Use it when signing SHA-384 output using NIST256p or in similar situations. True by default. Ignored for EdDSA.

Raises:

RSZeroError – in the unlikely event when r parameter or s parameter of the created signature is equal 0, as that would leak the key. Caller should try a better entropy source, retry with different k, or use the sign_deterministic() in such case.

Returns:

encoded signature of the hash of data

Return type:

bytes or sigencode function dependent type

sign_deterministic(data, hashfunc=None, sigencode=<function sigencode_string>, extra_entropy=b'')[source]

Create signature over data.

For Weierstrass curves it uses the deterministic RFC6979 algorithm. For Edwards curves it uses the standard EdDSA algorithm.

For ECDSA the data will be hashed using the hashfunc function before signing. For EdDSA the data will be hashed with the hash associated with the curve (SHA-512 for Ed25519 and SHAKE-256 for Ed448).

This is the recommended method for performing signatures when hashing of data is necessary.

Parameters:

data (bytes-like object) – data to be hashed and computed signature over
hashfunc (callable) – hash function to use for computing the signature, if unspecified, the default hash function selected during object initialisation will be used (see VerifyingKey.default_hashfunc). The object needs to implement the same interface as hashlib.sha1. Ignored with EdDSA.
sigencode (callable) – function used to encode the signature. The function needs to accept three parameters: the two integers that are the signature and the order of the curve over which the signature was computed. It needs to return an encoded signature. See ecdsa.util.sigencode_string and ecdsa.util.sigencode_der as examples of such functions. Ignored with EdDSA.
extra_entropy (bytes-like object) – additional data that will be fed into the random number generator used in the RFC6979 process. Entirely optional. Ignored with EdDSA.

Returns:

encoded signature over data

Return type:

bytes or sigencode function dependent type

sign_digest(digest, entropy=None, sigencode=<function sigencode_string>, k=None, allow_truncate=False)[source]

Create signature over digest using the probabilistic ECDSA algorithm.

This method uses the standard ECDSA algorithm that requires a cryptographically secure random number generator.

This method does not hash the input.

It’s recommended to use the sign_digest_deterministic() method instead of this one.

Parameters:

digest (bytes-like object) – hash value that will be signed
entropy (callable) – randomness source, os.urandom by default
sigencode (callable) – function used to encode the signature. The function needs to accept three parameters: the two integers that are the signature and the order of the curve over which the signature was computed. It needs to return an encoded signature. See ecdsa.util.sigencode_string and ecdsa.util.sigencode_der as examples of such functions.
k (int) – a pre-selected nonce for calculating the signature. In typical use cases, it should be set to None (the default) to allow its generation from an entropy source.
allow_truncate (bool) – if True, the provided digest can have bigger bit-size than the order of the curve, the extra bits (at the end of the digest) will be truncated. Use it when signing SHA-384 output using NIST256p or in similar situations.

Raises:

RSZeroError – in the unlikely event when “r” parameter or “s” parameter of the created signature is equal 0, as that would leak the key. Caller should try a better entropy source, retry with different ‘k’, or use the sign_digest_deterministic() in such case.

Returns:

encoded signature for the digest hash

Return type:

bytes or sigencode function dependent type

sign_digest_deterministic(digest, hashfunc=None, sigencode=<function sigencode_string>, extra_entropy=b'', allow_truncate=False)[source]

Create signature for digest using the deterministic RFC6979 algorithm.

digest should be the output of cryptographically secure hash function like SHA256 or SHA-3-256.

This is the recommended method for performing signatures when no hashing of data is necessary.

Parameters:

digest (bytes-like object) – hash of data that will be signed
hashfunc (callable) – hash function to use for computing the random “k” value from RFC6979 process, if unspecified, the default hash function selected during object initialisation will be used (see VerifyingKey.default_hashfunc). The object needs to implement the same interface as sha1() from hashlib.
sigencode (callable) – function used to encode the signature. The function needs to accept three parameters: the two integers that are the signature and the order of the curve over which the signature was computed. It needs to return an encoded signature. See sigencode_string() and sigencode_der() as examples of such functions.
extra_entropy (bytes-like object) – additional data that will be fed into the random number generator used in the RFC6979 process. Entirely optional.
allow_truncate (bool) – if True, the provided digest can have bigger bit-size than the order of the curve, the extra bits (at the end of the digest) will be truncated. Use it when signing SHA-384 output using NIST256p or in similar situations.

Returns:

encoded signature for the digest hash

Return type:

bytes or sigencode function dependent type

sign_number(number, entropy=None, k=None)[source]

Sign an integer directly.

Note, this is a low level method, usually you will want to use sign_deterministic() or sign_digest_deterministic().

Parameters:

number (int) – number to sign using the probabilistic ECDSA algorithm.
entropy (callable) – entropy source, os.urandom by default
k (int) – pre-selected nonce for signature operation. If unset it will be selected at random using the entropy source.

Raises:

RSZeroError – in the unlikely event when “r” parameter or “s” parameter of the created signature is equal 0, as that would leak the key. Caller should try a better entropy source, retry with different ‘k’, or use the sign_digest_deterministic() in such case.

Returns:

the “r” and “s” parameters of the signature

Return type:

tuple of ints

to_der(point_encoding='uncompressed', format='ssleay', curve_parameters_encoding=None)[source]

Convert the private key to the DER format.

See from_der() method for format specification.

Only the named curve format is supported. The public key will be included in the generated string.

Parameters:

point_encoding (str) – format to use for encoding public point Ignored for EdDSA
format (str) – either ssleay (default) or pkcs8. EdDSA keys require pkcs8.
curve_parameters_encoding (str) – format of encoded curve parameters, default depends on the curve, if the curve has an associated OID, named_curve format will be used, if no OID is associated with the curve, the fallback of explicit parameters will be used. Ignored for EdDSA.

Returns:

DER encoded private key

Return type:

to_pem(point_encoding='uncompressed', format='ssleay', curve_parameters_encoding=None)[source]

Convert the private key to the PEM format.

See from_pem() method for format description.

Only the named curve format is supported. The public key will be included in generated string.

The PEM header will specify BEGIN EC PRIVATE KEY or BEGIN PRIVATE KEY, depending on the desired format.

Parameters:

point_encoding (str) – format to use for encoding public point
format (str) – either ssleay (default) or pkcs8
curve_parameters_encoding (str) – format of encoded curve parameters, default depends on the curve, if the curve has an associated OID, named_curve format will be used, if no OID is associated with the curve, the fallback of explicit parameters will be used.

Returns:

PEM encoded private key

Return type:

Warning

The PEM is encoded to US-ASCII, it needs to be re-encoded if the system is incompatible (e.g. uses UTF-16)

to_ssh()[source]

Convert the private key to the SSH format.

Returns:: SSH encoded private key
Return type:: bytes

to_string()[source]

Convert the private key to raw encoding.

Note: while the method is named “to_string”, its name comes from Python 2 days, when binary and character strings used the same type. The type used in Python 3 is bytes.

Returns:: raw encoding of private key
Return type:: bytes

class ecdsa.keys.VerifyingKey(_error__please_use_generate=None)[source]

Bases: object

Class for handling keys that can verify signatures (public keys).

Variables:

~.curve (Curve) – The Curve over which all the cryptographic operations will take place
default_hashfunc (callable) – the function that will be used for hashing the data. Should implement the same API as hashlib.sha1
pubkey (Public_key) – the actual public key

classmethod from_der(string, hashfunc=<built-in function openssl_sha1>, valid_encodings=None, valid_curve_encodings=None)[source]

Initialise the key stored in DER format.

The expected format of the key is the SubjectPublicKeyInfo structure from RFC5912 (for RSA keys, it’s known as the PKCS#1 format):

SubjectPublicKeyInfo {PUBLIC-KEY: IOSet} ::= SEQUENCE {
    algorithm        AlgorithmIdentifier {PUBLIC-KEY, {IOSet}},
    subjectPublicKey BIT STRING
}

Note: only public EC keys are supported by this method. The SubjectPublicKeyInfo.algorithm.algorithm field must specify id-ecPublicKey (see RFC3279).

Only the named curve encoding is supported, thus the SubjectPublicKeyInfo.algorithm.parameters field needs to be an object identifier. A sequence in that field indicates an explicit parameter curve encoding, this format is not supported. A NULL object in that field indicates an “implicitlyCA” encoding, where the curve parameters come from CA certificate, those, again, are not supported.

Parameters:

string (bytes-like object) – binary string with the DER encoding of public ECDSA key
valid_encodings (set-like object) – list of allowed point encodings. By default uncompressed, compressed, and hybrid. To read malformed files, include raw encoding with raw in the list.
valid_curve_encodings (set-like object) – list of allowed encoding formats for curve parameters. By default (None) all are supported: named_curve and explicit.

Returns:

Initialised VerifyingKey object

Return type:

classmethod from_pem(string, hashfunc=<built-in function openssl_sha1>, valid_encodings=None, valid_curve_encodings=None)[source]

Initialise from public key stored in PEM format.

The PEM header of the key should be BEGIN PUBLIC KEY.

See the from_der() method for details of the format supported.

Note: only a single PEM object decoding is supported in provided string.

Parameters:

string (str) – text with PEM-encoded public ECDSA key
valid_encodings (set-like object) – list of allowed point encodings. By default uncompressed, compressed, and hybrid. To read malformed files, include raw encoding with raw in the list.
valid_curve_encodings (set-like object) – list of allowed encoding formats for curve parameters. By default (None) all are supported: named_curve and explicit.

Returns:

Initialised VerifyingKey object

Return type:

classmethod from_public_key_recovery(signature, data, curve, hashfunc=<built-in function openssl_sha1>, sigdecode=<function sigdecode_string>, allow_truncate=True)[source]

Return keys that can be used as verifiers of the provided signature.

Tries to recover the public key that can be used to verify the signature, usually returns two keys like that.

Parameters:

signature (bytes-like object) – the byte string with the encoded signature
data (bytes-like object) – the data to be hashed for signature verification
curve (Curve) – the curve over which the signature was performed
hashfunc (callable) – The default hash function that will be used for verification, needs to implement the same interface as hashlib.sha1
sigdecode (callable) – Callable to define the way the signature needs to be decoded to an object, needs to handle signature as the first parameter, the curve order (an int) as the second and return a tuple with two integers, “r” as the first one and “s” as the second one. See ecdsa.util.sigdecode_string() and ecdsa.util.sigdecode_der() for examples.
allow_truncate (bool) – if True, the provided hashfunc can generate values larger than the bit size of the order of the curve, the extra bits (at the end of the digest) will be truncated.

Returns:

Initialised VerifyingKey objects

Return type:

list of VerifyingKey

classmethod from_public_key_recovery_with_digest(signature, digest, curve, hashfunc=<built-in function openssl_sha1>, sigdecode=<function sigdecode_string>, allow_truncate=False)[source]

Return keys that can be used as verifiers of the provided signature.

Tries to recover the public key that can be used to verify the signature, usually returns two keys like that.

Parameters:

signature (bytes-like object) – the byte string with the encoded signature
digest (bytes-like object) – the hash value of the message signed by the signature
curve (Curve) – the curve over which the signature was performed
hashfunc (callable) – The default hash function that will be used for verification, needs to implement the same interface as hashlib.sha1
sigdecode (callable) – Callable to define the way the signature needs to be decoded to an object, needs to handle signature as the first parameter, the curve order (an int) as the second and return a tuple with two integers, “r” as the first one and “s” as the second one. See ecdsa.util.sigdecode_string() and ecdsa.util.sigdecode_der() for examples.
allow_truncate (bool) – if True, the provided hashfunc can generate values larger than the bit size of the order of the curve (and the length of provided digest), the extra bits (at the end of the digest) will be truncated.

Returns:

Initialised VerifyingKey object

Return type:

classmethod from_public_point(point, curve=NIST192p, hashfunc=<built-in function openssl_sha1>, validate_point=True)[source]

Initialise the object from a Point object.

This is a low-level method, generally you will not want to use it.

Parameters:

point (AbstractPoint) – The point to wrap around, the actual public key
curve (Curve) – The curve on which the point needs to reside, defaults to NIST192p
hashfunc (callable) – The default hash function that will be used for verification, needs to implement the same interface as hashlib.sha1

Raises:

MalformedPointError – if the public point does not lay on the curve

Returns:

Initialised VerifyingKey object

Return type:

classmethod from_string(string, curve=NIST192p, hashfunc=<built-in function openssl_sha1>, validate_point=True, valid_encodings=None)[source]

Initialise the object from byte encoding of public key.

The method does accept and automatically detect the type of point encoding used. It supports the raw encoding, uncompressed, compressed, and hybrid encodings. It also works with the native encoding of Ed25519 and Ed448 public keys (technically those are compressed, but encoded differently than in other signature systems).

Note, while the method is named “from_string” it’s a misnomer from Python 2 days when there were no binary strings. In Python 3 the input needs to be a bytes-like object.

Parameters:

string (bytes-like object) – single point encoding of the public key
curve (Curve) – the curve on which the public key is expected to lay
hashfunc (callable) – The default hash function that will be used for verification, needs to implement the same interface as hashlib.sha1. Ignored for EdDSA.
validate_point (bool) – whether to verify that the point lays on the provided curve or not, defaults to True. Ignored for EdDSA.
valid_encodings (set-like object) – list of acceptable point encoding formats, supported ones are: uncompressed, compressed, hybrid, and raw encoding (specified with raw name). All formats by default (specified with None). Ignored for EdDSA.

Raises:

MalformedPointError – if the public point does not lay on the curve or the encoding is invalid

Returns:

Initialised VerifyingKey object

Return type:

precompute(lazy=False)[source]

Precompute multiplication tables for faster signature verification.

Calling this method will cause the library to precompute the scalar multiplication tables, used in signature verification. While it’s an expensive operation (comparable to performing as many signatures as the bit size of the curve, i.e. 256 for NIST256p) it speeds up verification 2 times. You should call this method if you expect to verify hundreds of signatures (or more) using the same VerifyingKey object.

Note: You should call this method only once, this method generates a new precomputation table every time it’s called.

Parameters:: lazy (bool) – whether to calculate the precomputation table now (if set to False) or if it should be delayed to the time of first use (when set to True)

to_der(point_encoding='uncompressed', curve_parameters_encoding=None)[source]

Convert the public key to the DER format.

The format of the key is described in the from_der() method. This method supports only “named curve” encoding of keys.

Parameters:

point_encoding (str) – specification of the encoding format of public keys. “uncompressed” is most portable, “compressed” is smallest. “hybrid” is uncommon and unsupported by most implementations, it is as big as “uncompressed”.
curve_parameters_encoding (str) – the encoding for curve parameters to use, by default tries to use named_curve encoding, if that is not possible, falls back to explicit encoding.

Returns:

DER encoding of the public key

Return type:

to_pem(point_encoding='uncompressed', curve_parameters_encoding=None)[source]

Convert the public key to the PEM format.

The PEM header of the key will be BEGIN PUBLIC KEY.

The format of the key is described in the from_der() method. This method supports only “named curve” encoding of keys.

Parameters:

point_encoding (str) – specification of the encoding format of public keys. “uncompressed” is most portable, “compressed” is smallest. “hybrid” is uncommon and unsupported by most implementations, it is as big as “uncompressed”.
curve_parameters_encoding (str) – the encoding for curve parameters to use, by default tries to use named_curve encoding, if that is not possible, falls back to explicit encoding.

Returns:

portable encoding of the public key

Return type: