CMAC¶

CMAC (Cipher-based Message Authentication Code) is a MAC defined in NIST SP 800-38B and in RFC4493 (for AES only) and constructed using a block cipher. It was originally known as OMAC1.

The algorithm is sometimes named X-CMAC where X is the name of the cipher (e.g. AES-CMAC).

This is an example showing how to generate an AES-CMAC tag:

>>> from Crypto.Hash import CMAC
>>> from Crypto.Cipher import AES
>>>
>>> secret = b'Sixteen byte key'
>>> cobj = CMAC.new(secret, ciphermod=AES)
>>> cobj.update(b'Hello')
>>> print cobj.hexdigest()

And this is an example showing how to validate the AES-CMAC:

>>> from Crypto.Hash import CMAC
>>> from Crypto.Cipher import AES
>>>
>>> # We have received a message 'msg' together
>>> # with its MAC 'mac'
>>>
>>> secret = b'Sixteen byte key'
>>> cobj = CMAC.new(secret, ciphermod=AES)
>>> cobj.update(msg)
>>> try:
>>>   cobj.verify(mac)
>>>   print "The message '%s' is authentic" % msg
>>> except ValueError:
>>>   print "The message or the key is wrong"

A cipher block size of 128 bits (like for AES) guarantees that the risk of MAC collisions remains negligible even when the same CMAC key is used to authenticate a large amount of data.

This implementation allows also usage of ciphers with a 64 bits block size (like TDES) for legacy purposes only. However, the risk is much higher and one CMAC key should be rotated after as little as 16 MB (in total) have been authenticated.

class Crypto.Hash.CMAC.CMAC(key, msg, ciphermod, cipher_params, mac_len, update_after_digest)¶

A CMAC hash object. Do not instantiate directly. Use the new() function.

Variables:: digest_size (integer) – the size in bytes of the resulting MAC tag

copy()¶

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

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

Returns:: An CMAC

digest()¶

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

Returns:: The MAC tag, 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 array/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.CMAC.new(key, msg=None, ciphermod=None, cipher_params=None, mac_len=None, update_after_digest=False)¶

Create a new MAC object.

Parameters:

key (byte string/byte array/memoryview) – key for the CMAC object. The key must be valid for the underlying cipher algorithm. For instance, it must be 16 bytes long for AES-128.
ciphermod (module) – A cipher module from Crypto.Cipher. The cipher’s block size has to be 128 bits, like Crypto.Cipher.AES, to reduce the probability of collisions.
msg (byte string/byte array/memoryview) – Optional. The very first chunk of the message to authenticate. It is equivalent to an early call to CMAC.update. Optional.
cipher_params (dict) – Optional. A set of parameters to use when instantiating a cipher object.
mac_len (integer) – Length of the MAC, in bytes. It must be at least 4 bytes long. The default (and recommended) length matches the size of a cipher block.
update_after_digest (boolean) – Optional. By default, a hash object cannot be updated anymore after the digest is computed. When this flag is True, such check is no longer enforced.

Returns:

A CMAC object