Danger

This is a “Hazardous Materials” module. You should ONLY use it if you’re 100% absolutely sure that you know what you’re doing because this module is full of land mines, dragons, and dinosaurs with laser guns.

Elliptic curve cryptography

cryptography.hazmat.primitives.asymmetric.ec.generate_private_key(curve, backend)

New in version 0.5.

Generate a new private key on curve for use with backend.

Parameters:
Returns:

A new instance of EllipticCurvePrivateKey.

cryptography.hazmat.primitives.asymmetric.ec.derive_private_key(private_value, curve, backend)

New in version 1.6.

Derive a private key from private_value on curve for use with backend.

Parameters:
Returns:

A new instance of EllipticCurvePrivateKey.

Elliptic Curve Signature Algorithms

class cryptography.hazmat.primitives.asymmetric.ec.ECDSA(algorithm)

New in version 0.5.

The ECDSA signature algorithm first standardized in NIST publication FIPS 186-3, and later in FIPS 186-4.

Parameters:algorithm – An instance of HashAlgorithm.
>>> from cryptography.hazmat.backends import default_backend
>>> from cryptography.hazmat.primitives import hashes
>>> from cryptography.hazmat.primitives.asymmetric import ec
>>> private_key = ec.generate_private_key(
...     ec.SECP384R1(), default_backend()
... )
>>> signer = private_key.signer(ec.ECDSA(hashes.SHA256()))
>>> signer.update(b"this is some data I'd like")
>>> signer.update(b" to sign")
>>> signature = signer.finalize()

There is a shortcut to sign sufficiently short messages directly:

>>> data = b"this is some data I'd like to sign"
>>> signature = private_key.sign(
...     data,
...     ec.ECDSA(hashes.SHA256())
... )

The signature is a bytes object, whose contents is DER encoded as described in RFC 3279. This can be decoded using decode_dss_signature().

Verification requires the public key, the signature itself, the signed data, and knowledge of the hashing algorithm that was used when producing the signature:

>>> public_key = private_key.public_key()
>>> verifier = public_key.verifier(signature, ec.ECDSA(hashes.SHA256()))
>>> verifier.update(b"this is some data I'd like")
>>> verifier.update(b" to sign")
>>> verifier.verify()
True

The last call will either return True or raise an InvalidSignature exception.

Note

Although in this case the public key was derived from the private one, in a typical setting you will not possess the private key. The Key loading section explains how to load the public key from other sources.

class cryptography.hazmat.primitives.asymmetric.ec.EllipticCurvePrivateNumbers(private_value, public_numbers)

New in version 0.5.

The collection of integers that make up an EC private key.

public_numbers
Type:EllipticCurvePublicNumbers

The EllipticCurvePublicNumbers which makes up the EC public key associated with this EC private key.

private_value
Type:int

The private value.

private_key(backend)

Convert a collection of numbers into a private key suitable for doing actual cryptographic operations.

Parameters:backend – An instance of EllipticCurveBackend.
Returns:A new instance of EllipticCurvePrivateKey.
class cryptography.hazmat.primitives.asymmetric.ec.EllipticCurvePublicNumbers(x, y, curve)

New in version 0.5.

The collection of integers that make up an EC public key.

curve
Type:EllipticCurve

The elliptic curve for this key.

x
Type:int

The affine x component of the public point used for verifying.

y
Type:int

The affine y component of the public point used for verifying.

public_key(backend)

Convert a collection of numbers into a public key suitable for doing actual cryptographic operations.

Parameters:backend – An instance of EllipticCurveBackend.
Returns:A new instance of EllipticCurvePublicKey.
encode_point()

New in version 1.1.

Encodes an elliptic curve point to a byte string as described in SEC 1 v2.0 section 2.3.3. This method only supports uncompressed points.

Return bytes:The encoded point.
classmethod from_encoded_point(curve, data)

New in version 1.1.

Decodes a byte string as described in SEC 1 v2.0 section 2.3.3 and returns an EllipticCurvePublicNumbers. This method only supports uncompressed points.

Parameters:
  • curve – An EllipticCurve instance.
  • data (bytes) – The serialized point byte string.
Returns:

An EllipticCurvePublicNumbers instance.

Raises:
  • ValueError – Raised on invalid point type or data length.
  • TypeError – Raised when curve is not an EllipticCurve.

Elliptic Curve Key Exchange algorithm

class cryptography.hazmat.primitives.asymmetric.ec.ECDH

New in version 1.1.

The Elliptic Curve Diffie-Hellman Key Exchange algorithm first standardized in NIST publication 800-56A, and later in 800-56Ar2.

For most applications the shared_key should be passed to a key derivation function.

