:mod:`hashlib` --- Secure hashes and message digests

.. module:: hashlib
 :synopsis: Secure hash and message digest algorithms.

.. moduleauthor:: Gregory P. Smith <greg@krypto.org>

.. sectionauthor:: Gregory P. Smith <greg@krypto.org>

Source code: :source:`Lib/hashlib.py`

.. index::
 single: message digest, MD5
 single: secure hash algorithm, SHA1, SHA224, SHA256, SHA384, SHA512

.. testsetup::

 import hashlib

This module implements a common interface to many different secure hash and message digest algorithms. Included are the FIPS secure hash algorithms SHA1, SHA224, SHA256, SHA384, and SHA512 (defined in FIPS 180-2) as well as RSA's MD5 algorithm (defined in Internet

Hash algorithms

There is one constructor method named for each type of :dfn:`hash`. All return a hash object with the same simple interface. For example: use :func:`sha256` to create a SHA-256 hash object. You can now feed this object with :term:`bytes-like objects <bytes-like object>` (normally :class:`bytes`) using the :meth:`update` method. At any point you can ask it for the :dfn:`digest` of the concatenation of the data fed to it so far using the :meth:`digest` or :meth:`hexdigest` methods.

.. index:: single: OpenSSL; (use in module hashlib)

Constructors for hash algorithms that are always present in this module are :func:`sha1`, :func:`sha224`, :func:`sha256`, :func:`sha384`, :func:`sha512`, :func:`blake2b`, and :func:`blake2s`. :func:`md5` is normally available as well, though it may be missing if you are using a rare "FIPS compliant" build of Python. Additional algorithms may also be available depending upon the OpenSSL library that Python uses on your platform. On most platforms the :func:`sha3_224`, :func:`sha3_256`, :func:`sha3_384`, :func:`sha3_512`, :func:`shake_128`, :func:`shake_256` are also available.

.. versionadded:: 3.6
 SHA3 (Keccak) and SHAKE constructors :func:`sha3_224`, :func:`sha3_256`,
 :func:`sha3_384`, :func:`sha3_512`, :func:`shake_128`, :func:`shake_256`.

.. versionadded:: 3.6
 :func:`blake2b` and :func:`blake2s` were added.

For example, to obtain the digest of the byte string b'Nobody inspects the spammish repetition':

>>> import hashlib
>>> m = hashlib.sha256()
>>> m.update(b"Nobody inspects")
>>> m.update(b" the spammish repetition")
>>> m.digest()
b'\x03\x1e\xdd}Ae\x15\x93\xc5\xfe\\\x00o\xa5u+7\xfd\xdf\xf7\xbcN\x84:\xa6\xaf\x0c\x95\x0fK\x94\x06'
>>> m.digest_size
32
>>> m.block_size
64

More condensed:

>>> hashlib.sha224(b"Nobody inspects the spammish repetition").hexdigest()
'a4337bc45a8fc544c03f52dc550cd6e1e87021bc896588bd79e901e2'

.. function:: new(name[, data])

 Is a generic constructor that takes the string *name* of the desired
 algorithm as its first parameter. It also exists to allow access to the
 above listed hashes as well as any other algorithms that your OpenSSL
 library may offer. The named constructors are much faster than :func:`new`
 and should be preferred.

Using :func:`new` with an algorithm provided by OpenSSL:

>>> h = hashlib.new('ripemd160')
>>> h.update(b"Nobody inspects the spammish repetition")
>>> h.hexdigest()
'cc4a5ce1b3df48aec5d22d1f16b894a0b894eccc'

Hashlib provides the following constant attributes:

.. data:: algorithms_guaranteed

 A set containing the names of the hash algorithms guaranteed to be supported
 by this module on all platforms. Note that 'md5' is in this list despite
 some upstream vendors offering an odd "FIPS compliant" Python build that
 excludes it.

 .. versionadded:: 3.2

.. data:: algorithms_available

 A set containing the names of the hash algorithms that are available in the
 running Python interpreter. These names will be recognized when passed to
 :func:`new`. :attr:`algorithms_guaranteed` will always be a subset. The
 same algorithm may appear multiple times in this set under different names
 (thanks to OpenSSL).

 .. versionadded:: 3.2

The following values are provided as constant attributes of the hash objects returned by the constructors:

.. data:: hash.digest_size

 The size of the resulting hash in bytes.

.. data:: hash.block_size

 The internal block size of the hash algorithm in bytes.

A hash object has the following attributes:

.. attribute:: hash.name

 The canonical name of this hash, always lowercase and always suitable as a
 parameter to :func:`new` to create another hash of this type.

 .. versionchanged:: 3.4
 The name attribute has been present in CPython since its inception, but
 until Python 3.4 was not formally specified, so may not exist on some
 platforms.

A hash object has the following methods:

.. method:: hash.update(data)

 Update the hash object with the :term:`bytes-like object`.
 Repeated calls are equivalent to a single call with the
 concatenation of all the arguments: ``m.update(a); m.update(b)`` is
 equivalent to ``m.update(a+b)``.

 .. versionchanged:: 3.1
 The Python GIL is released to allow other threads to run while hash
 updates on data larger than 2047 bytes is taking place when using hash
 algorithms supplied by OpenSSL.

