15.2.hmac — Keyed-Hashing for Message Authentication¶

Source code:Lib/hmac.py

This module implements the HMAC algorithm as described byRFC 2104.

hmac.new(key,msg=None,digestmod=None)¶

Return a new hmac object.key is a bytes object giving the secret key. Ifmsg is present, the method callupdate(msg) is made.digestmod isthe digest constructor or module for the HMAC object to use. It defaults tothehashlib.md5 constructor.

An HMAC object has the following methods:

HMAC.update(msg)¶

Update the hmac object with the bytes objectmsg. Repeated calls areequivalent to a single call with the concatenation of all the arguments:m.update(a);m.update(b) is equivalent tom.update(a+b).

HMAC.digest()¶

Return the digest of the bytes passed to theupdate() method so far.This bytes object will be the same length as thedigest_size of the digestgiven to the constructor. It may contain non-ASCII bytes, including NULbytes.

Warning

When comparing the output ofdigest() to an externally-supplieddigest during a verification routine, it is recommended to use thecompare_digest() function instead of the== operatorto reduce the vulnerability to timing attacks.

HMAC.hexdigest()¶

Likedigest() except the digest is returned as a string twice thelength containing only hexadecimal digits. This may be used to exchange thevalue safely in email or other non-binary environments.

Warning

When comparing the output ofhexdigest() to an externally-supplieddigest during a verification routine, it is recommended to use thecompare_digest() function instead of the== operatorto reduce the vulnerability to timing attacks.

HMAC.copy()¶

Return a copy (“clone”) of the hmac object. This can be used to efficientlycompute the digests of strings that share a common initial substring.

This module also provides the following helper function:

hmac.compare_digest(a,b)¶

Returna==b. This function uses an approach designed to preventtiming analysis by avoiding content-based short circuiting behaviour,making it appropriate for cryptography.a andb must both be of thesame type: eitherstr (ASCII only, as e.g. returned byHMAC.hexdigest()), or abytes-like object.

Note

Ifa andb are of different lengths, or if an error occurs,a timing attack could theoretically reveal information about thetypes and lengths ofa andb–but not their values.

New in version 3.3.