>>> from cryptography.hazmat.backends import default_backend
>>> from cryptography.hazmat.primitives.asymmetric import ec
>>> private_key = ec.generate_private_key(
...     ec.SECP384R1(), default_backend()
... )
>>> peer_public_key = ec.generate_private_key(
...     ec.SECP384R1(), default_backend()
... ).public_key()
>>> shared_key = private_key.exchange(ec.ECDH(), peer_public_key)

ECDHE (or EECDH), the ephemeral form of this exchange, is strongly preferred over simple ECDH and provides forward secrecy when used. You must generate a new private key using generate_private_key() for each exchange() when performing an ECDHE key exchange.

Elliptic Curves

Elliptic curves provide equivalent security at much smaller key sizes than other asymmetric cryptography systems such as RSA or DSA. For many operations elliptic curves are also significantly faster; elliptic curve diffie-hellman is faster than diffie-hellman.

Note

Curves with a size of less than 224 bits should not be used. You should strongly consider using curves of at least 224 bits.

Generally the NIST prime field (“P”) curves are significantly faster than the other types suggested by NIST at both signing and verifying with ECDSA.

Prime fields also minimize the number of security concerns for elliptic-curve cryptography. However, there is some concern that both the prime field and binary field (“B”) NIST curves may have been weakened during their generation.

Currently cryptography only supports NIST curves, none of which are considered “safe” by the SafeCurves project run by Daniel J. Bernstein and Tanja Lange.

All named curves are instances of EllipticCurve.

class cryptography.hazmat.primitives.asymmetric.ec.SECT571K1

New in version 0.5.

SECG curve sect571k1. Also called NIST K-571.

class cryptography.hazmat.primitives.asymmetric.ec.SECT409K1

New in version 0.5.

SECG curve sect409k1. Also called NIST K-409.

class cryptography.hazmat.primitives.asymmetric.ec.SECT283K1

New in version 0.5.

SECG curve sect283k1. Also called NIST K-283.

class cryptography.hazmat.primitives.asymmetric.ec.SECT233K1

New in version 0.5.

SECG curve sect233k1. Also called NIST K-233.

class cryptography.hazmat.primitives.asymmetric.ec.SECT163K1

New in version 0.5.

SECG curve sect163k1. Also called NIST K-163.

class cryptography.hazmat.primitives.asymmetric.ec.SECT571R1

New in version 0.5.

SECG curve sect571r1. Also called NIST B-571.

class cryptography.hazmat.primitives.asymmetric.ec.SECT409R1

New in version 0.5.

SECG curve sect409r1. Also called NIST B-409.

class cryptography.hazmat.primitives.asymmetric.ec.SECT283R1

New in version 0.5.

SECG curve sect283r1. Also called NIST B-283.

class cryptography.hazmat.primitives.asymmetric.ec.SECT233R1

New in version 0.5.

SECG curve sect233r1. Also called NIST B-233.

class cryptography.hazmat.primitives.asymmetric.ec.SECT163R2

New in version 0.5.

SECG curve sect163r2. Also called NIST B-163.

class cryptography.hazmat.primitives.asymmetric.ec.SECP521R1

New in version 0.5.

SECG curve secp521r1. Also called NIST P-521.

class cryptography.hazmat.primitives.asymmetric.ec.SECP384R1

New in version 0.5.

SECG curve secp384r1. Also called NIST P-384.

class cryptography.hazmat.primitives.asymmetric.ec.SECP256R1

New in version 0.5.

SECG curve secp256r1. Also called NIST P-256.

class cryptography.hazmat.primitives.asymmetric.ec.SECT224R1

New in version 0.5.

SECG curve secp224r1. Also called NIST P-224.

class cryptography.hazmat.primitives.asymmetric.ec.SECP192R1

New in version 0.5.

SECG curve secp192r1. Also called NIST P-192.

class cryptography.hazmat.primitives.asymmetric.ec.SECP256K1

New in version 0.9.

SECG curve secp256k1.

Key Interfaces

class cryptography.hazmat.primitives.asymmetric.ec.EllipticCurve

New in version 0.5.

A named elliptic curve.

name
Type:string

The name of the curve. Usually the name used for the ASN.1 OID such as secp256k1.

key_size
Type:int

Size (in bits) of a secret scalar for the curve (as generated by generate_private_key()).

class cryptography.hazmat.primitives.asymmetric.ec.EllipticCurveSignatureAlgorithm

New in version 0.5.

Changed in version 1.6: Prehashed can now be used as an algorithm.

A signature algorithm for use with elliptic curve keys.

algorithm
Type:HashAlgorithm or Prehashed

The digest algorithm to be used with the signature scheme.

class cryptography.hazmat.primitives.asymmetric.ec.EllipticCurvePrivateKey

New in version 0.5.

