blob: cff2dbf1129f957581e7a19b57997774d1146553 [file] [log] [blame]
Alex Gaynoraf82d5e2013-10-29 17:07:24 -07001.. hazmat::
Paul Kehrer0317b042013-10-28 17:34:27 -05002
3Hash-based Message Authentication Codes
4=======================================
5
Alex Gaynor4658ce12013-10-29 15:26:50 -07006.. currentmodule:: cryptography.hazmat.primitives.hmac
7
Paul Kehrer0317b042013-10-28 17:34:27 -05008.. 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 integrity as well as authenticate a
16message.
17
David Reid6753e392013-11-01 15:32:03 -070018.. class:: HMAC(key, algorithm)
Paul Kehrer0317b042013-10-28 17:34:27 -050019
David Reid6753e392013-11-01 15:32:03 -070020 HMAC objects take a ``key`` and a provider of
21 :class:`~cryptography.hazmat.primitives.interfaces.HashAlgorithm`.
Paul Kehrer50a88152013-10-29 10:46:05 -050022 The ``key`` should be randomly generated bytes and is recommended to be
23 equal in length to the ``digest_size`` of the hash function chosen.
24 You must keep the ``key`` secret.
Paul Kehrer0317b042013-10-28 17:34:27 -050025
Alex Gaynor58ecc8d2013-11-03 21:21:00 -080026 This is an implementation of :rfc:`2104`.
27
Paul Kehrer0317b042013-10-28 17:34:27 -050028 .. doctest::
29
Paul Kehrerbf8962a2013-10-28 17:44:42 -050030 >>> from cryptography.hazmat.primitives import hashes, hmac
David Reid6753e392013-11-01 15:32:03 -070031 >>> h = hmac.HMAC(key, hashes.SHA256())
Paul Kehrer0317b042013-10-28 17:34:27 -050032 >>> h.update(b"message to hash")
David Reid6753e392013-11-01 15:32:03 -070033 >>> h.finalize()
34 '#F\xdaI\x8b"e\xc4\xf1\xbb\x9a\x8fc\xff\xf5\xdex.\xbc\xcd/+\x8a\x86\x1d\x84\'\xc3\xa6\x1d\xd8J'
Paul Kehrer0317b042013-10-28 17:34:27 -050035
Paul Kehrer2824ab72013-10-28 11:06:55 -050036 .. method:: update(msg)
Paul Kehrer0317b042013-10-28 17:34:27 -050037
Paul Kehrer50a88152013-10-29 10:46:05 -050038 :param bytes msg: The bytes to hash and authenticate.
David Reid2cce6182013-11-13 13:49:41 -080039 :raises cryptography.exceptions.AlreadyFinalized: See :meth:`finalize`
Paul Kehrer0317b042013-10-28 17:34:27 -050040
41 .. method:: copy()
42
David Reid2cce6182013-11-13 13:49:41 -080043 Copy this :class:`HMAC` instance, usually so that we may call
44 :meth:`finalize` and get an intermediate digest value while we continue
45 to call :meth:`update` on the original.
46
47 :return: A new instance of :class:`HMAC` which can be updated
48 and finalized independently of the original instance.
49 :raises cryptography.exceptions.AlreadyFinalized: See :meth:`finalize`
Paul Kehrer0317b042013-10-28 17:34:27 -050050
David Reid6753e392013-11-01 15:32:03 -070051 .. method:: finalize()
52
53 Finalize the current context and return the message digest as bytes.
54
David Reid2cce6182013-11-13 13:49:41 -080055 Once ``finalize`` is called this object can no longer be used and
56 :meth:`update`, :meth:`copy`, and :meth:`finalize` will raise
57 :class:`~cryptography.exceptions.AlreadyFinalized`.
Paul Kehrer0317b042013-10-28 17:34:27 -050058
59 :return bytes: The message digest as bytes.
David Reid2cce6182013-11-13 13:49:41 -080060 :raises cryptography.exceptions.AlreadyFinalized: