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

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

  The following backends implement this interface:

  - OpenSSL backend

  cipher_supported(cipher, mode)

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

    Parameters

      - cipher – An instance of `CipherAlgorithm`.

      - mode – An instance of `Mode`.

    Returns

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

  create_symmetric_encryption_ctx(cipher, mode)

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

    Parameters

      - cipher – An instance of `CipherAlgorithm`.

      - mode – An instance of `Mode`.

    Returns

      `CipherContext`

    Raises

      ValueError – When tag is not None in an AEAD mode

  create_symmetric_decryption_ctx(cipher, mode)

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

    Parameters

      - cipher – An instance of `CipherAlgorithm`.

      - mode – An instance of `Mode`.

    Returns

      `CipherContext`

    Raises

      ValueError – When tag is None in an AEAD mode

class cryptography.hazmat.backends.interfaces.HashBackend

  A backend with methods for using cryptographic hash functions.

  The following backends implement this interface:

  - OpenSSL backend

  hash_supported(algorithm)

    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)

    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

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

  The following backends implement this interface:

  - OpenSSL backend

  hmac_supported(algorithm)

    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)

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

    Parameters

      - key (bytes) – Secret key as `bytes`.

      - algorithm – An instance of `HashAlgorithm`.

    Returns

      `HashContext`

class cryptography.hazmat.backends.interfaces.CMACBackend

  New in version 0.4.

  A backend with methods for using CMAC

  cmac_algorithm_supported(algorithm)
    Parameters

      algorithm – An instance of `BlockCipherAlgorithm`.

    Returns

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

  create_cmac_ctx(algorithm)

    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

  New in version 0.2.

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

  The following backends implement this interface:

  - OpenSSL backend

  pbkdf2_hmac_supported(algorithm)

    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)
    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

  New in version 0.2.

  A backend with methods for using RSA.

  generate_rsa_private_key(public_exponent, key_size)
    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)

    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)

    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)
    Parameters

      numbers – An instance of `RSAPrivateNumbers`.

    Returns

      An instance of `RSAPrivateKey`.

    Raises

      - ValueError – This is raised when the values of `p`, `q`, `private_exponent`, `public_exponent`, or `modulus` do not match the bounds specified in RFC 3447.

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

  load_rsa_public_numbers(numbers)
    Parameters

      numbers – An instance of `RSAPublicNumbers`.

    Returns

      An instance of `RSAPublicKey`.

    Raises

      - ValueError – This is raised when the values of `public_exponent` or `modulus` do not match the bounds specified in RFC 3447.

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

class cryptography.hazmat.backends.interfaces.DSABackend

  New in version 0.4.

  A backend with methods for using DSA.

  generate_dsa_parameters(key_size)
    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)
    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)
    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)
    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)
    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)
    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)
    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)
    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

  New in version 0.5.

  elliptic_curve_supported(curve)
    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)
    Parameters

      - signature_algorithm – An instance of `EllipticCurveSignatureAlgorithm`.

      - curve – An instance of `EllipticCurve`.

    Returns

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

  generate_elliptic_curve_private_key(curve)
    Parameters

      curve – An instance of `EllipticCurve`.

  load_elliptic_curve_private_numbers(numbers)
    Parameters

      numbers – An instance of `EllipticCurvePrivateNumbers`.

    Returns

      An instance of `EllipticCurvePrivateKey`.

  load_elliptic_curve_public_numbers(numbers)
    Parameters

      numbers – An instance of `EllipticCurvePublicNumbers`.

    Returns

      An instance of `EllipticCurvePublicKey`.

  derive_elliptic_curve_private_key(private_value, curve)
    Parameters

      - private_value – A secret scalar value.

      - curve – An instance of `EllipticCurve`.

    Returns

      An instance of `EllipticCurvePrivateKey`.

class cryptography.hazmat.backends.interfaces.PEMSerializationBackend

  New in version 0.6.

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

  load_pem_private_key(data, password)
    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

      - ValueError – If the data could not be deserialized.

      - cryptography.exceptions.UnsupportedAlgorithm – If the data is encrypted with an unsupported algorithm.

  load_pem_public_key(data)
    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)

    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

  New in version 0.8.

  A backend with methods for working with DER encoded keys.

  load_der_private_key(data, password)
    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

      - ValueError – If the data could not be deserialized.

      - cryptography.exceptions.UnsupportedAlgorithm – If the data is encrypted with an unsupported algorithm.

  load_der_public_key(data)
    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)

    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

  New in version 0.7.

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

  load_pem_x509_certificate(data)
    Parameters

      data (bytes) – PEM formatted certificate data.

    Returns

      An instance of `Certificate`.

  load_der_x509_certificate(data)
    Parameters

      data (bytes) – DER formatted certificate data.

    Returns

      An instance of `Certificate`.

  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)

    New in version 1.0.

    Parameters

      - builder – An instance of `CertificateSigningRequestBuilder`.

      - private_key – The `RSAPrivateKey`, `DSAPrivateKey` or `EllipticCurvePrivateKey` that will be used to sign the request. When the request is signed by a certificate authority, the private key’s associated public key will be stored in the resulting certificate.

      - algorithm – The `HashAlgorithm` that will be used to generate the request signature.

    Returns

      A new instance of `CertificateSigningRequest`.

  create_x509_certificate(builder, private_key, algorithm)

    New in version 1.0.

    Parameters

      - builder – An instance of `CertificateBuilder`.

      - private_key – The `RSAPrivateKey`, `DSAPrivateKey` or `EllipticCurvePrivateKey` that will be used to sign the certificate.

      - algorithm – The `HashAlgorithm` that will be used to generate the certificate signature.

    Returns

      A new instance of `Certificate`.

  create_x509_crl(builder, private_key, algorithm)

    New in version 1.2.

    Parameters

      - builder – An instance of `CertificateRevocationListBuilder`.

      - private_key – The `RSAPrivateKey`, `DSAPrivateKey` or `EllipticCurvePrivateKey` that will be used to sign the CRL.

      - algorithm – The `HashAlgorithm` that will be used to generate the CRL signature.

    Returns

      A new instance of `CertificateRevocationList`.

  create_x509_revoked_certificate(builder)

    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

  New in version 0.9.

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

  generate_dh_parameters(generator, key_size)
    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)
    Parameters

      parameters – An instance of `DHParameters`.

    Returns

      A new instance of `DHPrivateKey`.

  generate_dh_private_key_and_parameters(generator, key_size)
    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)
    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)
    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)
    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)
    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()
    Returns

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

class cryptography.hazmat.backends.interfaces.ScryptBackend

  New in version 1.6.

  A backend with methods for using Scrypt.

  The following backends implement this interface:

  - OpenSSL backend

  derive_scrypt(self, key_material, salt, length, n, r, p)
    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.