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.

Backend interfaces

Backend implementations may provide a number of interfaces to support operations such as Symmetric encryption, Message digests (Hashing), and Hash-based message authentication codes (HMAC).

A specific backend may provide one or more of these interfaces.

class cryptography.hazmat.backends.interfaces.CipherBackend[source]

A backend that provides methods for using ciphers for encryption and decryption.

The following backends implement this interface:

cipher_supported(cipher, mode)[source]

Check if a cipher and mode combination is supported by this backend.

Parameters
Returns

True if the specified cipher and mode combination is supported by this backend, otherwise False

create_symmetric_encryption_ctx(cipher, mode)[source]

Create a CipherContext that can be used for encrypting data with the symmetric cipher using the given mode.

Parameters
Returns

CipherContext

Raises

ValueError – When tag is not None in an AEAD mode

create_symmetric_decryption_ctx(cipher, mode)[source]

Create a CipherContext that can be used for decrypting data with the symmetric cipher using the given mode.

Parameters
Returns

CipherContext

Raises

ValueError – When tag is None in an AEAD mode

class cryptography.hazmat.backends.interfaces.HashBackend[source]

A backend with methods for using cryptographic hash functions.

The following backends implement this interface:

hash_supported(algorithm)[source]

Check if the specified algorithm is supported by this backend.

Parameters

algorithm – An instance of HashAlgorithm.

Returns

True if the specified algorithm is supported by this backend, otherwise False.

create_hash_ctx(algorithm)[source]

Create a HashContext that uses the specified algorithm to calculate a message digest.

Parameters

algorithm – An instance of HashAlgorithm.

Returns

HashContext

class cryptography.hazmat.backends.interfaces.HMACBackend[source]

A backend with methods for using cryptographic hash functions as message authentication codes.

The following backends implement this interface:

hmac_supported(algorithm)[source]

Check if the specified algorithm is supported by this backend.

Parameters

algorithm – An instance of HashAlgorithm.

Returns

True if the specified algorithm is supported for HMAC by this backend, otherwise False.

create_hmac_ctx(key, algorithm)[source]

Create a HashContext that uses the specified algorithm to calculate a hash-based message authentication code.

Parameters
Returns

HashContext

class cryptography.hazmat.backends.interfaces.CMACBackend[source]

New in version 0.4.

A backend with methods for using CMAC

cmac_algorithm_supported(algorithm)[source]
Parameters

algorithm – An instance of BlockCipherAlgorithm.

Returns

Returns True if the block cipher is supported for CMAC by this backend

create_cmac_ctx(algorithm)[source]

Create a context that uses the specified algorithm to calculate a message authentication code.

Parameters

algorithm – An instance of BlockCipherAlgorithm.

Returns

CMAC object.

class cryptography.hazmat.backends.interfaces.PBKDF2HMACBackend[source]

New in version 0.2.

A backend with methods for using PBKDF2 using HMAC as a PRF.

The following backends implement this interface:

pbkdf2_hmac_supported(algorithm)[source]

Check if the specified algorithm is supported by this backend.

Parameters

algorithm – An instance of HashAlgorithm.

Returns

True if the specified algorithm is supported for PBKDF2 HMAC by this backend, otherwise False.

derive_pbkdf2_hmac(self, algorithm, length, salt, iterations, key_material)[source]
Parameters
  • algorithm – An instance of HashAlgorithm.

  • length (int) – The desired length of the derived key. Maximum is (232 - 1) * algorithm.digest_size

  • salt (bytes) – A salt.

  • iterations (int) – The number of iterations to perform of the hash function. This can be used to control the length of time the operation takes. Higher numbers help mitigate brute force attacks against derived keys.

  • key_material (bytes) – The key material to use as a basis for the derived key. This is typically a password.

Return bytes

Derived key.

class cryptography.hazmat.backends.interfaces.RSABackend[source]

New in version 0.2.

A backend with methods for using RSA.

generate_rsa_private_key(public_exponent, key_size)[source]
Parameters
  • public_exponent (int) – The public exponent of the new key. Often one of the small Fermat primes 3, 5, 17, 257 or 65537.

  • key_size (int) – The length in bits of the modulus. Should be at least 2048.

Returns

A new instance of RSAPrivateKey.

Raises

ValueError – If the public_exponent is not valid.

rsa_padding_supported(padding)[source]

Check if the specified padding is supported by the backend.

Parameters

padding – An instance of AsymmetricPadding.

Returns

True if the specified padding is supported by this backend, otherwise False.

generate_rsa_parameters_supported(public_exponent, key_size)[source]

Check if the specified parameters are supported for key generation by the backend.

Parameters
  • public_exponent (int) – The public exponent.

  • key_size (int) – The bit length of the generated modulus.

load_rsa_private_numbers(numbers)[source]
Parameters

numbers – An instance of RSAPrivateNumbers.

Returns

An instance of RSAPrivateKey.

Raises
load_rsa_public_numbers(numbers)[source]
Parameters

numbers – An instance of RSAPublicNumbers.

Returns

An instance of RSAPublicKey.

Raises
class cryptography.hazmat.backends.interfaces.DSABackend[source]

New in version 0.4.

A backend with methods for using DSA.

generate_dsa_parameters(key_size)[source]
Parameters

key_size (int) – The length of the modulus in bits. It should be either 1024, 2048 or 3072. For keys generated in 2015 this should be at least 2048. Note that some applications (such as SSH) have not yet gained support for larger key sizes specified in FIPS 186-3 and are still restricted to only the 1024-bit keys specified in FIPS 186-2.

Returns

A new instance of DSAParameters.

generate_dsa_private_key(parameters)[source]
Parameters

parameters – An instance of DSAParameters.

Returns

A new instance of DSAPrivateKey.

Raises

ValueError – This is raised if the key size is not one of 1024, 2048, or 3072.

generate_dsa_private_key_and_parameters(key_size)[source]
Parameters

key_size (int) – The length of the modulus in bits. It should be either 1024, 2048 or 3072. For keys generated in 2015 this should be at least 2048. Note that some applications (such as SSH) have not yet gained support for larger key sizes specified in FIPS 186-3 and are still restricted to only the 1024-bit keys specified in FIPS 186-2.

Returns

A new instance of DSAPrivateKey.

Raises

ValueError – This is raised if the key size is not supported by the backend.

dsa_hash_supported(algorithm)[source]
Parameters

algorithm – An instance of HashAlgorithm.

Returns

True if the specified algorithm is supported by this backend, otherwise False.

dsa_parameters_supported(p, q, g)[source]
Parameters
  • p (int) – The p value of a DSA key.

  • q (int) – The q value of a DSA key.

  • g (int) – The g value of a DSA key.

Returns

True if the given values of p, q, and g are supported by this backend, otherwise False.

load_dsa_parameter_numbers(numbers)[source]
Parameters

numbers – An instance of DSAParameterNumbers.

Returns

An instance of DSAParameters.

Raises

cryptography.exceptions.UnsupportedAlgorithm – This is raised when any backend specific criteria are not met.

load_dsa_private_numbers(numbers)[source]
Parameters

numbers – An instance of DSAPrivateNumbers.

Returns

An instance of DSAPrivateKey.

Raises

cryptography.exceptions.UnsupportedAlgorithm – This is raised when any backend specific criteria are not met.

load_dsa_public_numbers(numbers)[source]
Parameters

numbers – An instance of DSAPublicNumbers.

Returns

An instance of DSAPublicKey.

Raises

cryptography.exceptions.UnsupportedAlgorithm – This is raised when any backend specific criteria are not met.

class cryptography.hazmat.backends.interfaces.EllipticCurveBackend[source]

New in version 0.5.

elliptic_curve_supported(curve)[source]
Parameters

curve – An instance of EllipticCurve.

Returns

True if the elliptic curve is supported by this backend.

elliptic_curve_signature_algorithm_supported(signature_algorithm, curve)[source]
Parameters
Returns

True if the signature algorithm and curve are supported by this backend.

generate_elliptic_curve_private_key(curve)[source]
Parameters

curve – An instance of EllipticCurve.

load_elliptic_curve_private_numbers(numbers)[source]
Parameters

numbers – An instance of EllipticCurvePrivateNumbers.

Returns

An instance of EllipticCurvePrivateKey.

load_elliptic_curve_public_numbers(numbers)[source]
Parameters

numbers – An instance of EllipticCurvePublicNumbers.

Returns

An instance of EllipticCurvePublicKey.

derive_elliptic_curve_private_key(private_value, curve)[source]
Parameters
  • private_value – A secret scalar value.

  • curve – An instance of EllipticCurve.

Returns

An instance of EllipticCurvePrivateKey.

class cryptography.hazmat.backends.interfaces.PEMSerializationBackend[source]

New in version 0.6.

A backend with methods for working with any PEM encoded keys.

load_pem_private_key(data, password)[source]
Parameters
  • data (bytes) – PEM data to load.

  • password (bytes) – The password to use if the data is encrypted. Should be None if the data is not encrypted.

Returns

A new instance of the appropriate type of private key that the serialized data contains.

Raises
load_pem_public_key(data)[source]
Parameters

data (bytes) – PEM data to load.

Returns

A new instance of the appropriate type of public key serialized data contains.

Raises

ValueError – If the data could not be deserialized.

load_pem_parameters(data)[source]

New in version 2.0.

Parameters

data (bytes) – PEM data to load.

Returns

A new instance of the appropriate type of asymmetric parameters the serialized data contains.

Raises

ValueError – If the data could not be deserialized.

