KMAC128

KMAC128 is a variable-length Message Authenticated Code (MAC) derived from SHA-3 and standardized in NIST SP 800-185.

KMAC128 provides a security strength of 128 bits. It must be keyed with a secret of 16 bytes or more.

This is an example showing how to generate a KMAC128 tag:

>>> from Crypto.Hash import KMAC128
>>>
>>> secret = b'Sixteen byte key'
>>> mac = KMAC128.new(key=secret, mac_len=16)
>>> mac.update(b'Hello')
>>> print(mac.hexdigest())
e6cb0fb015898ebd019d4eb5fad444bf

And this is an example showing how to validate the KMAC128 tag:

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

An application can select the length of the MAC tag by means of the initialization parameter mac_len. For instance, while the traditional HMAC-SHA256 can only produce 32-byte tags, with KMAC128 you can produce 16-byte tags (see the examples above) but also a 33-byte tag:

>>> from Crypto.Hash import KMAC128
>>>
>>> secret = b'Sixteen byte key'
>>> mac = KMAC128.new(key=secret, mac_len=33)
>>> mac.update(b'Hello')
>>> print(mac.hexdigest())
eed4b3157bd5d98002ad0ca990c192125416c7a72705fea22cf5d896361243bc5a

Note how the 16-byte tag is NOT just the truncated version of the 33-byte tag: they are cryptographically uncorrelated.

class Crypto.Hash.KMAC128.KMAC_Hash(data, key, mac_len, custom, oid_variant, cshake, rate)

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

digest()

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

Returns

The MAC tag. Binary form.

Return type

byte string

hexdigest()

Return the printable MAC tag of the message.

Returns

The MAC tag. 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.

new(**kwargs)

Return a new instance of a KMAC hash object. See new().

update(data)

Authenticate the next chunk of message.

Parameters
  • data (bytes/bytearray/memoryview) – The next chunk of the message to

  • authenticate.

verify(mac_tag)

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

Parameters

mac_tag (bytes/bytearray/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.KMAC128.new(**kwargs)

Create a new KMAC128 object.

Parameters
  • key (bytes/bytearray/memoryview) – The key to use to compute the MAC. It must be at least 128 bits long (16 bytes).

  • data (bytes/bytearray/memoryview) – Optional. The very first chunk of the message to authenticate. It is equivalent to an early call to KMAC_Hash.update().

  • mac_len (integer) – Optional. The size of the authentication tag, in bytes. Default is 64. Minimum is 8.

  • custom (bytes/bytearray/memoryview) – Optional. A customization byte string (S in SP 800-185).

Returns

A KMAC_Hash hash object