diff options
Diffstat (limited to 'docs/hazmat/backends')
| -rw-r--r-- | docs/hazmat/backends/commoncrypto.rst | 30 | ||||
| -rw-r--r-- | docs/hazmat/backends/index.rst | 10 | ||||
| -rw-r--r-- | docs/hazmat/backends/interfaces.rst | 351 | ||||
| -rw-r--r-- | docs/hazmat/backends/multibackend.rst | 45 | ||||
| -rw-r--r-- | docs/hazmat/backends/openssl.rst | 56 |
5 files changed, 273 insertions, 219 deletions
diff --git a/docs/hazmat/backends/commoncrypto.rst b/docs/hazmat/backends/commoncrypto.rst deleted file mode 100644 index ddaf97e5..00000000 --- a/docs/hazmat/backends/commoncrypto.rst +++ /dev/null @@ -1,30 +0,0 @@ -.. hazmat:: - -CommonCrypto backend -==================== - -The `CommonCrypto`_ C library provided by Apple on OS X and iOS. The -CommonCrypto backend is only supported on OS X versions 10.8 and above. - -.. currentmodule:: cryptography.hazmat.backends.commoncrypto.backend - -.. versionadded:: 0.2 - -.. data:: cryptography.hazmat.backends.commoncrypto.backend - - This is the exposed API for the CommonCrypto backend. - - It implements the following interfaces: - - * :class:`~cryptography.hazmat.backends.interfaces.CipherBackend` - * :class:`~cryptography.hazmat.backends.interfaces.HashBackend` - * :class:`~cryptography.hazmat.backends.interfaces.HMACBackend` - * :class:`~cryptography.hazmat.backends.interfaces.PBKDF2HMACBackend` - - It has one additional public attribute. - - .. attribute:: name - - The string name of this backend: ``"commoncrypto"`` - -.. _`CommonCrypto`: https://developer.apple.com/library/mac/documentation/Darwin/Reference/ManPages/man3/Common%20Crypto.3cc.html diff --git a/docs/hazmat/backends/index.rst b/docs/hazmat/backends/index.rst index aec7a1e0..a8a1ff30 100644 --- a/docs/hazmat/backends/index.rst +++ b/docs/hazmat/backends/index.rst @@ -8,15 +8,11 @@ Getting a backend .. currentmodule:: cryptography.hazmat.backends -``cryptography`` aims to support multiple backends to ensure it can provide -the widest number of supported cryptographic algorithms as well as supporting -platform specific implementations. +``cryptography`` was originally designed to support multiple backends, but +this design has been deprecated. You can get the default backend by calling :func:`~default_backend`. -The default backend will change over time as we implement new backends and -the libraries we use in those backends changes. - .. function:: default_backend() @@ -31,6 +27,4 @@ Individual backends :maxdepth: 1 openssl - commoncrypto - multibackend interfaces diff --git a/docs/hazmat/backends/interfaces.rst b/docs/hazmat/backends/interfaces.rst index fb3786c3..36dd3a7a 100644 --- a/docs/hazmat/backends/interfaces.rst +++ b/docs/hazmat/backends/interfaces.rst @@ -22,18 +22,17 @@ A specific ``backend`` may provide one or more of these interfaces. The following backends implement this interface: * :doc:`/hazmat/backends/openssl` - * :doc:`/hazmat/backends/commoncrypto` .. method:: cipher_supported(cipher, mode) Check if a ``cipher`` and ``mode`` combination is supported by this backend. - :param cipher: An instance of a - :class:`~cryptography.hazmat.primitives.ciphers.CipherAlgorithm` - provider. - :param mode: An instance of a - :class:`~cryptography.hazmat.primitives.ciphers.modes.Mode` provider. + :param cipher: An instance of + :class:`~cryptography.hazmat.primitives.ciphers.CipherAlgorithm`. + + :param mode: An instance of + :class:`~cryptography.hazmat.primitives.ciphers.modes.Mode`. :returns: ``True`` if the specified ``cipher`` and ``mode`` combination is supported by this backend, otherwise ``False`` @@ -46,11 +45,11 @@ A specific ``backend`` may provide one or more of these interfaces. can be used for encrypting data with the symmetric ``cipher`` using the given ``mode``. - :param cipher: An instance of a - :class:`~cryptography.hazmat.primitives.ciphers.CipherAlgorithm` - provider. - :param mode: An instance of a - :class:`~cryptography.hazmat.primitives.ciphers.modes.Mode` provider. + :param cipher: An instance of + :class:`~cryptography.hazmat.primitives.ciphers.CipherAlgorithm`. + + :param mode: An instance of + :class:`~cryptography.hazmat.primitives.ciphers.modes.Mode`. :returns: :class:`~cryptography.hazmat.primitives.ciphers.CipherContext` @@ -65,11 +64,11 @@ A specific ``backend`` may provide one or more of these interfaces. can be used for decrypting data with the symmetric ``cipher`` using the given ``mode``. - :param cipher: An instance of a - :class:`~cryptography.hazmat.primitives.ciphers.CipherAlgorithm` - provider. - :param mode: An instance of a - :class:`~cryptography.hazmat.primitives.ciphers.modes.Mode` provider. + :param cipher: An instance of + :class:`~cryptography.hazmat.primitives.ciphers.CipherAlgorithm`. + + :param mode: An instance of + :class:`~cryptography.hazmat.primitives.ciphers.modes.Mode`. :returns: :class:`~cryptography.hazmat.primitives.ciphers.CipherContext` @@ -84,15 +83,13 @@ A specific ``backend`` may provide one or more of these interfaces. The following backends implement this interface: * :doc:`/hazmat/backends/openssl` - * :doc:`/hazmat/backends/commoncrypto` .. method:: hash_supported(algorithm) Check if the specified ``algorithm`` is supported by this backend. - :param algorithm: An instance of a - :class:`~cryptography.hazmat.primitives.hashes.HashAlgorithm` - provider. + :param algorithm: An instance of + :class:`~cryptography.hazmat.primitives.hashes.HashAlgorithm`. :returns: ``True`` if the specified ``algorithm`` is supported by this backend, otherwise ``False``. @@ -104,9 +101,8 @@ A specific ``backend`` may provide one or more of these interfaces. :class:`~cryptography.hazmat.primitives.hashes.HashContext` that uses the specified ``algorithm`` to calculate a message digest. - :param algorithm: An instance of a - :class:`~cryptography.hazmat.primitives.hashes.HashAlgorithm` - provider. + :param algorithm: An instance of + :class:`~cryptography.hazmat.primitives.hashes.HashAlgorithm`. :returns: :class:`~cryptography.hazmat.primitives.hashes.HashContext` @@ -120,29 +116,28 @@ A specific ``backend`` may provide one or more of these interfaces. The following backends implement this interface: * :doc:`/hazmat/backends/openssl` - * :doc:`/hazmat/backends/commoncrypto` .. method:: hmac_supported(algorithm) Check if the specified ``algorithm`` is supported by this backend. - :param algorithm: An instance of a - :class:`~cryptography.hazmat.primitives.hashes.HashAlgorithm` - provider. + :param algorithm: An instance of + :class:`~cryptography.hazmat.primitives.hashes.HashAlgorithm`. :returns: ``True`` if the specified ``algorithm`` is supported for HMAC by this backend, otherwise ``False``. - .. method:: create_hmac_ctx(algorithm) + .. method:: create_hmac_ctx(key, algorithm) Create a :class:`~cryptography.hazmat.primitives.hashes.HashContext` that uses the specified ``algorithm`` to calculate a hash-based message authentication code. - :param algorithm: An instance of a - :class:`~cryptography.hazmat.primitives.hashes.HashAlgorithm` - provider. + :param bytes key: Secret key as ``bytes``. + + :param algorithm: An instance of + :class:`~cryptography.hazmat.primitives.hashes.HashAlgorithm`. :returns: :class:`~cryptography.hazmat.primitives.hashes.HashContext` @@ -156,23 +151,21 @@ A specific ``backend`` may provide one or more of these interfaces. .. method:: cmac_algorithm_supported(algorithm) - :param algorithm: An instance of a - :class:`~cryptography.hazmat.primitives.ciphers.BlockCipherAlgorithm` - provider. + :param algorithm: An instance of + :class:`~cryptography.hazmat.primitives.ciphers.BlockCipherAlgorithm`. + :return: Returns True if the block cipher is supported for CMAC by this backend .. method:: create_cmac_ctx(algorithm) Create a - :class:`~cryptography.hazmat.primitives.interfaces.MACContext` that + context that uses the specified ``algorithm`` to calculate a message authentication code. - :param algorithm: An instance of a - :class:`~cryptography.hazmat.primitives.ciphers.BlockCipherAlgorithm` - provider. + :param algorithm: An instance of + :class:`~cryptography.hazmat.primitives.ciphers.BlockCipherAlgorithm`. - :returns: - :class:`~cryptography.hazmat.primitives.interfaces.MACContext` + :returns: CMAC object. .. class:: PBKDF2HMACBackend @@ -184,24 +177,21 @@ A specific ``backend`` may provide one or more of these interfaces. The following backends implement this interface: * :doc:`/hazmat/backends/openssl` - * :doc:`/hazmat/backends/commoncrypto` .. method:: pbkdf2_hmac_supported(algorithm) Check if the specified ``algorithm`` is supported by this backend. - :param algorithm: An instance of a - :class:`~cryptography.hazmat.primitives.hashes.HashAlgorithm` - provider. + :param algorithm: An instance of + :class:`~cryptography.hazmat.primitives.hashes.HashAlgorithm`. :returns: ``True`` if the specified ``algorithm`` is supported for PBKDF2 HMAC by this backend, otherwise ``False``. .. method:: derive_pbkdf2_hmac(self, algorithm, length, salt, iterations, key_material) - :param algorithm: An instance of a - :class:`~cryptography.hazmat.primitives.hashes.HashAlgorithm` - provider. + :param algorithm: An instance of + :class:`~cryptography.hazmat.primitives.hashes.HashAlgorithm`. :param int length: The desired length of the derived key. Maximum is (2\ :sup:`32` - 1) * ``algorithm.digest_size`` @@ -233,9 +223,8 @@ A specific ``backend`` may provide one or more of these interfaces. :param int key_size: The length in bits of the modulus. Should be at least 2048. - :return: A new instance of a - :class:`~cryptography.hazmat.primitives.asymmetric.rsa.RSAPrivateKey` - provider. + :return: A new instance of + :class:`~cryptography.hazmat.primitives.asymmetric.rsa.RSAPrivateKey`. :raises ValueError: If the public_exponent is not valid. @@ -243,9 +232,8 @@ A specific ``backend`` may provide one or more of these interfaces. Check if the specified ``padding`` is supported by the backend. - :param padding: An instance of an - :class:`~cryptography.hazmat.primitives.asymmetric.padding.AsymmetricPadding` - provider. + :param padding: An instance of + :class:`~cryptography.hazmat.primitives.asymmetric.padding.AsymmetricPadding`. :returns: ``True`` if the specified ``padding`` is supported by this backend, otherwise ``False``. @@ -264,7 +252,7 @@ A specific ``backend`` may provide one or more of these interfaces. :param numbers: An instance of :class:`~cryptography.hazmat.primitives.asymmetric.rsa.RSAPrivateNumbers`. - :returns: A provider of + :returns: An instance of :class:`~cryptography.hazmat.primitives.asymmetric.rsa.RSAPrivateKey`. :raises ValueError: This is raised when the values of ``p``, ``q``, @@ -277,9 +265,9 @@ A specific ``backend`` may provide one or more of these interfaces. .. method:: load_rsa_public_numbers(numbers) :param numbers: An instance of - :class:`~cryptography.hazmat.primitives.asymmetric.rsa.RSAPrivateNumbers`. + :class:`~cryptography.hazmat.primitives.asymmetric.rsa.RSAPublicNumbers`. - :returns: A provider of + :returns: An instance of :class:`~cryptography.hazmat.primitives.asymmetric.rsa.RSAPublicKey`. :raises ValueError: This is raised when the values of @@ -305,24 +293,19 @@ A specific ``backend`` may provide one or more of these interfaces. 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. - :return: A new instance of a - :class:`~cryptography.hazmat.primitives.asymmetric.dsa.DSAParameters` - provider. + :return: A new instance of + :class:`~cryptography.hazmat.primitives.asymmetric.dsa.DSAParameters`. .. method:: generate_dsa_private_key(parameters) - :param parameters: A - :class:`~cryptography.hazmat.primitives.asymmetric.dsa.DSAParameters` - provider. + :param parameters: An instance of + :class:`~cryptography.hazmat.primitives.asymmetric.dsa.DSAParameters`. - :return: A new instance of a - :class:`~cryptography.hazmat.primitives.asymmetric.dsa.DSAPrivateKey` - provider. + :return: A new instance of + :class:`~cryptography.hazmat.primitives.asymmetric.dsa.DSAPrivateKey`. :raises ValueError: This is raised if the key size is not one of 1024, - 2048, or 3072. It is also raised when OpenSSL is older than version - 1.0.0 and the key size is larger than 1024; older OpenSSL versions - do not support keys larger than 1024 bits. + 2048, or 3072. .. method:: generate_dsa_private_key_and_parameters(key_size) @@ -333,18 +316,16 @@ A specific ``backend`` may provide one or more of these interfaces. 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. - :return: A new instance of a - :class:`~cryptography.hazmat.primitives.asymmetric.dsa.DSAPrivateKey` - provider. + :return: A new instance of + :class:`~cryptography.hazmat.primitives.asymmetric.dsa.DSAPrivateKey`. :raises ValueError: This is raised if the key size is not supported by the backend. .. method:: dsa_hash_supported(algorithm) - :param algorithm: An instance of a - :class:`~cryptography.hazmat.primitives.hashes.HashAlgorithm` - provider. + :param algorithm: An instance of + :class:`~cryptography.hazmat.primitives.hashes.HashAlgorithm`. :returns: ``True`` if the specified ``algorithm`` is supported by this backend, otherwise ``False``. @@ -365,7 +346,7 @@ A specific ``backend`` may provide one or more of these interfaces. :param numbers: An instance of :class:`~cryptography.hazmat.primitives.asymmetric.dsa.DSAParameterNumbers`. - :returns: A provider of + :returns: An instance of :class:`~cryptography.hazmat.primitives.asymmetric.dsa.DSAParameters`. :raises cryptography.exceptions.UnsupportedAlgorithm: This is raised @@ -376,7 +357,7 @@ A specific ``backend`` may provide one or more of these interfaces. :param numbers: An instance of :class:`~cryptography.hazmat.primitives.asymmetric.dsa.DSAPrivateNumbers`. - :returns: A provider of + :returns: An instance of :class:`~cryptography.hazmat.primitives.asymmetric.dsa.DSAPrivateKey`. :raises cryptography.exceptions.UnsupportedAlgorithm: This is raised @@ -387,7 +368,7 @@ A specific ``backend`` may provide one or more of these interfaces. :param numbers: An instance of :class:`~cryptography.hazmat.primitives.asymmetric.dsa.DSAPublicNumbers`. - :returns: A provider of + :returns: An instance of :class:`~cryptography.hazmat.primitives.asymmetric.dsa.DSAPublicKey`. :raises cryptography.exceptions.UnsupportedAlgorithm: This is raised @@ -400,49 +381,51 @@ A specific ``backend`` may provide one or more of these interfaces. .. method:: elliptic_curve_supported(curve) - :param curve: An instance of a - :class:`~cryptography.hazmat.primitives.asymmetric.ec.EllipticCurve` - provider. + :param curve: An instance of + :class:`~cryptography.hazmat.primitives.asymmetric.ec.EllipticCurve`. :returns: True if the elliptic curve is supported by this backend. .. method:: elliptic_curve_signature_algorithm_supported(signature_algorithm, curve) - :param signature_algorithm: An instance of a - :class:`~cryptography.hazmat.primitives.asymmetric.ec.EllipticCurveSignatureAlgorithm` - provider. + :param signature_algorithm: An instance of + :class:`~cryptography.hazmat.primitives.asymmetric.ec.EllipticCurveSignatureAlgorithm`. - :param curve: An instance of a - :class:`~cryptography.hazmat.primitives.asymmetric.ec.EllipticCurve` - provider. + :param curve: An instance of + :class:`~cryptography.hazmat.primitives.asymmetric.ec.EllipticCurve`. :returns: True if the signature algorithm and curve are supported by this backend. .. method:: generate_elliptic_curve_private_key(curve) - :param curve: An instance of a - :class:`~cryptography.hazmat.primitives.asymmetric.ec.EllipticCurve` - provider. + :param curve: An instance of + :class:`~cryptography.hazmat.primitives.asymmetric.ec.EllipticCurve`. .. method:: load_elliptic_curve_private_numbers(numbers) - :param numbers: An instance of a - :class:`~cryptography.hazmat.primitives.asymmetric.ec.EllipticCurvePrivateNumbers` - provider. + :param numbers: An instance of + :class:`~cryptography.hazmat.primitives.asymmetric.ec.EllipticCurvePrivateNumbers`. - :returns: An instance of a - :class:`~cryptography.hazmat.primitives.asymmetric.ec.EllipticCurvePrivateKey` - provider. + :returns: An instance of + :class:`~cryptography.hazmat.primitives.asymmetric.ec.EllipticCurvePrivateKey`. .. method:: load_elliptic_curve_public_numbers(numbers) - :param numbers: An instance of a - :class:`~cryptography.hazmat.primitives.asymmetric.ec.EllipticCurvePublicNumbers` - provider. + :param numbers: An instance of + :class:`~cryptography.hazmat.primitives.asymmetric.ec.EllipticCurvePublicNumbers`. + + :returns: An instance of + :class:`~cryptography.hazmat.primitives.asymmetric.ec.EllipticCurvePublicKey`. + + .. method:: derive_elliptic_curve_private_key(private_value, curve) - :returns: An instance of a - :class:`~cryptography.hazmat.primitives.asymmetric.ec.EllipticCurvePublicKey` - provider. + :param private_value: A secret scalar value. + + :param curve: An instance of + :class:`~cryptography.hazmat.primitives.asymmetric.ec.EllipticCurve`. + + :returns: An instance of + :class:`~cryptography.hazmat.primitives.asymmetric.ec.EllipticCurvePrivateKey`. .. class:: PEMSerializationBackend @@ -468,6 +451,15 @@ A specific ``backend`` may provide one or more of these interfaces. serialized data contains. :raises ValueError: If the data could not be deserialized. + .. method:: load_pem_parameters(data) + + .. versionadded:: 2.0 + + :param bytes data: PEM data to load. + :return: A new instance of the appropriate type of asymmetric + parameters the serialized data contains. + :raises ValueError: If the data could not be deserialized. + .. class:: DERSerializationBackend .. versionadded:: 0.8 @@ -492,6 +484,16 @@ A specific ``backend`` may provide one or more of these interfaces. serialized data contains. :raises ValueError: If the data could not be deserialized. + .. method:: load_der_parameters(data) + + .. versionadded:: 2.0 + + :param bytes data: DER data to load. + :return: A new instance of the appropriate type of asymmetric + parameters the serialized data contains. + :raises ValueError: If the data could not be deserialized. + + .. class:: X509Backend .. versionadded:: 0.7 @@ -547,9 +549,64 @@ A specific ``backend`` may provide one or more of these interfaces. :class:`~cryptography.hazmat.primitives.hashes.HashAlgorithm` that will be used to generate the request signature. - :returns: A new object with the - :class:`~cryptography.x509.CertificateSigningRequest` interface. + :returns: A new instance of + :class:`~cryptography.x509.CertificateSigningRequest`. + + .. method:: create_x509_certificate(builder, private_key, algorithm) + + .. versionadded:: 1.0 + + :param builder: An instance of + :class:`~cryptography.x509.CertificateBuilder`. + + :param private_key: The + :class:`~cryptography.hazmat.primitives.asymmetric.rsa.RSAPrivateKey`, + :class:`~cryptography.hazmat.primitives.asymmetric.dsa.DSAPrivateKey` or + :class:`~cryptography.hazmat.primitives.asymmetric.ec.EllipticCurvePrivateKey` + that will be used to sign the certificate. + + :param algorithm: The + :class:`~cryptography.hazmat.primitives.hashes.HashAlgorithm` + that will be used to generate the certificate signature. + + :returns: A new instance of :class:`~cryptography.x509.Certificate`. + + .. method:: create_x509_crl(builder, private_key, algorithm) + .. versionadded:: 1.2 + + :param builder: An instance of + :class:`~cryptography.x509.CertificateRevocationListBuilder`. + + :param private_key: The + :class:`~cryptography.hazmat.primitives.asymmetric.rsa.RSAPrivateKey`, + :class:`~cryptography.hazmat.primitives.asymmetric.dsa.DSAPrivateKey` or + :class:`~cryptography.hazmat.primitives.asymmetric.ec.EllipticCurvePrivateKey` + that will be used to sign the CRL. + + :param algorithm: The + :class:`~cryptography.hazmat.primitives.hashes.HashAlgorithm` + that will be used to generate the CRL signature. + + :returns: A new instance of + :class:`~cryptography.x509.CertificateRevocationList`. + + .. method:: create_x509_revoked_certificate(builder) + + .. versionadded:: 1.2 + + :param builder: An instance of RevokedCertificateBuilder. + + :returns: A new instance of + :class:`~cryptography.x509.RevokedCertificate`. + + .. method:: x509_name_bytes(name) + + .. versionadded:: 1.6 + + :param name: An instance of :class:`~cryptography.x509.Name`. + + :return bytes: The DER encoded bytes. .. class:: DHBackend @@ -557,33 +614,33 @@ A specific ``backend`` may provide one or more of these interfaces. A backend with methods for doing Diffie-Hellman key exchange. - .. method:: generate_dh_parameters(key_size) + .. method:: generate_dh_parameters(generator, key_size) + + :param int generator: The generator to use. Often 2 or 5. :param int key_size: The bit length of the prime modulus to generate. - :return: A new instance of a - :class:`~cryptography.hazmat.primitives.asymmetric.dh.DHParameters` - provider. + :return: A new instance of + :class:`~cryptography.hazmat.primitives.asymmetric.dh.DHParameters`. :raises ValueError: If ``key_size`` is not at least 512. .. method:: generate_dh_private_key(parameters) - :param parameters: A - :class:`~cryptography.hazmat.primitives.asymmetric.dh.DHParameters` - provider. + :param parameters: An instance of + :class:`~cryptography.hazmat.primitives.asymmetric.dh.DHParameters`. - :return: A new instance of a - :class:`~cryptography.hazmat.primitives.asymmetric.dh.DHPrivateKey` - provider. + :return: A new instance of + :class:`~cryptography.hazmat.primitives.asymmetric.dh.DHPrivateKey`. - .. method:: generate_dh_private_key_and_parameters(self, key_size) + .. method:: generate_dh_private_key_and_parameters(generator, key_size) + + :param int generator: The generator to use. Often 2 or 5. :param int key_size: The bit length of the prime modulus to generate. - :return: A new instance of a - :class:`~cryptography.hazmat.primitives.asymmetric.dh.DHPrivateKey` - provider. + :return: A new instance of + :class:`~cryptography.hazmat.primitives.asymmetric.dh.DHPrivateKey`. :raises ValueError: If ``key_size`` is not at least 512. @@ -593,9 +650,8 @@ A specific ``backend`` may provide one or more of these interfaces. :class:`~cryptography.hazmat.primitives.asymmetric.dh.DHPrivateNumbers` instance. - :return: A new instance of a - :class:`~cryptography.hazmat.primitives.asymmetric.dh.DHPrivateKey` - provider. + :return: A new instance of + :class:`~cryptography.hazmat.primitives.asymmetric.dh.DHPrivateKey`. :raises cryptography.exceptions.UnsupportedAlgorithm: This is raised when any backend specific criteria are not met. @@ -606,9 +662,8 @@ A specific ``backend`` may provide one or more of these interfaces. :class:`~cryptography.hazmat.primitives.asymmetric.dh.DHPublicNumbers` instance. - :return: A new instance of a - :class:`~cryptography.hazmat.primitives.asymmetric.dh.DHPublicKey` - provider. + :return: A new instance of + :class:`~cryptography.hazmat.primitives.asymmetric.dh.DHPublicKey`. :raises cryptography.exceptions.UnsupportedAlgorithm: This is raised when any backend specific criteria are not met. @@ -619,18 +674,56 @@ A specific ``backend`` may provide one or more of these interfaces. :class:`~cryptography.hazmat.primitives.asymmetric.dh.DHParameterNumbers` instance. - :return: A new instance of a - :class:`~cryptography.hazmat.primitives.asymmetric.dh.DHParameters` - provider. + :return: A new instance of + :class:`~cryptography.hazmat.primitives.asymmetric.dh.DHParameters`. :raises cryptography.exceptions.UnsupportedAlgorithm: This is raised when any backend specific criteria are not met. - .. method:: dh_parameters_supported(p, g) + .. method:: dh_parameters_supported(p, g, q=None) :param int p: The p value of the DH key. :param int g: The g value of the DH key. - :returns: ``True`` if the given values of ``p`` and ``g`` are supported - by this backend, otherwise ``False``. + :param int q: 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``. + + .. versionadded:: 1.8 + + .. method:: dh_x942_serialization_supported() + + :returns: True if serialization of DH objects with + subgroup order (q) is supported by this backend. + + +.. class:: ScryptBackend + + .. versionadded:: 1.6 + + A backend with methods for using Scrypt. + + The following backends implement this interface: + + * :doc:`/hazmat/backends/openssl` + + .. method:: derive_scrypt(self, key_material, salt, length, n, r, p) + + :param bytes key_material: The key material to use as a basis for + the derived key. This is typically a password. + + :param bytes salt: A salt. + + :param int length: The desired length of the derived key. + + :param int n: CPU/Memory cost parameter. It must be larger than 1 and be a + power of 2. + + :param int r: Block size parameter. + + :param int p: Parallelization parameter. + + :return bytes: Derived key. + diff --git a/docs/hazmat/backends/multibackend.rst b/docs/hazmat/backends/multibackend.rst deleted file mode 100644 index 0aae04a7..00000000 --- a/docs/hazmat/backends/multibackend.rst +++ /dev/null @@ -1,45 +0,0 @@ -.. hazmat:: - -MultiBackend -============ - -.. currentmodule:: cryptography.hazmat.backends.multibackend - -.. class:: MultiBackend(backends) - - .. versionadded:: 0.2 - - This class allows you to combine multiple backends into a single backend - that offers the combined features of all of its constituents. - - .. testsetup:: - - from cryptography import utils - from cryptography.exceptions import UnsupportedAlgorithm, _Reasons - from cryptography.hazmat.backends.interfaces import HashBackend - from cryptography.hazmat.backends.openssl.backend import backend as backend2 - - @utils.register_interface(HashBackend) - class DummyHashBackend(object): - def hash_supported(self, algorithm): - return False - - def create_hash_ctx(self, algorithm): - raise UnsupportedAlgorithm("", _Reasons.UNSUPPORTED_HASH) - - backend1 = DummyHashBackend() - - .. doctest:: - - >>> from cryptography.hazmat.backends.multibackend import MultiBackend - >>> from cryptography.hazmat.primitives import hashes - >>> backend1.hash_supported(hashes.SHA256()) - False - >>> backend2.hash_supported(hashes.SHA256()) - True - >>> multi_backend = MultiBackend([backend1, backend2]) - >>> multi_backend.hash_supported(hashes.SHA256()) - True - - :param backends: A ``list`` of backend objects. Backends are checked for - feature support in the order they appear in this list. diff --git a/docs/hazmat/backends/openssl.rst b/docs/hazmat/backends/openssl.rst index 03ac5570..56121cb5 100644 --- a/docs/hazmat/backends/openssl.rst +++ b/docs/hazmat/backends/openssl.rst @@ -3,9 +3,8 @@ OpenSSL backend =============== -The `OpenSSL`_ C library. Cryptography supports version ``0.9.8e`` (present in -Red Hat Enterprise Linux 5) and greater. Earlier versions may work but are -**not tested or supported**. +The `OpenSSL`_ C library. Cryptography supports OpenSSL version 1.0.2 and +greater. .. data:: cryptography.hazmat.backends.openssl.backend @@ -16,6 +15,7 @@ Red Hat Enterprise Linux 5) and greater. Earlier versions may work but are * :class:`~cryptography.hazmat.backends.interfaces.CipherBackend` * :class:`~cryptography.hazmat.backends.interfaces.CMACBackend` * :class:`~cryptography.hazmat.backends.interfaces.DERSerializationBackend` + * :class:`~cryptography.hazmat.backends.interfaces.DHBackend` * :class:`~cryptography.hazmat.backends.interfaces.DSABackend` * :class:`~cryptography.hazmat.backends.interfaces.EllipticCurveBackend` * :class:`~cryptography.hazmat.backends.interfaces.HashBackend` @@ -25,17 +25,42 @@ Red Hat Enterprise Linux 5) and greater. Earlier versions may work but are * :class:`~cryptography.hazmat.backends.interfaces.PEMSerializationBackend` * :class:`~cryptography.hazmat.backends.interfaces.X509Backend` + It also implements the following interface for OpenSSL versions ``1.1.0`` + and above. + + * :class:`~cryptography.hazmat.backends.interfaces.ScryptBackend` + It also exposes the following: .. attribute:: name The string name of this backend: ``"openssl"`` + .. method:: openssl_version_text() + + :return text: The friendly string name of the loaded OpenSSL library. + This is not necessarily the same version as it was compiled against. + + .. method:: openssl_version_number() + + .. versionadded:: 1.8 + + :return int: The integer version of the loaded OpenSSL library. This is + defined in ``opensslv.h`` as ``OPENSSL_VERSION_NUMBER`` and is + typically shown in hexadecimal (e.g. ``0x1010003f``). This is + not necessarily the same version as it was compiled against. + .. method:: activate_osrandom_engine() Activates the OS random engine. This will effectively disable OpenSSL's default CSPRNG. + .. method:: osrandom_engine_implementation() + + .. versionadded:: 1.7 + + Returns the implementation of OS random engine. + .. method:: activate_builtin_random() This will activate the default OpenSSL CSPRNG. @@ -43,7 +68,7 @@ Red Hat Enterprise Linux 5) and greater. Earlier versions may work but are OS random engine ---------------- -OpenSSL uses a user-space CSPRNG that is seeded from system random ( +By default OpenSSL uses a user-space CSPRNG that is seeded from system random ( ``/dev/urandom`` or ``CryptGenRandom``). This CSPRNG is not reseeded automatically when a process calls ``fork()``. This can result in situations where two different processes can return similar or identical keys and @@ -67,8 +92,9 @@ When importing only the binding it is added to the engine list but OS random sources ----------------- -On OS X and FreeBSD ``/dev/urandom`` is an alias for ``/dev/random`` and -utilizes the `Yarrow`_ algorithm. +On macOS and FreeBSD ``/dev/urandom`` is an alias for ``/dev/random``. The +implementation on macOS uses the `Yarrow`_ algorithm. FreeBSD uses the +`Fortuna`_ algorithm. On Windows the implementation of ``CryptGenRandom`` depends on which version of the operation system you are using. See the `Microsoft documentation`_ for more @@ -77,8 +103,24 @@ details. Linux uses its own PRNG design. ``/dev/urandom`` is a non-blocking source seeded from the same pool as ``/dev/random``. ++------------------------------------------+------------------------------+ +| Windows | ``CryptGenRandom()`` | ++------------------------------------------+------------------------------+ +| Linux >= 3.17 with working | ``getrandom()`` | +| ``SYS_getrandom`` syscall | | ++------------------------------------------+------------------------------+ +| OpenBSD >= 5.6 | ``getentropy()`` | ++------------------------------------------+------------------------------+ +| BSD family (including macOS 10.12+) with | ``getentropy()`` | +| ``SYS_getentropy`` in ``sys/syscall.h`` | | ++------------------------------------------+------------------------------+ +| fallback | ``/dev/urandom`` with | +| | cached file descriptor | ++------------------------------------------+------------------------------+ + .. _`OpenSSL`: https://www.openssl.org/ .. _`initializing the RNG`: https://en.wikipedia.org/wiki/OpenSSL#Predictable_private_keys_.28Debian-specific.29 +.. _`Fortuna`: https://en.wikipedia.org/wiki/Fortuna_(PRNG) .. _`Yarrow`: https://en.wikipedia.org/wiki/Yarrow_algorithm -.. _`Microsoft documentation`: https://msdn.microsoft.com/en-us/library/windows/desktop/aa379942(v=vs.85).aspx +.. _`Microsoft documentation`: https://docs.microsoft.com/en-us/windows/desktop/api/wincrypt/nf-wincrypt-cryptgenrandom |