Danger
This is a “Hazardous Materials” module. You should ONLY use it if you’re 100% absolutely sure that you know what you’re doing because this module is full of land mines, dragons, and dinosaurs with laser guns.
Hash-based message authentication codes (HMAC)¶
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.
-
class
cryptography.hazmat.primitives.hmac.HMAC(key, algorithm, backend)¶ HMAC objects take a
keyand aHashAlgorithminstance. Thekeyshould be randomly generated bytes and is recommended to be equal in length to thedigest_sizeof the hash function chosen. You must keep thekeysecret.This is an implementation of RFC 2104.
>>> from cryptography.hazmat.backends import default_backend >>> from cryptography.hazmat.primitives import hashes, hmac >>> h = hmac.HMAC(key, hashes.SHA256(), backend=default_backend()) >>> h.update(b"message to hash") >>> h.finalize() b'#F\xdaI\x8b"e\xc4\xf1\xbb\x9a\x8fc\xff\xf5\xdex.\xbc\xcd/+\x8a\x86\x1d\x84\'\xc3\xa6\x1d\xd8J'
If the backend doesn’t support the requested
algorithmanUnsupportedAlgorithmexception will be raised.If
algorithmisn’t aHashAlgorithminstance thenTypeErrorwill 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(), backend=default_backend()) >>> h.update(b"message to hash") >>> h.verify(b"an incorrect signature") Traceback (most recent call last): ... cryptography.exceptions.InvalidSignature: Signature did not match digest.
- Parameters
key (bytes-like) – Secret key as
bytes.algorithm – An
HashAlgorithminstance such as those described in Cryptographic Hashes.backend – An
HMACBackendinstance.
- Raises
cryptography.exceptions.UnsupportedAlgorithm – This is raised if the provided
backenddoes not implementHMACBackend
-
update(msg)¶ - Parameters
msg (bytes-like) – The bytes to hash and authenticate.
- Raises
TypeError – This exception is raised if
msgis notbytes.
-
copy()¶ Copy this
HMACinstance, usually so that we may callfinalize()to get an intermediate digest value while we continue to callupdate()on the original instance.- Returns
A new instance of
HMACthat can be updated and finalized independently of the original instance.- Raises
-
verify(signature)¶ Finalize the current context and securely compare digest to
signature.- Parameters
signature (bytes) – The bytes to compare the current digest against.
- Raises
cryptography.exceptions.InvalidSignature – If signature does not match digest
TypeError – This exception is raised if
signatureis notbytes.
-
finalize()¶ Finalize the current context and return the message digest as bytes.
After
finalizehas been called this object can no longer be used andupdate(),copy(),verify()andfinalize()will raise anAlreadyFinalizedexception.- Return bytes
The message digest as bytes.
- Raises