Hash algorithms¶

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

To allow multithreading, the PythonGIL 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(), andblake2s().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 toalgorithms_guaranteed.

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

Usage¶

To obtain the digest of the byte stringb"Nobodyinspectsthespammishrepetition":

>>>importhashlib>>>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 stringname 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.

Usingnew() 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 tonew() 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 thebytes-like object.Repeated calls are equivalent to a single call with theconcatenation of all the arguments:m.update(a);m.update(b) isequivalent tom.update(a+b).

hash.digest()¶

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

hash.hexdigest()¶

Likedigest() 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.

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)¶

Theshake_128() andshake_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 theupdate() method so far.This is a bytes object of sizelength which may contain bytes inthe whole range from 0 to 255.

shake.hexdigest(length)¶

Likedigest() 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 builtinopen(),BytesIOinstances, SocketIO objects fromsocket.socket.makefile(), andsimilar.fileobj must be opened in blocking mode, otherwise aBlockingIOError may be raised.

The function may bypass Python’s I/O and use the file descriptorfromfileno() directly.fileobj must be assumed to bein an unknown state after this function returns or raises. It is up tothe caller to closefileobj.

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

Example:

>>>importio,hashlib,hmac>>>withopen("library/hashlib.rst","rb")asf:...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)

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

Added in version 3.11.

Changed in version 3.13.3 (unreleased):Now raises aBlockingIOError if the file is opened in blockingmode. Previously, spurious null bytes were added to the digest.

Key derivation¶

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

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 stringhash_name is the desired name of the hash digest algorithm forHMAC, e.g. ‘sha1’ or ‘sha256’.password andsalt are interpreted asbuffers of bytes. Applications and libraries should limitpassword toa sensible length (e.g. 1024).salt should be about 16 or more bytes froma proper source, e.g.os.urandom().

The number ofiterations 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, readAppendix A.2.2 ofNIST-SP-800-132. The answerson thestackexchange pbkdf2 iterations question explain in detail.

dklen is the length of the derived key in bytes. Ifdklen isNone then thedigest size of the hash algorithmhash_name is used, e.g. 64 for SHA-512.

>>>fromhashlibimportpbkdf2_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 inRFC 7914.

password andsalt must bebytes-like objects. Applications and libraries should limitpasswordto 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 andmaxmem limits memory (OpenSSL 1.1.0 defaults to 32 MiB).dklen is the length of the derived key in bytes.

Added in version 3.6.

BLAKE2¶

BLAKE2 is a cryptographic hash function defined inRFC 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 supportskeyed mode (a faster and simpler replacement forHMAC),salted hashing,personalization, andtree 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).

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' andb'salt\x00' is the same value. (This is notthe case forkey.)

These sizes are available as moduleconstants 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 to2**32-1, 0 if unlimited or insequential mode).

• node_offset: node offset (0 to2**64-1 for BLAKE2b, 0 to2**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 inBLAKE2 specification for comprehensive review of treehashing.

>>>fromhashlibimportblake2b>>>h=blake2b()>>>h.update(b'Hello world')>>>h.hexdigest()'6ff843ba685842aa82031d3f53c48b66326df7639a63d128974c5c14f31a0f33343a8c65551134ed1ae0f2b0dd2bb495dc81039e3eeb0aa1bb0388bbeac29183'

>>>fromhashlibimportblake2b>>>blake2b(b'Hello world').hexdigest()'6ff843ba685842aa82031d3f53c48b66326df7639a63d128974c5c14f31a0f33343a8c65551134ed1ae0f2b0dd2bb495dc81039e3eeb0aa1bb0388bbeac29183'

>>>fromhashlibimportblake2b>>>items=[b'Hello',b' ',b'world']>>>h=blake2b()>>>foriteminitems:...h.update(item)...>>>h.hexdigest()'6ff843ba685842aa82031d3f53c48b66326df7639a63d128974c5c14f31a0f33343a8c65551134ed1ae0f2b0dd2bb495dc81039e3eeb0aa1bb0388bbeac29183'

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

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

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

>>>fromhashlibimportblake2b>>>fromhmacimportcompare_digest>>>>>>SECRET_KEY=b'pseudorandomly generated server secret key'>>>AUTH_SIZE=16>>>>>>defsign(cookie):...h=blake2b(digest_size=AUTH_SIZE,key=SECRET_KEY)...h.update(cookie)...returnh.hexdigest().encode('utf-8')>>>>>>defverify(cookie,sig):...good_sig=sign(cookie)...returncompare_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

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

>>>importos>>>fromhashlibimportblake2b>>>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

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

>>>fromhashlibimportblake2s>>>frombase64importb64decode,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/  \0001

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