HMAC

HMAC (Hash-based Message Authentication Code) is a MAC defined in RFC2104 and FIPS-198_ and constructed using a cryptographic hash algorithm.

It is usually named HMAC-X, where X is the hash algorithm; for instance HMAC-SHA1 or HMAC-SHA256.

The strength of an HMAC depends on:

  • the strength of the hash algorithm

  • the entropy of the secret key

This is an example showing how to generate a MAC (with HMAC-SHA256):

>>> from Crypto.Hash import HMAC, SHA256
>>>
>>> secret = b'Swordfish'
>>> h = HMAC.new(secret, digestmod=SHA256)
>>> h.update(b'Hello')
>>> print(h.hexdigest())

This is an example showing how to validate the MAC:

>>> from Crypto.Hash import HMAC, SHA256
>>>
>>> # We have received a message 'msg' together
>>> # with its MAC 'mac'
>>>
>>> secret = b'Swordfish'
>>> h = HMAC.new(secret, digestmod=SHA256)
>>> h.update(msg)
>>> try:
>>>   h.hexverify(mac)
>>>   print("The message '%s' is authentic" % msg)
>>> except ValueError:
>>>   print("The message or the key is wrong")

HMAC (Hash-based Message Authentication Code) algorithm

HMAC is a MAC defined in RFC2104 and FIPS-198_ and constructed using a cryptograpic hash algorithm. It is usually named HMAC-X, where X is the hash algorithm; for instance HMAC-SHA1 or HMAC-MD5.

The strength of an HMAC depends on:

  • the strength of the hash algorithm

  • the length and entropy of the secret key

An example of possible usage is the following:

>>> from Crypto.Hash import HMAC
>>>
>>> secret = b'Swordfish'
>>> h = HMAC.new(secret)
>>> h.update(b'Hello')
>>> print h.hexdigest()
class Crypto.Hash.HMAC.HMAC(key, msg=None, digestmod=None)

Class that implements HMAC

copy()

Return a copy (“clone”) of the MAC object.

The copy will have the same internal state as the original MAC object. This can be used to efficiently compute the MAC of strings that share a common initial substring.

Returns:

An HMAC object

digest()

Return the binary (non-printable) MAC of the message that has been authenticated so far.

This method does not change the state of the MAC object. You can continue updating the object after calling this function.

Return:

A byte string of digest_size bytes. It may contain non-ASCII characters, including null bytes.

digest_size = None

The size of the authentication tag produced by the MAC. It matches the digest size on the underlying hashing module used.

hexdigest()

Return the printable MAC of the message that has been authenticated so far.

This method does not change the state of the MAC object.

Return:

A string of 2* digest_size bytes. It contains only hexadecimal ASCII digits.

update(msg)

Continue authentication of a message by consuming the next chunk of data.

Repeated calls are equivalent to a single call with the concatenation of all the arguments. In other words:

>>> m.update(a); m.update(b)

is equivalent to:

>>> m.update(a+b)
Parameters:
msgbyte string

The next chunk of the message being authenticated

Crypto.Hash.HMAC.digest_size = None

The size of the authentication tag produced by the MAC. It matches the digest size on the underlying hashing module used.

Crypto.Hash.HMAC.new(key, msg=None, digestmod=None)

Create a new HMAC object.

Parameters:
keybyte string

key for the MAC object. It must be long enough to match the expected security level of the MAC. However, there is no benefit in using keys longer than the digest_size of the underlying hash algorithm.

msgbyte string

The very first chunk of the message to authenticate. It is equivalent to an early call to HMAC.update(). Optional.

Parameter digestmod:

The hash to use to implement the HMAC. Default is Crypto.Hash.MD5.

Type digestmod:

A hash module or instantiated object from Crypto.Hash

Returns:

An HMAC object