# 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