1.. hazmat::
2
3Hash-based message authentication codes (HMAC)
4==============================================
5
6.. currentmodule:: cryptography.hazmat.primitives.hmac
7
8.. testsetup::
9
10    import binascii
11    key = binascii.unhexlify(b"0" * 32)
12
13Hash-based message authentication codes (or HMACs) are a tool for calculating
14message authentication codes using a cryptographic hash function coupled with a
15secret key. You can use an HMAC to verify both the integrity and authenticity
16of a message.
17
18.. class:: HMAC(key, algorithm, backend)
19
20    HMAC objects take a ``key`` and a
21    :class:`~cryptography.hazmat.primitives.hashes.HashAlgorithm` instance.
22    The ``key`` should be :doc:`randomly generated bytes </random-numbers>` and
23    is recommended to be equal in length to the ``digest_size`` of the hash
24    function chosen. You must keep the ``key`` secret.
25
26    This is an implementation of :rfc:`2104`.
27
28    .. doctest::
29
30        >>> from cryptography.hazmat.backends import default_backend
31        >>> from cryptography.hazmat.primitives import hashes, hmac
32        >>> h = hmac.HMAC(key, hashes.SHA256(), backend=default_backend())
33        >>> h.update(b"message to hash")
34        >>> h.finalize()
35        b'#F\xdaI\x8b"e\xc4\xf1\xbb\x9a\x8fc\xff\xf5\xdex.\xbc\xcd/+\x8a\x86\x1d\x84\'\xc3\xa6\x1d\xd8J'
36
37    If the backend doesn't support the requested ``algorithm`` an
38    :class:`~cryptography.exceptions.UnsupportedAlgorithm` exception will be
39    raised.
40
41    If ``algorithm`` isn't a
42    :class:`~cryptography.hazmat.primitives.hashes.HashAlgorithm` instance
43    then ``TypeError`` will be raised.
44
45    To check that a given signature is correct use the :meth:`verify` method.
46    You will receive an exception if the signature is wrong:
47
48    .. doctest::
49
50        >>> h = hmac.HMAC(key, hashes.SHA256(), backend=default_backend())
51        >>> h.update(b"message to hash")
52        >>> h.verify(b"an incorrect signature")
53        Traceback (most recent call last):
54        ...
55        cryptography.exceptions.InvalidSignature: Signature did not match digest.
56
57    :param key: Secret key as ``bytes``.
58    :type key: :term:`bytes-like`
59    :param algorithm: An
60        :class:`~cryptography.hazmat.primitives.hashes.HashAlgorithm`
61        instance such as those described in
62        :ref:`Cryptographic Hashes <cryptographic-hash-algorithms>`.
63    :param backend: An
64        :class:`~cryptography.hazmat.backends.interfaces.HMACBackend`
65        instance.
66
67    :raises cryptography.exceptions.UnsupportedAlgorithm: This is raised if the
68        provided ``backend`` does not implement
69        :class:`~cryptography.hazmat.backends.interfaces.HMACBackend`
70
71    .. method:: update(msg)
72
73        :param msg: The bytes to hash and authenticate.
74        :type msg: :term:`bytes-like`
75        :raises cryptography.exceptions.AlreadyFinalized: See :meth:`finalize`
76        :raises TypeError: This exception is raised if ``msg`` is not ``bytes``.
77
78    .. method:: copy()
79
80        Copy this :class:`HMAC` instance, usually so that we may call
81        :meth:`finalize` to get an intermediate digest value while we continue
82        to call :meth:`update` on the original instance.
83
84        :return: A new instance of :class:`HMAC` that can be updated
85            and finalized independently of the original instance.
86        :raises cryptography.exceptions.AlreadyFinalized: See :meth:`finalize`
87
88    .. method:: verify(signature)
89
90        Finalize the current context and securely compare digest to
91        ``signature``.
92
93        :param bytes signature: The bytes to compare the current digest
94                                against.
95        :raises cryptography.exceptions.AlreadyFinalized: See :meth:`finalize`
96        :raises cryptography.exceptions.InvalidSignature: If signature does not
97                                                          match digest
98        :raises TypeError: This exception is raised if ``signature`` is not
99                           ``bytes``.
100
101    .. method:: finalize()
102
103        Finalize the current context and return the message digest as bytes.
104
105        After ``finalize`` has been called this object can no longer be used
106        and :meth:`update`, :meth:`copy`, :meth:`verify` and :meth:`finalize`
107        will raise an :class:`~cryptography.exceptions.AlreadyFinalized`
108        exception.
109
110        :return bytes: The message digest as bytes.
111        :raises cryptography.exceptions.AlreadyFinalized:
112