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

class Crypto.Hash.HMAC.HMAC(key, msg=b'', digestmod=None)¶

An HMAC hash object. Do not instantiate directly. Use the new() function.

Variables:

digest_size (integer) – the size in bytes of the resulting MAC tag
oid – the ASN.1 object ID of the HMAC algorithm. Only present if the algorithm was officially assigned one.

copy()¶

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

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

Returns:: An HMAC

digest()¶

Return the binary (non-printable) MAC tag of the message authenticated so far.

Returns:: The MAC tag digest, computed over the data processed so far. Binary form.
Return type:: byte string

hexdigest()¶

Return the printable MAC tag of the message authenticated so far.

Returns:: The MAC tag, computed over the data processed so far. Hexadecimal encoded.
Return type:: string

hexverify(hex_mac_tag)¶

Verify that a given printable MAC (computed by another party) is valid.

Parameters:: hex_mac_tag (string) – the expected MAC of the message, as a hexadecimal string.
Raises:: ValueError – if the MAC does not match. It means that the message has been tampered with or that the MAC key is incorrect.

update(msg)¶

Authenticate the next chunk of message.

Parameters:: data (byte string/byte array/memoryview) – The next chunk of data

verify(mac_tag)¶

Verify that a given binary MAC (computed by another party) is valid.

Parameters:: mac_tag (byte string/byte string/memoryview) – the expected MAC of the message.
Raises:: ValueError – if the MAC does not match. It means that the message has been tampered with or that the MAC key is incorrect.

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

Create a new MAC object.

Parameters:

key (bytes/bytearray/memoryview) – key for the MAC object. It must be long enough to match the expected security level of the MAC.
msg (bytes/bytearray/memoryview) – Optional. The very first chunk of the message to authenticate. It is equivalent to an early call to HMAC.update().
digestmod (module) – The hash to use to implement the HMAC. Default is Crypto.Hash.MD5.

Returns:

An HMAC object