- Primitives
- Message authentication codes
- Hash-based message authentication codes (HMAC)
- Edit on GitHub
Danger
This is a “Hazardous Materials” module. You should ONLY use it if you’re100% absolutely sure that you know what you’re doing because this module isfull of land mines, dragons, and dinosaurs with laser guns.
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.Thekey
should be randomly generated bytes andis recommended to be equal in length to thedigest_size
of the hashfunction chosen. You must keep thekey
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
instancethenTypeError
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.
- Parameters:
key (bytes-like) – The secret key.
algorithm – An
HashAlgorithm
instance 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 notbytes
.
- 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 to
signature
.- 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 anAlreadyFinalized
exception.- Return bytes:
The message digest as bytes.
- Raises: