hashlib — Secure hashes and message digests (2024)

Hash algorithms¶

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

To allow multithreading, the Python GIL is released while computing ahash supplied more than 2047 bytes of data at once in its constructor or.update method.

Constructors for hash algorithms that are always present in this module aresha1(), sha224(), sha256(), sha384(), sha512(),sha3_224(), sha3_256(), sha3_384(), sha3_512(),shake_128(), shake_256(), blake2b(), and blake2s().md5() is normally available as well, though it may be missing or blockedif you are using a rare “FIPS compliant” build of Python.These correspond to algorithms_guaranteed.

Additional algorithms may also be available if your Python distribution’shashlib was linked against a build of OpenSSL that provides others.Others are not guaranteed available on all installations and will only beaccessible by name via new(). See algorithms_available.

Changed in version 3.9: All hashlib constructors take a keyword-only argument usedforsecuritywith default value True. A false value allows the use of insecure andblocked hashing algorithms in restricted environments. False indicatesthat the hashing algorithm is not used in a security context, e.g. as anon-cryptographic one-way compression function.

Changed in version 3.9: Hashlib now uses SHA3 and SHAKE from OpenSSL if it provides it.

Changed in version 3.12: For any of the MD5, SHA1, SHA2, or SHA3 algorithms that the linkedOpenSSL does not provide we fall back to a verified implementation fromthe HACL* project.

Usage¶

To obtain the digest of the byte string b"Nobody inspects the spammishrepetition":

>>> 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.hexdigest()'031edd7d41651593c5fe5c006fa5752b37fddff7bc4e843aa6af0c950f4b9406'

More condensed:

>>> hashlib.sha256(b"Nobody inspects the spammish repetition").hexdigest()'031edd7d41651593c5fe5c006fa5752b37fddff7bc4e843aa6af0c950f4b9406'

Constructors¶

hashlib.new(name, [data, ]*, usedforsecurity=True)¶

Is a generic constructor that takes the string name of the desiredalgorithm as its first parameter. It also exists to allow access to theabove listed hashes as well as any other algorithms that your OpenSSLlibrary may offer.

Using new() with an algorithm name:

>>> h = hashlib.new('sha256')>>> h.update(b"Nobody inspects the spammish repetition")>>> h.hexdigest()'031edd7d41651593c5fe5c006fa5752b37fddff7bc4e843aa6af0c950f4b9406'

hashlib.md5([data, ]*, usedforsecurity=True)¶

hashlib.sha1([data, ]*, usedforsecurity=True)¶

hashlib.sha224([data, ]*, usedforsecurity=True)¶

hashlib.sha256([data, ]*, usedforsecurity=True)¶

hashlib.sha384([data, ]*, usedforsecurity=True)¶

hashlib.sha512([data, ]*, usedforsecurity=True)¶

hashlib.sha3_224([data, ]*, usedforsecurity=True)¶

hashlib.sha3_256([data, ]*, usedforsecurity=True)¶

hashlib.sha3_384([data, ]*, usedforsecurity=True)¶

hashlib.sha3_512([data, ]*, usedforsecurity=True)¶

Named constructors such as these are faster than passing an algorithm name tonew().

Attributes¶

Hashlib provides the following constant module attributes:

hashlib.algorithms_guaranteed¶

A set containing the names of the hash algorithms guaranteed to be supportedby this module on all platforms. Note that ‘md5’ is in this list despitesome upstream vendors offering an odd “FIPS compliant” Python build thatexcludes it.

Added in version 3.2.

hashlib.algorithms_available¶

A set containing the names of the hash algorithms that are available in therunning Python interpreter. These names will be recognized when passed tonew(). algorithms_guaranteed will always be a subset. Thesame algorithm may appear multiple times in this set under different names(thanks to OpenSSL).

Added in version 3.2.

Hash Objects¶

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

hash.digest_size¶

The size of the resulting hash in bytes.

hash.block_size¶

The internal block size of the hash algorithm in bytes.

A hash object has the following attributes:

hash.name¶

The canonical name of this hash, always lowercase and always suitable as aparameter to new() to create another hash of this type.

Changed in version 3.4: The name attribute has been present in CPython since its inception, butuntil Python 3.4 was not formally specified, so may not exist on someplatforms.

A hash object has the following methods:

hash.update(data)¶

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

hash.digest()¶

Return the digest of the data passed to the update() method so far.This is a bytes object of size digest_size which may contain bytes inthe whole range from 0 to 255.

hash.hexdigest()¶

Like digest() except the digest is returned as a string object ofdouble length, containing only hexadecimal digits. This may be used toexchange the value safely in email or other non-binary environments.

See Also

PyCryptodome: Secure Your Data with EaseStrong Encryption Explained: 6 Encryption Best PracticesTypes of Encryption Algorithms + Pros and Cons for Each5 Python Libraries Every Cybersecurity Professionals Must Know

