15.1.hashlib — Secure hashes and message digests¶

Source code:Lib/hashlib.py

This module implements a common interface to many different secure hash andmessage 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 MD5algorithm (defined in InternetRFC 1321). The terms “secure hash” and“message digest” are interchangeable. Older algorithms were called messagedigests. The modern term is secure hash.

There is one constructor method named for each type ofhash. All returna hash object with the same simple interface. For example: usesha1() tocreate a SHA1 hash object. You can now feed this object withbytes-likeobjects (normallybytes) using theupdate() method.At any point you can ask it for thedigest of theconcatenation of the data fed to it so far using thedigest() orhexdigest() methods.

Constructors for hash algorithms that are always present in this module aremd5(),sha1(),sha224(),sha256(),sha384(), andsha512(). Additional algorithms may also be available depending upon theOpenSSL library that Python uses on your platform.

For example, to obtain the digest of the byte stringb'Nobodyinspectsthespammishrepetition':

>>>importhashlib>>>m=hashlib.md5()>>>m.update(b"Nobody inspects")>>>m.update(b" the spammish repetition")>>>m.digest()b'\xbbd\x9c\x83\xdd\x1e\xa5\xc9\xd9\xde\xc9\xa1\x8d\xf0\xff\xe9'>>>m.digest_size16>>>m.block_size64

More condensed:

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

hashlib.new(name[,data])¶

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. The named constructors are much faster thannew()and should be preferred.

Usingnew() 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:

hashlib.algorithms_guaranteed¶

A set containing the names of the hash algorithms guaranteed to be supportedby this module on all platforms.

New 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).

New in version 3.2.

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 methods:

hash.update(arg)¶

Update the hash object with the objectarg, which must be interpretable asa buffer of bytes. 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).

Changed in version 3.1:The Python GIL is released to allow other threads to run while hashupdates on data larger than 2047 bytes is taking place when using hashalgorithms supplied by OpenSSL.

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.