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
andmode
combination is supported by this backend.Parameters: - cipher – An instance of
CipherAlgorithm
. - mode – An instance of
Mode
.
Returns: True
if the specifiedcipher
andmode
combination is supported by this backend, otherwiseFalse
- cipher – An instance of
-
create_symmetric_encryption_ctx
(cipher, mode)[source]¶ Create a
CipherContext
that can be used for encrypting data with the symmetriccipher
using the givenmode
.Parameters: - cipher – An instance of
CipherAlgorithm
. - mode – An instance of
Mode
.
Returns: Raises: ValueError – When tag is not None in an AEAD mode
- cipher – An instance of
-
create_symmetric_decryption_ctx
(cipher, mode)[source]¶ Create a
CipherContext
that can be used for decrypting data with the symmetriccipher
using the givenmode
.Parameters: - cipher – An instance of
CipherAlgorithm
. - mode – An instance of
Mode
.
Returns: Raises: ValueError – When tag is None in an AEAD mode
- cipher – An instance of
-
-
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 specifiedalgorithm
is supported by this backend, otherwiseFalse
.
-
create_hash_ctx
(algorithm)[source]¶ Create a
HashContext
that uses the specifiedalgorithm
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 specifiedalgorithm
is supported for HMAC by this backend, otherwiseFalse
.
-
create_hmac_ctx
(key, algorithm)[source]¶ Create a
HashContext
that uses the specifiedalgorithm
to calculate a hash-based message authentication code.Parameters: - key (bytes) – Secret key as
bytes
. - algorithm – An instance of
HashAlgorithm
.
Returns: - key (bytes) – Secret key as
-
-
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 specifiedalgorithm
is supported for PBKDF2 HMAC by this backend, otherwiseFalse
.
-
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.
- algorithm – An instance of
-
-
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: 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 specifiedpadding
is supported by this backend, otherwiseFalse
.
-
generate_rsa_parameters_supported
(public_exponent, key_size)[source]¶ Check if the specified parameters are supported for key generation by the backend.
Parameters:
-
load_rsa_private_numbers
(numbers)[source]¶ 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
, ormodulus
do not match the bounds specified in RFC 3447. - cryptography.exceptions.UnsupportedAlgorithm – This is raised when any backend specific criteria are not met.
- ValueError – This is raised when the values of
-
load_rsa_public_numbers
(numbers)[source]¶ Parameters: numbers – An instance of
RSAPublicNumbers
.Returns: An instance of
RSAPublicKey
.Raises: - ValueError – This is raised when the values of
public_exponent
ormodulus
do not match the bounds specified in RFC 3447. - cryptography.exceptions.UnsupportedAlgorithm – This is raised when any backend specific criteria are not met.
- ValueError – This is raised when the values of
-
-
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 specifiedalgorithm
is supported by this backend, otherwiseFalse
.
-
dsa_parameters_supported
(p, q, g)[source]¶ Parameters: Returns: True
if the given values ofp
,q
, andg
are supported by this backend, otherwiseFalse
.
-
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: - signature_algorithm – An instance of
EllipticCurveSignatureAlgorithm
. - curve – An instance of
EllipticCurve
.
Returns: True if the signature algorithm and curve are supported by this backend.
- signature_algorithm – An instance of
-
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: 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)[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: 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)[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_certificate
(data)[source]¶ Parameters: data (bytes) – PEM formatted certificate data. Returns: An instance of Certificate
.
-
load_der_x509_certificate
(data)[source]¶ Parameters: data (bytes) – DER formatted certificate data. Returns: An instance of Certificate
.
-
load_pem_x509_csr
(data)[source]¶ New in version 0.9.
Parameters: data (bytes) – PEM formatted certificate signing request data. Returns: An instance of CertificateSigningRequest
.
-
load_der_x509_csr
(data)[source]¶ 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: - builder – An instance of
CertificateSigningRequestBuilder
. - private_key – The
RSAPrivateKey
,DSAPrivateKey
orEllipticCurvePrivateKey
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
.- builder – An instance of
-
create_x509_certificate
(builder, private_key, algorithm)[source]¶ New in version 1.0.
Parameters: - builder – An instance of
CertificateBuilder
. - private_key – The
RSAPrivateKey
,DSAPrivateKey
orEllipticCurvePrivateKey
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
.- builder – An instance of
-
create_x509_crl
(builder, private_key, algorithm)[source]¶ New in version 1.2.
Parameters: - builder – An instance of
CertificateRevocationListBuilder
. - private_key – The
RSAPrivateKey
,DSAPrivateKey
orEllipticCurvePrivateKey
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
.- builder – An instance of
-
create_x509_revoked_certificate
(builder)[source]¶ New in version 1.2.
Parameters: builder – An instance of RevokedCertificateBuilder. Returns: A new instance of RevokedCertificate
.
-
-
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: 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: 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: Returns: True
if the given values ofp
,g
andq
are supported by this backend, otherwiseFalse
.
New in version 1.8.
-
-
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.
-