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'
>>>
>>> secret = b'Sixteen byte key'
>>> mac = KMAC128.new(key=secret, mac_len=16)
>>> mac.update(msg)
>>> try:
>>> mac.verify(mac)
>>> 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.
-
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