Hash-based message authentication codes (HMAC) — Cryptography 44.0.0.dev1 documentation (2024)

Hash-based message authentication codes (or HMACs) are a tool for calculatingmessage authentication codes using a cryptographic hash function coupled with asecret key. You can use an HMAC to verify both the integrity and authenticityof a message.

class cryptography.hazmat.primitives.hmac.HMAC(key, algorithm)

HMAC objects take a key and aHashAlgorithm instance.The key should be randomly generated bytes andis recommended to be equal in length to the digest_size of the hashfunction chosen. You must keep the key secret.

This is an implementation of RFC 2104.

>>> from cryptography.hazmat.primitives import hashes, hmac>>> key = b'test key. Beware! A real key should use os.urandom or TRNG to generate'>>> h = hmac.HMAC(key, hashes.SHA256())>>> h.update(b"message to hash")>>> signature = h.finalize()>>> signatureb'k\xd9\xb29\xefS\xf8\xcf\xec\xed\xbf\x95\xe6\x97X\x18\x9e%\x11DU1\x9fq}\x9a\x9c\xe0)y`='

If algorithm isn’t aHashAlgorithm instancethen TypeError will be raised.

To check that a given signature is correct use the verify() method.You will receive an exception if the signature is wrong:

>>> h = hmac.HMAC(key, hashes.SHA256())>>> h.update(b"message to hash")>>> h_copy = h.copy() # get a copy of `h' to be reused>>> h.verify(signature)>>>>>> h_copy.verify(b"an incorrect signature")Traceback (most recent call last):...cryptography.exceptions.InvalidSignature: Signature did not match digest.

See Also

SSH SHA-1 HMAC Algorithms Enabled

Parameters:

• key (bytes-like) – The secret key.

• algorithm – AnHashAlgorithminstance such as those described inCryptographic Hashes.

Raises:

cryptography.exceptions.UnsupportedAlgorithm – This is raised if theprovided algorithm isn’t supported.

update(msg)

Parameters:

msg (bytes-like) – The bytes to hash and authenticate.

Raises:

• cryptography.exceptions.AlreadyFinalized – See finalize()

• TypeError – This exception is raised if msg is not bytes.

copy()

Copy this HMAC instance, usually so that we may callfinalize() to get an intermediate digest value while we continueto call update() on the original instance.

Returns:

A new instance of HMAC that can be updatedand finalized independently of the original instance.

Raises:

cryptography.exceptions.AlreadyFinalized – See finalize()

verify(signature)

Finalize the current context and securely compare digest tosignature.

Parameters:

signature (bytes) – The bytes to compare the current digestagainst.

Raises:

• cryptography.exceptions.AlreadyFinalized – See finalize()

• cryptography.exceptions.InvalidSignature – If signature does notmatch digest

• TypeError – This exception is raised if signature is notbytes.

finalize()

Finalize the current context and return the message digest as bytes.

After finalize has been called this object can no longer be usedand update(), copy(), verify() and finalize()will raise an AlreadyFinalizedexception.

Return bytes:

The message digest as bytes.

Raises:

cryptography.exceptions.AlreadyFinalized –