An elliptic curve private key for use with an algorithm such as ECDSA or EdDSA.

signer(signature_algorithm)

Sign data which can be verified later by others using the public key. The signature is formatted as DER-encoded bytes, as specified in RFC 3279.

Parameters:signature_algorithm – An instance of EllipticCurveSignatureAlgorithm.
Returns:AsymmetricSignatureContext
exchange(algorithm, peer_public_key)

New in version 1.1.

Perform’s a key exchange operation using the provided algorithm with the peer’s public key.

For most applications the result should be passed to a key derivation function.

Parameters:
  • algorithm – The key exchange algorithm, currently only ECDH is supported.
  • peer_public_key (EllipticCurvePublicKey) – The public key for the peer.
Returns bytes:

A shared key.

public_key()
Returns:EllipticCurvePublicKey

The EllipticCurvePublicKey object for this private key.

sign(data, signature_algorithm)

New in version 1.5.

Sign one block of data which can be verified later by others using the public key.

Parameters:
Return bytes:

Signature.

class cryptography.hazmat.primitives.asymmetric.ec.EllipticCurvePrivateKeyWithSerialization

New in version 0.8.

Extends EllipticCurvePrivateKey.

private_numbers()

Create a EllipticCurvePrivateNumbers object.

Returns:An EllipticCurvePrivateNumbers instance.
private_bytes(encoding, format, encryption_algorithm)

Allows serialization of the key to bytes. Encoding ( PEM or DER), format ( TraditionalOpenSSL or PKCS8) and encryption algorithm (such as BestAvailableEncryption or NoEncryption) are chosen to define the exact serialization.

Parameters:
Return bytes:

Serialized key.

class cryptography.hazmat.primitives.asymmetric.ec.EllipticCurvePublicKey

New in version 0.5.

An elliptic curve public key.

verifier(signature, signature_algorithm)

Verify data was signed by the private key associated with this public key.

param bytes signature:
 The signature to verify. DER encoded as specified in RFC 3279.
param signature_algorithm:
 An instance of EllipticCurveSignatureAlgorithm.
returns:AsymmetricVerificationContext
curve
Type:EllipticCurve

The elliptic curve for this key.

public_numbers()

Create a EllipticCurvePublicNumbers object.

Returns:An EllipticCurvePublicNumbers instance.
public_bytes(encoding, format)

Allows serialization of the key to bytes. Encoding ( PEM or DER) and format ( SubjectPublicKeyInfo) are chosen to define the exact serialization.

Parameters:
Return bytes:

Serialized key.

verify(signature, data, signature_algorithm)

New in version 1.5.

Verify one block of data was signed by the private key associated with this public key.

Parameters:
  • signature (bytes) – The signature to verify.
  • data (bytes) – The message string that was signed.
  • signature_algorithm – An instance of EllipticCurveSignatureAlgorithm.
Raises:

cryptography.exceptions.InvalidSignature – If the signature does not validate.

class cryptography.hazmat.primitives.asymmetric.ec.EllipticCurvePublicKeyWithSerialization

New in version 0.6.

Alias for EllipticCurvePublicKey.

Serialization

This sample demonstrates how to generate a private key and serialize it.

>>> from cryptography.hazmat.backends import default_backend
>>> from cryptography.hazmat.primitives import hashes
>>> from cryptography.hazmat.primitives.asymmetric import ec
>>> from cryptography.hazmat.primitives import serialization

>>> private_key = ec.generate_private_key(ec.SECP384R1(), default_backend())

>>> serialized_private = private_key.private_bytes(
...     encoding=serialization.Encoding.PEM,
...     format=serialization.PrivateFormat.PKCS8,
...     encryption_algorithm=serialization.BestAvailableEncryption(b'testpassword')
...     )
>>> serialized_private.splitlines()[0]
'-----BEGIN ENCRYPTED PRIVATE KEY-----'

You can also serialize the key without a password, by relying on NoEncryption.

The public key is serialized as follows:

>>> public_key = private_key.public_key()
>>> serialized_public = public_key.public_bytes(
...     encoding=serialization.Encoding.PEM,
...     format=serialization.PublicFormat.SubjectPublicKeyInfo
...     )
>>> serialized_public.splitlines()[0]
'-----BEGIN PUBLIC KEY-----'

This is the part that you would normally share with the rest of the world.

Key loading

This extends the sample in the previous section, assuming that the variables serialized_private and serialized_public contain the respective keys in PEM format.

>>> loaded_public_key = serialization.load_pem_public_key(
...    serialized_public,
...    backend=default_backend()
...    )

>>> loaded_private_key = serialization.load_pem_private_key(
...    serialized_private,
...    password=b'testpassword',  # or password=None, if in plain text
...    backend=default_backend()
...    )