From 601278a17617e5aa631d6395320340f4df3641b2 Mon Sep 17 00:00:00 2001 From: Paul Kehrer Date: Thu, 12 Feb 2015 12:51:00 -0600 Subject: move hash interfaces --- docs/hazmat/backends/interfaces.rst | 22 +++++----- docs/hazmat/primitives/asymmetric/dsa.rst | 4 +- docs/hazmat/primitives/asymmetric/ec.rst | 4 +- docs/hazmat/primitives/asymmetric/rsa.rst | 6 +-- docs/hazmat/primitives/cryptographic-hashes.rst | 50 ++++++++++++++++++++-- docs/hazmat/primitives/interfaces.rst | 46 -------------------- .../hazmat/primitives/key-derivation-functions.rst | 6 +-- docs/hazmat/primitives/mac/hmac.rst | 6 +-- docs/x509.rst | 2 +- 9 files changed, 72 insertions(+), 74 deletions(-) (limited to 'docs') diff --git a/docs/hazmat/backends/interfaces.rst b/docs/hazmat/backends/interfaces.rst index b828fa73..15d8b980 100644 --- a/docs/hazmat/backends/interfaces.rst +++ b/docs/hazmat/backends/interfaces.rst @@ -91,7 +91,7 @@ A specific ``backend`` may provide one or more of these interfaces. Check if the specified ``algorithm`` is supported by this backend. :param algorithm: An instance of a - :class:`~cryptography.hazmat.primitives.interfaces.HashAlgorithm` + :class:`~cryptography.hazmat.primitives.hashes.HashAlgorithm` provider. :returns: ``True`` if the specified ``algorithm`` is supported by this @@ -101,15 +101,15 @@ A specific ``backend`` may provide one or more of these interfaces. .. method:: create_hash_ctx(algorithm) Create a - :class:`~cryptography.hazmat.primitives.interfaces.HashContext` that + :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.interfaces.HashAlgorithm` + :class:`~cryptography.hazmat.primitives.hashes.HashAlgorithm` provider. :returns: - :class:`~cryptography.hazmat.primitives.interfaces.HashContext` + :class:`~cryptography.hazmat.primitives.hashes.HashContext` .. class:: HMACBackend @@ -127,7 +127,7 @@ A specific ``backend`` may provide one or more of these interfaces. Check if the specified ``algorithm`` is supported by this backend. :param algorithm: An instance of a - :class:`~cryptography.hazmat.primitives.interfaces.HashAlgorithm` + :class:`~cryptography.hazmat.primitives.hashes.HashAlgorithm` provider. :returns: ``True`` if the specified ``algorithm`` is supported for HMAC @@ -136,16 +136,16 @@ A specific ``backend`` may provide one or more of these interfaces. .. method:: create_hmac_ctx(algorithm) Create a - :class:`~cryptography.hazmat.primitives.interfaces.HashContext` that + :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.interfaces.HashAlgorithm` + :class:`~cryptography.hazmat.primitives.hashes.HashAlgorithm` provider. :returns: - :class:`~cryptography.hazmat.primitives.interfaces.HashContext` + :class:`~cryptography.hazmat.primitives.hashes.HashContext` .. class:: CMACBackend @@ -191,7 +191,7 @@ A specific ``backend`` may provide one or more of these interfaces. Check if the specified ``algorithm`` is supported by this backend. :param algorithm: An instance of a - :class:`~cryptography.hazmat.primitives.interfaces.HashAlgorithm` + :class:`~cryptography.hazmat.primitives.hashes.HashAlgorithm` provider. :returns: ``True`` if the specified ``algorithm`` is supported for @@ -200,7 +200,7 @@ A specific ``backend`` may provide one or more of these interfaces. .. method:: derive_pbkdf2_hmac(self, algorithm, length, salt, iterations, key_material) :param algorithm: An instance of a - :class:`~cryptography.hazmat.primitives.interfaces.HashAlgorithm` + :class:`~cryptography.hazmat.primitives.hashes.HashAlgorithm` provider. :param int length: The desired length of the derived key. Maximum is @@ -343,7 +343,7 @@ A specific ``backend`` may provide one or more of these interfaces. .. method:: dsa_hash_supported(algorithm) :param algorithm: An instance of a - :class:`~cryptography.hazmat.primitives.interfaces.HashAlgorithm` + :class:`~cryptography.hazmat.primitives.hashes.HashAlgorithm` provider. :returns: ``True`` if the specified ``algorithm`` is supported by this diff --git a/docs/hazmat/primitives/asymmetric/dsa.rst b/docs/hazmat/primitives/asymmetric/dsa.rst index 59c0d973..36bc801f 100644 --- a/docs/hazmat/primitives/asymmetric/dsa.rst +++ b/docs/hazmat/primitives/asymmetric/dsa.rst @@ -267,7 +267,7 @@ Key interfaces :rfc:`6979`. :param algorithm: An instance of a - :class:`~cryptography.hazmat.primitives.interfaces.HashAlgorithm` + :class:`~cryptography.hazmat.primitives.hashes.HashAlgorithm` provider. :param backend: A @@ -330,7 +330,7 @@ Key interfaces specified in :rfc:`6979`. :param algorithm: An instance of a - :class:`~cryptography.hazmat.primitives.interfaces.HashAlgorithm` + :class:`~cryptography.hazmat.primitives.hashes.HashAlgorithm` provider. :param backend: A diff --git a/docs/hazmat/primitives/asymmetric/ec.rst b/docs/hazmat/primitives/asymmetric/ec.rst index caa3f285..5b114710 100644 --- a/docs/hazmat/primitives/asymmetric/ec.rst +++ b/docs/hazmat/primitives/asymmetric/ec.rst @@ -32,7 +32,7 @@ Elliptic Curve Signature Algorithms `FIPS 186-3`_, and later in `FIPS 186-4`_. :param algorithm: An instance of a - :class:`~cryptography.hazmat.primitives.interfaces.HashAlgorithm` + :class:`~cryptography.hazmat.primitives.hashes.HashAlgorithm` provider. .. doctest:: @@ -282,7 +282,7 @@ Key Interfaces .. attribute:: algorithm - :type: :class:`~cryptography.hazmat.primitives.interfaces.HashAlgorithm` + :type: :class:`~cryptography.hazmat.primitives.hashes.HashAlgorithm` The digest algorithm to be used with the signature scheme. diff --git a/docs/hazmat/primitives/asymmetric/rsa.rst b/docs/hazmat/primitives/asymmetric/rsa.rst index e516f749..4855a45c 100644 --- a/docs/hazmat/primitives/asymmetric/rsa.rst +++ b/docs/hazmat/primitives/asymmetric/rsa.rst @@ -252,7 +252,7 @@ Mask generation functions in :class:`PSS` padding. It takes a hash algorithm and a salt length. :param algorithm: An instance of a - :class:`~cryptography.hazmat.primitives.interfaces.HashAlgorithm` + :class:`~cryptography.hazmat.primitives.hashes.HashAlgorithm` provider. Numbers @@ -429,7 +429,7 @@ Key interfaces provider. :param algorithm: An instance of a - :class:`~cryptography.hazmat.primitives.interfaces.HashAlgorithm` + :class:`~cryptography.hazmat.primitives.hashes.HashAlgorithm` provider. :returns: @@ -499,7 +499,7 @@ Key interfaces provider. :param algorithm: An instance of a - :class:`~cryptography.hazmat.primitives.interfaces.HashAlgorithm` + :class:`~cryptography.hazmat.primitives.hashes.HashAlgorithm` provider. :returns: diff --git a/docs/hazmat/primitives/cryptographic-hashes.rst b/docs/hazmat/primitives/cryptographic-hashes.rst index c8b56eb9..49288326 100644 --- a/docs/hazmat/primitives/cryptographic-hashes.rst +++ b/docs/hazmat/primitives/cryptographic-hashes.rst @@ -12,9 +12,9 @@ Message digests results (with a high probability) in different digests. This is an implementation of - :class:`~cryptography.hazmat.primitives.interfaces.HashContext` meant to + :class:`~cryptography.hazmat.primitives.hashes.HashContext` meant to be used with - :class:`~cryptography.hazmat.primitives.interfaces.HashAlgorithm` + :class:`~cryptography.hazmat.primitives.hashes.HashAlgorithm` implementations to provide an incremental interface to calculating various message digests. @@ -39,7 +39,7 @@ Message digests `Lifetimes of cryptographic hash functions`_. :param algorithm: A - :class:`~cryptography.hazmat.primitives.interfaces.HashAlgorithm` + :class:`~cryptography.hazmat.primitives.hashes.HashAlgorithm` provider such as those described in :ref:`below `. :param backend: A @@ -146,4 +146,48 @@ MD5 message digest and has practical known collision attacks. +Interfaces +~~~~~~~~~~ + +.. class:: HashAlgorithm + + .. attribute:: name + + :type: str + + The standard name for the hash algorithm, for example: ``"sha256"`` or + ``"whirlpool"``. + + .. attribute:: digest_size + + :type: int + + The size of the resulting digest in bytes. + + .. attribute:: block_size + + :type: int + + The internal block size of the hash algorithm in bytes. + + +.. class:: HashContext + + .. attribute:: algorithm + + A :class:`HashAlgorithm` that will be used by this context. + + .. method:: update(data) + + :param bytes data: The data you want to hash. + + .. method:: finalize() + + :return: The final digest as bytes. + + .. method:: copy() + + :return: A :class:`HashContext` that is a copy of the current context. + + .. _`Lifetimes of cryptographic hash functions`: http://valerieaurora.org/hash.html diff --git a/docs/hazmat/primitives/interfaces.rst b/docs/hazmat/primitives/interfaces.rst index cd21ea1a..86a3a7e4 100644 --- a/docs/hazmat/primitives/interfaces.rst +++ b/docs/hazmat/primitives/interfaces.rst @@ -160,52 +160,6 @@ In 0.8 the EC key interfaces were moved to the :mod:`cryptography.hazmat.primitives.asymmetric.ec` module. -Hash algorithms ---------------- - -.. class:: HashAlgorithm - - .. attribute:: name - - :type: str - - The standard name for the hash algorithm, for example: ``"sha256"`` or - ``"whirlpool"``. - - .. attribute:: digest_size - - :type: int - - The size of the resulting digest in bytes. - - .. attribute:: block_size - - :type: int - - The internal block size of the hash algorithm in bytes. - - -.. class:: HashContext - - .. attribute:: algorithm - - A :class:`~cryptography.hazmat.primitives.interfaces.HashAlgorithm` that - will be used by this context. - - .. method:: update(data) - - :param bytes data: The data you want to hash. - - .. method:: finalize() - - :return: The final digest as bytes. - - .. method:: copy() - - :return: A :class:`~cryptography.hazmat.primitives.interfaces.HashContext` - that is a copy of the current context. - - Key derivation functions ------------------------ diff --git a/docs/hazmat/primitives/key-derivation-functions.rst b/docs/hazmat/primitives/key-derivation-functions.rst index 60096870..4a47159f 100644 --- a/docs/hazmat/primitives/key-derivation-functions.rst +++ b/docs/hazmat/primitives/key-derivation-functions.rst @@ -69,7 +69,7 @@ Different KDFs are suitable for different tasks such as: >>> kdf.verify(b"my great password", key) :param algorithm: An instance of a - :class:`~cryptography.hazmat.primitives.interfaces.HashAlgorithm` + :class:`~cryptography.hazmat.primitives.hashes.HashAlgorithm` provider. :param int length: The desired length of the derived key. Maximum is (2\ :sup:`32` - 1) * ``algorithm.digest_size``. @@ -169,7 +169,7 @@ Different KDFs are suitable for different tasks such as: >>> hkdf.verify(b"input key", key) :param algorithm: An instance of a - :class:`~cryptography.hazmat.primitives.interfaces.HashAlgorithm` + :class:`~cryptography.hazmat.primitives.hashes.HashAlgorithm` provider. :param int length: The desired length of the derived key. Maximum is @@ -270,7 +270,7 @@ Different KDFs are suitable for different tasks such as: >>> hkdf.verify(key_material, key) :param algorithm: An instance of a - :class:`~cryptography.hazmat.primitives.interfaces.HashAlgorithm` + :class:`~cryptography.hazmat.primitives.hashes.HashAlgorithm` provider. :param int length: The desired length of the derived key. Maximum is diff --git a/docs/hazmat/primitives/mac/hmac.rst b/docs/hazmat/primitives/mac/hmac.rst index ce566c5c..2515ac91 100644 --- a/docs/hazmat/primitives/mac/hmac.rst +++ b/docs/hazmat/primitives/mac/hmac.rst @@ -18,7 +18,7 @@ of a message. .. class:: HMAC(key, algorithm, backend) HMAC objects take a ``key`` and a - :class:`~cryptography.hazmat.primitives.interfaces.HashAlgorithm` provider. + :class:`~cryptography.hazmat.primitives.hashes.HashAlgorithm` provider. The ``key`` should be :doc:`randomly generated bytes ` and is recommended to be equal in length to the ``digest_size`` of the hash function chosen. You must keep the ``key`` secret. @@ -39,7 +39,7 @@ of a message. raised. If ``algorithm`` isn't a - :class:`~cryptography.hazmat.primitives.interfaces.HashAlgorithm` provider + :class:`~cryptography.hazmat.primitives.hashes.HashAlgorithm` provider then ``TypeError`` will be raised. To check that a given signature is correct use the :meth:`verify` method. @@ -56,7 +56,7 @@ of a message. :param bytes key: Secret key as ``bytes``. :param algorithm: An - :class:`~cryptography.hazmat.primitives.interfaces.HashAlgorithm` + :class:`~cryptography.hazmat.primitives.hashes.HashAlgorithm` provider such as those described in :ref:`Cryptographic Hashes `. :param backend: An diff --git a/docs/x509.rst b/docs/x509.rst index 9bd9bd59..587fd884 100644 --- a/docs/x509.rst +++ b/docs/x509.rst @@ -103,7 +103,7 @@ X.509 Certificate Object .. method:: fingerprint(algorithm) :param algorithm: The - :class:`~cryptography.hazmat.primitives.interfaces.HashAlgorithm` + :class:`~cryptography.hazmat.primitives.hashes.HashAlgorithm` that will be used to generate the fingerprint. :return bytes: The fingerprint using the supplied hash algorithm as -- cgit v1.2.3