hmac — Keyed-Hashing for Message Authentication¶

Source code:Lib/hmac.py

This module implements the HMAC algorithm as described byRFC 2104.The interface allows to use any hash function with afixed digest size.In particular, extendable output functions such as SHAKE-128 or SHAKE-256cannot be used with HMAC.

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

Return a new hmac object.key is a bytes or bytearray object giving thesecret key. Ifmsg is present, the method callupdate(msg) is made.digestmod is the digest name, digest constructor or module for the HMACobject to use. It may be any name suitable tohashlib.new().Despite its argument position, it is required.

Changed in version 3.4:Parameterkey can be a bytes or bytearray object.Parametermsg can be of any type supported byhashlib.Parameterdigestmod can be the name of a hash algorithm.

Changed in version 3.8:Thedigestmod argument is now required. Pass it as a keywordargument to avoid awkwardness when you do not have an initialmsg.

hmac.digest(key,msg,digest)¶

Return digest ofmsg for given secretkey anddigest. Thefunction is equivalent toHMAC(key,msg,digest).digest(), butuses an optimized C or inline implementation, which is faster for messagesthat fit into memory. The parameterskey,msg, anddigest havethe same meaning as innew().

CPython implementation detail, the optimized C implementation is only usedwhendigest is a string and name of a digest algorithm, which issupported by OpenSSL.

Added in version 3.7.

classhmac.HMAC¶

An HMAC object has the following methods:

HMAC.update(msg)¶

Update the hmac object withmsg. Repeated calls are equivalent to asingle call with the concatenation of all the arguments:m.update(a);m.update(b) is equivalent tom.update(a+b).

Changed in version 3.4:Parametermsg can be of any type supported byhashlib.

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.

A hash object has the following attributes:

HMAC.digest_size¶

The size of the resulting HMAC digest in bytes.

HMAC.block_size¶

The internal block size of the hash algorithm in bytes.

Added in version 3.4.

HMAC.name¶

The canonical name of this HMAC, always lowercase, e.g.hmac-md5.

Added in version 3.4.

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.

Added in version 3.3.

Changed in version 3.10:The function uses OpenSSL’sCRYPTO_memcmp() internally whenavailable.