.. method:: hash.digest()

 Return the digest of the data passed to the :meth:`update` method so far.
 This is a bytes object of size :attr:`digest_size` which may contain bytes in
 the whole range from 0 to 255.

.. method:: hash.hexdigest()

 Like :meth:`digest` except the digest is returned as a string object of
 double length, containing only hexadecimal digits. This may be used to
 exchange the value safely in email or other non-binary environments.

.. method:: hash.copy()

 Return a copy ("clone") of the hash object. This can be used to efficiently
 compute the digests of data sharing a common initial substring.

SHAKE variable length digests

The :func:`shake_128` and :func:`shake_256` algorithms provide variable length digests with length_in_bits//2 up to 128 or 256 bits of security. As such, their digest methods require a length. Maximum length is not limited by the SHAKE algorithm.

.. method:: shake.digest(length)

 Return the digest of the data passed to the :meth:`update` method so far.
 This is a bytes object of size *length* which may contain bytes in
 the whole range from 0 to 255.

.. method:: shake.hexdigest(length)

 Like :meth:`digest` except the digest is returned as a string object of
 double length, containing only hexadecimal digits. This may be used to
 exchange the value safely in email or other non-binary environments.

Key derivation

Key derivation and key stretching algorithms are designed for secure password hashing. Naive algorithms such as sha1(password) are not resistant against brute-force attacks. A good password hashing function must be tunable, slow, and include a BLAKE2

.. sectionauthor:: Dmitry Chestnykh

.. index::
 single: blake2b, blake2s

RFC 7693 that comes in two flavors:

• BLAKE2b, optimized for 64-bit platforms and produces digests of any size between 1 and 64 bytes,
• BLAKE2s, optimized for 8- to 32-bit platforms and produces digests of any size between 1 and 32 bytes.

BLAKE2 supports keyed mode (a faster and simpler replacement for :mod:`hashlib` objects.

Creating hash objects

New hash objects are created by calling constructor functions:

.. function:: blake2b(data=b'', *, digest_size=64, key=b'', salt=b'', \
 person=b'', fanout=1, depth=1, leaf_size=0, node_offset=0, \
 node_depth=0, inner_size=0, last_node=False)

.. function:: blake2s(data=b'', *, digest_size=32, key=b'', salt=b'', \
 person=b'', fanout=1, depth=1, leaf_size=0, node_offset=0, \
 node_depth=0, inner_size=0, last_node=False)

These functions return the corresponding hash objects for calculating BLAKE2b or BLAKE2s. They optionally take these general parameters:

• data: initial chunk of data to hash, which must be :term:`bytes-like object`. It can be passed only as positional argument.
• digest_size: size of output digest in bytes.
• key: key for keyed hashing (up to 64 bytes for BLAKE2b, up to 32 bytes for BLAKE2s).
• salt: salt for randomized hashing (up to 16 bytes for BLAKE2b, up to 8 bytes for BLAKE2s).
• person: personalization string (up to 16 bytes for BLAKE2b, up to 8 bytes for BLAKE2s).

The following table shows limits for general parameters (in bytes):

These sizes are available as module constants described below.

Constructor functions also accept the following tree hashing parameters:

• fanout: fanout (0 to 255, 0 if unlimited, 1 in sequential mode).
• depth: maximal depth of tree (1 to 255, 255 if unlimited, 1 in sequential mode).
• leaf_size: maximal byte length of leaf (0 to 2**32-1, 0 if unlimited or in sequential mode).
• node_offset: node offset (0 to 2**64-1 for BLAKE2b, 0 to 2**48-1 for BLAKE2s, 0 for the first, leftmost, leaf, or in sequential mode).
• node_depth: node depth (0 to 255, 0 for leaves, or in sequential mode).
• inner_size: inner digest size (0 to 64 for BLAKE2b, 0 to 32 for BLAKE2s, 0 in sequential mode).
• last_node: boolean indicating whether the processed node is the last one (False for sequential mode).

See section 2.10 in Constants

.. data:: blake2b.SALT_SIZE

.. data:: blake2s.SALT_SIZE

Salt length (maximum length accepted by constructors).

.. data:: blake2b.PERSON_SIZE

.. data:: blake2s.PERSON_SIZE

Personalization string length (maximum length accepted by constructors).

.. data:: blake2b.MAX_KEY_SIZE

.. data:: blake2s.MAX_KEY_SIZE

Maximum key size.

.. data:: blake2b.MAX_DIGEST_SIZE

.. data:: blake2s.MAX_DIGEST_SIZE

Maximum digest size that the hash function can output.

Examples

Simple hashing

To calculate hash of some data, you should first construct a hash object by calling the appropriate constructor function (:func:`blake2b` or :func:`blake2s`), then update it with the data by calling :meth:`update` on the object, and, finally, get the digest out of the object by calling :meth:`digest` (or :meth:`hexdigest` for hex-encoded string).

>>> from hashlib import blake2b
>>> h = blake2b()
>>> h.update(b'Hello world')
>>> h.hexdigest()
'6ff843ba685842aa82031d3f53c48b66326df7639a63d128974c5c14f31a0f33343a8c65551134ed1ae0f2b0dd2bb495dc81039e3eeb0aa1bb0388bbeac29183'

As a shortcut, you can pass the first chunk of data to update directly to the constructor as the positional argument:

>>> from hashlib import blake2b
>>> blake2b(b'Hello world').hexdigest()
'6ff843ba685842aa82031d3f53c48b66326df7639a63d128974c5c14f31a0f33343a8c65551134ed1ae0f2b0dd2bb495dc81039e3eeb0aa1bb0388bbeac29183'

You can call :meth:`hash.update` as many times as you need to iteratively update the hash:

>>> from hashlib import blake2b
>>> items = [b'Hello', b' ', b'world']
>>> h = blake2b()
>>> for item in items:
... h.update(item)
>>> h.hexdigest()
'6ff843ba685842aa82031d3f53c48b66326df7639a63d128974c5c14f31a0f33343a8c65551134ed1ae0f2b0dd2bb495dc81039e3eeb0aa1bb0388bbeac29183'

Using different digest sizes

BLAKE2 has configurable size of digests up to 64 bytes for BLAKE2b and up to 32 bytes for BLAKE2s. For example, to replace SHA-1 with BLAKE2b without changing the size of output, we can tell BLAKE2b to produce 20-byte digests:

>>> from hashlib import blake2b
>>> h = blake2b(digest_size=20)
>>> h.update(b'Replacing SHA1 with the more secure function')
>>> h.hexdigest()
'd24f26cf8de66472d58d4e1b1774b4c9158b1f4c'
>>> h.digest_size
20
>>> len(h.digest())
20

Hash objects with different digest sizes have completely different outputs (shorter hashes are not prefixes of longer hashes); BLAKE2b and BLAKE2s produce different outputs even if the output length is the same:

>>> from hashlib import blake2b, blake2s
>>> blake2b(digest_size=10).hexdigest()
'6fa1d8fcfd719046d762'
>>> blake2b(digest_size=11).hexdigest()
'eb6ec15daf9546254f0809'
>>> blake2s(digest_size=10).hexdigest()
'1bf21a98c78a1c376ae9'
>>> blake2s(digest_size=11).hexdigest()
'567004bf96e4a25773ebf4'

Keyed hashing

Keyed hashing can be used for authentication as a faster and simpler replacement for

Even though there's a native keyed hashing mode, BLAKE2 can, of course, be used in HMAC construction with :mod:`hmac` module:

>>> import hmac, hashlib
>>> m = hmac.new(b'secret key', digestmod=hashlib.blake2s)
>>> m.update(b'message')
>>> m.hexdigest()
'e3c8102868d28b5ff85fc35dda07329970d1a01e273c37481326fe0c861c8142'

Randomized hashing

By setting salt parameter users can introduce randomization to the hash function. Randomized hashing is useful for protecting against collision attacks on the hash function used in digital signatures.

Randomized hashing is designed for situations where one party, the message preparer, generates all or part of a message to be signed by a second party, the message signer. If the message preparer is able to find cryptographic hash function collisions (i.e., two messages producing the same hash value), then they might prepare meaningful versions of the message that would produce the same hash value and digital signature, but with different results (e.g., transferring 1,000,000ドル to an account, rather than 10ドル). Cryptographic hash functions have been designed with collision resistance as a major goal, but the current concentration on attacking cryptographic hash functions may result in a given cryptographic hash function providing less collision resistance than expected. Randomized hashing offers the signer additional protection by reducing the likelihood that a preparer can generate two or more messages that ultimately yield the same hash value during the digital signature generation process --- even if it is practical to find collisions for the hash function. However, the use of randomized hashing may reduce the amount of security provided by a digital signature when all portions of the message are prepared by the signer.

()

 10
 / \
00 01

>>> from hashlib import blake2b
>>>
>>> FANOUT = 2
>>> DEPTH = 2
>>> LEAF_SIZE = 4096
>>> INNER_SIZE = 64
>>>
>>> buf = bytearray(6000)
>>>
>>> # Left leaf
... h00 = blake2b(buf[0:LEAF_SIZE], fanout=FANOUT, depth=DEPTH,
... leaf_size=LEAF_SIZE, inner_size=INNER_SIZE,
... node_offset=0, node_depth=0, last_node=False)
>>> # Right leaf
... h01 = blake2b(buf[LEAF_SIZE:], fanout=FANOUT, depth=DEPTH,
... leaf_size=LEAF_SIZE, inner_size=INNER_SIZE,
... node_offset=1, node_depth=0, last_node=True)
>>> # Root node
... h10 = blake2b(digest_size=32, fanout=FANOUT, depth=DEPTH,
... leaf_size=LEAF_SIZE, inner_size=INNER_SIZE,
... node_offset=0, node_depth=1, last_node=True)
>>> h10.update(h00.digest())
>>> h10.update(h01.digest())
>>> h10.hexdigest()
'3ad2a9b37c6070e374c7a8c508fe20ca86b6ed54e286e93a0318e95e881db5aa'