hmac.rst

Hash-based message authentication codes (HMAC)

cryptography.hazmat.primitives.hmac

import binascii key = binascii.unhexlify(b"0" * 32)

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

HMAC objects take a key and a ~cryptography.hazmat.primitives.hashes.HashAlgorithm instance. The key should be randomly generated bytes </random-numbers> and is recommended to be equal in length to the digest_size of the hash function chosen. You must keep the key secret.

This is an implementation of 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() >>> signature b'kxd9xb29xefSxf8xcfxecxedxbfx95xe6x97Xx18x9e%x11DU1x9fq}x9ax9cxe0)y`='

If algorithm isn't a ~cryptography.hazmat.primitives.hashes.HashAlgorithm instance then 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.

param key

Secret key as bytes.

type key

bytes-like

param algorithm

An ~cryptography.hazmat.primitives.hashes.HashAlgorithm instance such as those described in Cryptographic Hashes <cryptographic-hash-algorithms>.

raises cryptography.exceptions.UnsupportedAlgorithm

This is raised if the provided algorithm isn't supported.

update(msg)

param msg

The bytes to hash and authenticate.

type msg

bytes-like

raises cryptography.exceptions.AlreadyFinalized

See finalize

raises TypeError

This exception is raised if msg is not bytes.

copy()

Copy this HMAC instance, usually so that we may call finalize to get an intermediate digest value while we continue to call update on the original instance.

return

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

raises cryptography.exceptions.AlreadyFinalized

See finalize

verify(signature)

Finalize the current context and securely compare digest to signature.

param bytes signature

The bytes to compare the current digest against.

raises cryptography.exceptions.AlreadyFinalized

See finalize

raises cryptography.exceptions.InvalidSignature

If signature does not match digest

raises TypeError

This exception is raised if signature is not bytes.

finalize()

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

After finalize has been called this object can no longer be used and update, copy, verify and finalize will raise an ~cryptography.exceptions.AlreadyFinalized exception.

return bytes

The message digest as bytes.

raises cryptography.exceptions.AlreadyFinalized