class cryptography.hazmat.backends.interfaces.DERSerializationBackend[source]

New in version 0.8.

A backend with methods for working with DER encoded keys.

load_der_private_key(data, password)[source]
Parameters
  • data (bytes) – DER data to load.

  • password (bytes) – The password to use if the data is encrypted. Should be None if the data is not encrypted.

Returns

A new instance of the appropriate type of private key that the serialized data contains.

Raises
load_der_public_key(data)[source]
Parameters

data (bytes) – DER data to load.

Returns

A new instance of the appropriate type of public key serialized data contains.

Raises

ValueError – If the data could not be deserialized.

load_der_parameters(data)[source]

New in version 2.0.

Parameters

data (bytes) – DER data to load.

Returns

A new instance of the appropriate type of asymmetric parameters the serialized data contains.

Raises

ValueError – If the data could not be deserialized.

class cryptography.hazmat.backends.interfaces.X509Backend[source]

New in version 0.7.

A backend with methods for working with X.509 objects.

load_pem_x509_csr(data)

New in version 0.9.

Parameters

data (bytes) – PEM formatted certificate signing request data.

Returns

An instance of CertificateSigningRequest.

load_der_x509_csr(data)

New in version 0.9.

Parameters

data (bytes) – DER formatted certificate signing request data.

Returns

An instance of CertificateSigningRequest.

create_x509_csr(builder, private_key, algorithm)[source]

New in version 1.0.

Parameters
Returns

A new instance of CertificateSigningRequest.

create_x509_certificate(builder, private_key, algorithm)[source]

New in version 1.0.

Parameters
Returns

A new instance of Certificate.

create_x509_crl(builder, private_key, algorithm)[source]

New in version 1.2.

Parameters
Returns

A new instance of CertificateRevocationList.

create_x509_revoked_certificate(builder)[source]

New in version 1.2.

Parameters

builder – An instance of RevokedCertificateBuilder.

Returns

A new instance of RevokedCertificate.

x509_name_bytes(name)

New in version 1.6.

Parameters

name – An instance of Name.

Return bytes

The DER encoded bytes.

class cryptography.hazmat.backends.interfaces.DHBackend[source]

New in version 0.9.

A backend with methods for doing Diffie-Hellman key exchange.

generate_dh_parameters(generator, key_size)[source]
Parameters
  • generator (int) – The generator to use. Often 2 or 5.

  • key_size (int) – The bit length of the prime modulus to generate.

Returns

A new instance of DHParameters.

Raises

ValueError – If key_size is not at least 512.

generate_dh_private_key(parameters)[source]
Parameters

parameters – An instance of DHParameters.

Returns

A new instance of DHPrivateKey.

generate_dh_private_key_and_parameters(generator, key_size)[source]
Parameters
  • generator (int) – The generator to use. Often 2 or 5.

  • key_size (int) – The bit length of the prime modulus to generate.

Returns

A new instance of DHPrivateKey.

Raises

ValueError – If key_size is not at least 512.

load_dh_private_numbers(numbers)[source]
Parameters

numbers – A DHPrivateNumbers instance.

Returns

A new instance of DHPrivateKey.

Raises

cryptography.exceptions.UnsupportedAlgorithm – This is raised when any backend specific criteria are not met.

load_dh_public_numbers(numbers)[source]
Parameters

numbers – A DHPublicNumbers instance.

Returns

A new instance of DHPublicKey.

Raises

cryptography.exceptions.UnsupportedAlgorithm – This is raised when any backend specific criteria are not met.

load_dh_parameter_numbers(numbers)[source]
Parameters

numbers – A DHParameterNumbers instance.

Returns

A new instance of DHParameters.

Raises

cryptography.exceptions.UnsupportedAlgorithm – This is raised when any backend specific criteria are not met.

dh_parameters_supported(p, g, q=None)[source]
Parameters
  • p (int) – The p value of the DH key.

  • g (int) – The g value of the DH key.

  • q (int) – The q value of the DH key.

Returns

True if the given values of p, g and q are supported by this backend, otherwise False.

New in version 1.8.

dh_x942_serialization_supported()[source]
Returns

True if serialization of DH objects with subgroup order (q) is supported by this backend.

class cryptography.hazmat.backends.interfaces.ScryptBackend[source]

New in version 1.6.

A backend with methods for using Scrypt.

The following backends implement this interface:

derive_scrypt(self, key_material, salt, length, n, r, p)[source]
Parameters
  • key_material (bytes) – The key material to use as a basis for the derived key. This is typically a password.

  • salt (bytes) – A salt.

  • length (int) – The desired length of the derived key.

  • n (int) – CPU/Memory cost parameter. It must be larger than 1 and be a power of 2.

  • r (int) – Block size parameter.

  • p (int) – Parallelization parameter.

Return bytes

Derived key.