hash.copy()¶

Return a copy (“clone”) of the hash object. This can be used to efficientlycompute the digests of data sharing a common initial substring.

SHAKE variable length digests¶

hashlib.shake_128([data, ]*, usedforsecurity=True)¶

hashlib.shake_256([data, ]*, usedforsecurity=True)¶

The shake_128() and shake_256() algorithms provide variablelength 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 limitedby the SHAKE algorithm.

shake.digest(length)¶

Return the digest of the data passed to the update() method so far.This is a bytes object of size length which may contain bytes inthe whole range from 0 to 255.

shake.hexdigest(length)¶

Like digest() except the digest is returned as a string object ofdouble length, containing only hexadecimal digits. This may be used toexchange the value in email or other non-binary environments.

Example use:

>>> h = hashlib.shake_256(b'Nobody inspects the spammish repetition')>>> h.hexdigest(20)'44709d6fcb83d92a76dcb0b668c98e1b1d3dafe7'

File hashing¶

The hashlib module provides a helper function for efficient hashing ofa file or file-like object.

hashlib.file_digest(fileobj, digest, /)¶

Return a digest object that has been updated with contents of file object.

fileobj must be a file-like object opened for reading in binary mode.It accepts file objects from builtin open(), BytesIOinstances, SocketIO objects from socket.socket.makefile(), andsimilar. The function may bypass Python’s I/O and use the file descriptorfrom fileno() directly. fileobj must be assumed to bein an unknown state after this function returns or raises. It is up tothe caller to close fileobj.

digest must either be a hash algorithm name as a str, a hashconstructor, or a callable that returns a hash object.

Example:

>>> import io, hashlib, hmac>>> with open(hashlib.__file__, "rb") as f:...  digest = hashlib.file_digest(f, "sha256")...>>> digest.hexdigest() '...'

>>> buf = io.BytesIO(b"somedata")>>> mac1 = hmac.HMAC(b"key", digestmod=hashlib.sha512)>>> digest = hashlib.file_digest(buf, lambda: mac1)

>>> digest is mac1True>>> mac2 = hmac.HMAC(b"key", b"somedata", digestmod=hashlib.sha512)>>> mac1.digest() == mac2.digest()True

Added in version 3.11.

Key derivation¶

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

hashlib.pbkdf2_hmac(hash_name, password, salt, iterations, dklen=None)¶

The function provides PKCS#5 password-based key derivation function 2. Ituses HMAC as pseudorandom function.

The string hash_name is the desired name of the hash digest algorithm forHMAC, e.g. ‘sha1’ or ‘sha256’. password and salt are interpreted asbuffers of bytes. Applications and libraries should limit password toa sensible length (e.g. 1024). salt should be about 16 or more bytes froma proper source, e.g. os.urandom().

The number of iterations should be chosen based on the hash algorithm andcomputing power. As of 2022, hundreds of thousands of iterations of SHA-256are suggested. For rationale as to why and how to choose what is best foryour application, read Appendix A.2.2 of NIST-SP-800-132. The answerson the stackexchange pbkdf2 iterations question explain in detail.

dklen is the length of the derived key. If dklen is None then thedigest size of the hash algorithm hash_name is used, e.g. 64 for SHA-512.

>>> from hashlib import pbkdf2_hmac>>> our_app_iters = 500_000 # Application specific, read above.>>> dk = pbkdf2_hmac('sha256', b'password', b'bad salt' * 2, our_app_iters)>>> dk.hex()'15530bba69924174860db778f2c6f8104d3aaf9d26241840c8c4a641c8d000a9'

Function only available when Python is compiled with OpenSSL.

Added in version 3.4.

Changed in version 3.12: Function now only available when Python is built with OpenSSL. The slowpure Python implementation has been removed.

hashlib.scrypt(password, *, salt, n, r, p, maxmem=0, dklen=64)¶

The function provides scrypt password-based key derivation function asdefined in RFC 7914.

password and salt must be bytes-like objects. Applications and libraries should limit passwordto a sensible length (e.g. 1024). salt should be about 16 or morebytes from a proper source, e.g. os.urandom().

n is the CPU/Memory cost factor, r the block size, p parallelizationfactor and maxmem limits memory (OpenSSL 1.1.0 defaults to 32 MiB).dklen is the length of the derived key.

Added in version 3.6.

BLAKE2¶

BLAKE2 is a cryptographic hash function defined in RFC 7693 that comes in twoflavors:

• BLAKE2b, optimized for 64-bit platforms and produces digests of any sizebetween 1 and 64 bytes,

• BLAKE2s, optimized for 8- to 32-bit platforms and produces digests of anysize between 1 and 32 bytes.

BLAKE2 supports keyed mode (a faster and simpler replacement for HMAC),salted hashing, personalization, and tree hashing.

Hash objects from this module follow the API of standard library’shashlib objects.

Creating hash objects¶

New hash objects are created by calling constructor functions:

hashlib.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, usedforsecurity=True)¶

hashlib.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, usedforsecurity=True)¶

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

• data: initial chunk of data to hash, which must bebytes-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 forBLAKE2s).

• salt: salt for randomized hashing (up to 16 bytes for BLAKE2b, up to 8bytes for BLAKE2s).

• person: personalization string (up to 16 bytes for BLAKE2b, up to 8 bytesfor BLAKE2s).

  See Also

  Build Error: pycrypto 2.6.1 for Python 3.9.12 on Windows

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

Hash	digest_size	len(key)	len(salt)	len(person)
BLAKE2b	64	64	16	16
BLAKE2s	32	32	8	8

Note

BLAKE2 specification defines constant lengths for salt and personalizationparameters, however, for convenience, this implementation accepts bytestrings of any size up to the specified length. If the length of theparameter is less than specified, it is padded with zeros, thus, forexample, b'salt' and b'salt\x00' is the same value. (This is notthe case for key.)

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 insequential mode).

• leaf_size: maximal byte length of leaf (0 to 2**32-1, 0 if unlimited or insequential mode).

• node_offset: node offset (0 to 2**64-1 for BLAKE2b, 0 to 2**48-1 forBLAKE2s, 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 forBLAKE2s, 0 in sequential mode).

• last_node: boolean indicating whether the processed node is the lastone (False for sequential mode).

See section 2.10 in BLAKE2 specification for comprehensive review of treehashing.

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

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

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

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

>>> 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'

>>> from hashlib import blake2b>>> h = blake2b(key=b'pseudorandom key', digest_size=16)>>> h.update(b'message data')>>> h.hexdigest()'3d363ff7401e02026f4a4687d4863ced'

>>> from hashlib import blake2b>>> from hmac import compare_digest>>>>>> SECRET_KEY = b'pseudorandomly generated server secret key'>>> AUTH_SIZE = 16>>>>>> def sign(cookie):...  h = blake2b(digest_size=AUTH_SIZE, key=SECRET_KEY)...  h.update(cookie)...  return h.hexdigest().encode('utf-8')>>>>>> def verify(cookie, sig):...  good_sig = sign(cookie)...  return compare_digest(good_sig, sig)>>>>>> cookie = b'user-alice'>>> sig = sign(cookie)>>> print("{0},{1}".format(cookie.decode('utf-8'), sig))user-alice,b'43b3c982cf697e0c5ab22172d1ca7421'>>> verify(cookie, sig)True>>> verify(b'user-bob', sig)False>>> verify(cookie, b'0102030405060708090a0b0c0d0e0f00')False

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

>>> import os>>> from hashlib import blake2b>>> msg = b'some message'>>> # Calculate the first hash with a random salt.>>> salt1 = os.urandom(blake2b.SALT_SIZE)>>> h1 = blake2b(salt=salt1)>>> h1.update(msg)>>> # Calculate the second hash with a different random salt.>>> salt2 = os.urandom(blake2b.SALT_SIZE)>>> h2 = blake2b(salt=salt2)>>> h2.update(msg)>>> # The digests are different.>>> h1.digest() != h2.digest()True

>>> from hashlib import blake2b>>> FILES_HASH_PERSON = b'MyApp Files Hash'>>> BLOCK_HASH_PERSON = b'MyApp Block Hash'>>> h = blake2b(digest_size=32, person=FILES_HASH_PERSON)>>> h.update(b'the same content')>>> h.hexdigest()'20d9cd024d4fb086aae819a1432dd2466de12947831b75c5a30cf2676095d3b4'>>> h = blake2b(digest_size=32, person=BLOCK_HASH_PERSON)>>> h.update(b'the same content')>>> h.hexdigest()'cf68fb5761b9c44e7878bfb2c4c9aea52264a80b75005e65619778de59f383a3'

>>> from hashlib import blake2s>>> from base64 import b64decode, b64encode>>> orig_key = b64decode(b'Rm5EPJai72qcK3RGBpW3vPNfZy5OZothY+kHY6h21KM=')>>> enc_key = blake2s(key=orig_key, person=b'kEncrypt').digest()>>> mac_key = blake2s(key=orig_key, person=b'kMAC').digest()>>> print(b64encode(enc_key).decode('utf-8'))rbPb15S/Z9t+agffno5wuhB77VbRi6F9Iv2qIxU7WHw=>>> print(b64encode(mac_key).decode('utf-8'))G9GtHFE1YluXY1zWPlYk1e/nWfu0WSEb0KRcjhDeP/o=

 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'