diff options
Diffstat (limited to 'docs/hazmat/primitives/cryptographic-hashes.rst')
| -rw-r--r-- | docs/hazmat/primitives/cryptographic-hashes.rst | 168 |
1 files changed, 132 insertions, 36 deletions
diff --git a/docs/hazmat/primitives/cryptographic-hashes.rst b/docs/hazmat/primitives/cryptographic-hashes.rst index 49288326..24cc70b5 100644 --- a/docs/hazmat/primitives/cryptographic-hashes.rst +++ b/docs/hazmat/primitives/cryptographic-hashes.rst @@ -1,7 +1,7 @@ .. hazmat:: -Message digests -=============== +Message digests (Hashing) +========================= .. module:: cryptography.hazmat.primitives.hashes @@ -26,7 +26,7 @@ Message digests >>> digest.update(b"abc") >>> digest.update(b"123") >>> digest.finalize() - 'l\xa1=R\xcap\xc8\x83\xe0\xf0\xbb\x10\x1eBZ\x89\xe8bM\xe5\x1d\xb2\xd29%\x93\xafj\x84\x11\x80\x90' + b'l\xa1=R\xcap\xc8\x83\xe0\xf0\xbb\x10\x1eBZ\x89\xe8bM\xe5\x1d\xb2\xd29%\x93\xafj\x84\x11\x80\x90' If the backend doesn't support the requested ``algorithm`` an :class:`~cryptography.exceptions.UnsupportedAlgorithm` exception will be @@ -40,11 +40,11 @@ Message digests :param algorithm: A :class:`~cryptography.hazmat.primitives.hashes.HashAlgorithm` - provider such as those described in + instance such as those described in :ref:`below <cryptographic-hash-algorithms>`. :param backend: A :class:`~cryptography.hazmat.backends.interfaces.HashBackend` - provider. + instance. :raises cryptography.exceptions.UnsupportedAlgorithm: This is raised if the provided ``backend`` does not implement @@ -79,19 +79,6 @@ Message digests .. _cryptographic-hash-algorithms: -SHA-1 -~~~~~ - -.. attention:: - - NIST has deprecated SHA-1 in favor of the SHA-2 variants. New applications - are strongly suggested to use SHA-2 over SHA-1. - -.. class:: SHA1() - - SHA-1 is a cryptographic hash function standardized by NIST. It produces an - 160-bit message digest. - SHA-2 family ~~~~~~~~~~~~ @@ -115,21 +102,134 @@ SHA-2 family SHA-512 is a cryptographic hash function from the SHA-2 family and is standardized by NIST. It produces a 512-bit message digest. -RIPEMD160 -~~~~~~~~~ +.. class:: SHA512_224() + + .. versionadded:: 2.5 + + SHA-512/224 is a cryptographic hash function from the SHA-2 family and is + standardized by NIST. It produces a 224-bit message digest. + +.. class:: SHA512_256() + + .. versionadded:: 2.5 + + SHA-512/256 is a cryptographic hash function from the SHA-2 family and is + standardized by NIST. It produces a 256-bit message digest. + +BLAKE2 +~~~~~~ + +`BLAKE2`_ is a cryptographic hash function specified in :rfc:`7693`. BLAKE2's +design makes it immune to `length-extension attacks`_, an advantage over the +SHA-family of hashes. + +.. note:: + + While the RFC specifies keying, personalization, and salting features, + these are not supported at this time due to limitations in OpenSSL 1.1.0. + +.. class:: BLAKE2b(digest_size) + + BLAKE2b is optimized for 64-bit platforms and produces an 1 to 64-byte + message digest. + + :param int digest_size: The desired size of the hash output in bytes. Only + ``64`` is supported at this time. + + :raises ValueError: If the ``digest_size`` is invalid. + +.. class:: BLAKE2s(digest_size) + + BLAKE2s is optimized for 8 to 32-bit platforms and produces a + 1 to 32-byte message digest. + + :param int digest_size: The desired size of the hash output in bytes. Only + ``32`` is supported at this time. + + :raises ValueError: If the ``digest_size`` is invalid. + +SHA-3 family +~~~~~~~~~~~~ + +SHA-3 is the most recent NIST secure hash algorithm standard. Despite the +larger number SHA-3 is not considered to be better than SHA-2. Instead, it uses +a significantly different internal structure so that **if** an attack appears +against SHA-2 it is unlikely to apply to SHA-3. SHA-3 is significantly slower +than SHA-2 so at this time most users should choose SHA-2. + +.. class:: SHA3_224() + + .. versionadded:: 2.5 + + SHA3/224 is a cryptographic hash function from the SHA-3 family and is + standardized by NIST. It produces a 224-bit message digest. + +.. class:: SHA3_256() + + .. versionadded:: 2.5 + + SHA3/256 is a cryptographic hash function from the SHA-3 family and is + standardized by NIST. It produces a 256-bit message digest. + +.. class:: SHA3_384() + + .. versionadded:: 2.5 + + SHA3/384 is a cryptographic hash function from the SHA-3 family and is + standardized by NIST. It produces a 384-bit message digest. + +.. class:: SHA3_512() + + .. versionadded:: 2.5 + + SHA3/512 is a cryptographic hash function from the SHA-3 family and is + standardized by NIST. It produces a 512-bit message digest. + +.. class:: SHAKE128(digest_size) + + .. versionadded:: 2.5 + + SHAKE128 is an extendable output function (XOF) based on the same core + permutations as SHA3. It allows the caller to obtain an arbitrarily long + digest length. Longer lengths, however, do not increase security or + collision resistance and lengths shorter than 128 bit (16 bytes) will + decrease it. + + :param int digest_size: The length of output desired. Must be greater than + zero. -.. class:: RIPEMD160() + :raises ValueError: If the ``digest_size`` is invalid. - RIPEMD160 is a cryptographic hash function that is part of ISO/IEC - 10118-3:2004. It produces a 160-bit message digest. +.. class:: SHAKE256(digest_size) -Whirlpool -~~~~~~~~~ + .. versionadded:: 2.5 -.. class:: Whirlpool() + SHAKE256 is an extendable output function (XOF) based on the same core + permutations as SHA3. It allows the caller to obtain an arbitrarily long + digest length. Longer lengths, however, do not increase security or + collision resistance and lengths shorter than 256 bit (32 bytes) will + decrease it. - Whirlpool is a cryptographic hash function that is part of ISO/IEC - 10118-3:2004. It produces a 512-bit message digest. + :param int digest_size: The length of output desired. Must be greater than + zero. + + :raises ValueError: If the ``digest_size`` is invalid. + +SHA-1 +~~~~~ + +.. warning:: + + SHA-1 is a deprecated hash algorithm that has practical known collision + attacks. You are strongly discouraged from using it. Existing applications + should strongly consider moving away. + +.. class:: SHA1() + + SHA-1 is a cryptographic hash function standardized by NIST. It produces an + 160-bit message digest. Cryptanalysis of SHA-1 has demonstrated that it is + vulnerable to practical collision attacks, and collisions have been + demonstrated. MD5 ~~~ @@ -156,7 +256,7 @@ Interfaces :type: str The standard name for the hash algorithm, for example: ``"sha256"`` or - ``"whirlpool"``. + ``"blake2b"``. .. attribute:: digest_size @@ -164,12 +264,6 @@ Interfaces 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 @@ -190,4 +284,6 @@ Interfaces :return: A :class:`HashContext` that is a copy of the current context. -.. _`Lifetimes of cryptographic hash functions`: http://valerieaurora.org/hash.html +.. _`Lifetimes of cryptographic hash functions`: https://valerieaurora.org/hash.html +.. _`BLAKE2`: https://blake2.net +.. _`length-extension attacks`: https://en.wikipedia.org/wiki/Length_extension_attack |