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¶
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 key and a HashAlgorithm provider. The key should be randomly generated bytes 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 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() '#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 algorithm an UnsupportedAlgorithm exception will be raised.
If algorithm isn’t a HashAlgorithm provider 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(), 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) – Secret key as bytes.
- algorithm – An HashAlgorithm provider such as those described in Cryptographic Hashes.
- backend – An HMACBackend provider.
Raises cryptography.exceptions.UnsupportedAlgorithm: This is raised if the provided backend does not implement HMACBackend
- update(msg)¶
Parameters: msg (bytes) – 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 call finalize() to get an intermediate digest value while we continue to call update() on the original instance.
Returns: 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.
Parameters: signature (bytes) – The bytes to compare the current digest against.
Raises: - cryptography.exceptions.AlreadyFinalized – See finalize()
- cryptography.exceptions.InvalidSignature – If signature does not match digest
- 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 AlreadyFinalized exception.
Return bytes: The message digest as bytes. Raises cryptography.exceptions.AlreadyFinalized: