1:mod:`!hmac` --- Keyed-Hashing for Message Authentication 2========================================================= 3 4.. module:: hmac 5 :synopsis: Keyed-Hashing for Message Authentication (HMAC) implementation 6 7.. moduleauthor:: Gerhard Häring <ghaering@users.sourceforge.net> 8.. sectionauthor:: Gerhard Häring <ghaering@users.sourceforge.net> 9 10**Source code:** :source:`Lib/hmac.py` 11 12-------------- 13 14This module implements the HMAC algorithm as described by :rfc:`2104`. 15 16 17.. function:: new(key, msg=None, digestmod) 18 19 Return a new hmac object. *key* is a bytes or bytearray object giving the 20 secret key. If *msg* is present, the method call ``update(msg)`` is made. 21 *digestmod* is the digest name, digest constructor or module for the HMAC 22 object to use. It may be any name suitable to :func:`hashlib.new`. 23 Despite its argument position, it is required. 24 25 .. versionchanged:: 3.4 26 Parameter *key* can be a bytes or bytearray object. 27 Parameter *msg* can be of any type supported by :mod:`hashlib`. 28 Parameter *digestmod* can be the name of a hash algorithm. 29 30 .. versionchanged:: 3.8 31 The *digestmod* argument is now required. Pass it as a keyword 32 argument to avoid awkwardness when you do not have an initial *msg*. 33 34 35.. function:: digest(key, msg, digest) 36 37 Return digest of *msg* for given secret *key* and *digest*. The 38 function is equivalent to ``HMAC(key, msg, digest).digest()``, but 39 uses an optimized C or inline implementation, which is faster for messages 40 that fit into memory. The parameters *key*, *msg*, and *digest* have 41 the same meaning as in :func:`~hmac.new`. 42 43 CPython implementation detail, the optimized C implementation is only used 44 when *digest* is a string and name of a digest algorithm, which is 45 supported by OpenSSL. 46 47 .. versionadded:: 3.7 48 49 50An HMAC object has the following methods: 51 52.. method:: HMAC.update(msg) 53 54 Update the hmac object with *msg*. Repeated calls are equivalent to a 55 single call with the concatenation of all the arguments: 56 ``m.update(a); m.update(b)`` is equivalent to ``m.update(a + b)``. 57 58 .. versionchanged:: 3.4 59 Parameter *msg* can be of any type supported by :mod:`hashlib`. 60 61 62.. method:: HMAC.digest() 63 64 Return the digest of the bytes passed to the :meth:`update` method so far. 65 This bytes object will be the same length as the *digest_size* of the digest 66 given to the constructor. It may contain non-ASCII bytes, including NUL 67 bytes. 68 69 .. warning:: 70 71 When comparing the output of :meth:`digest` to an externally supplied 72 digest during a verification routine, it is recommended to use the 73 :func:`compare_digest` function instead of the ``==`` operator 74 to reduce the vulnerability to timing attacks. 75 76 77.. method:: HMAC.hexdigest() 78 79 Like :meth:`digest` except the digest is returned as a string twice the 80 length containing only hexadecimal digits. This may be used to exchange the 81 value safely in email or other non-binary environments. 82 83 .. warning:: 84 85 When comparing the output of :meth:`hexdigest` to an externally supplied 86 digest during a verification routine, it is recommended to use the 87 :func:`compare_digest` function instead of the ``==`` operator 88 to reduce the vulnerability to timing attacks. 89 90 91.. method:: HMAC.copy() 92 93 Return a copy ("clone") of the hmac object. This can be used to efficiently 94 compute the digests of strings that share a common initial substring. 95 96 97A hash object has the following attributes: 98 99.. attribute:: HMAC.digest_size 100 101 The size of the resulting HMAC digest in bytes. 102 103.. attribute:: HMAC.block_size 104 105 The internal block size of the hash algorithm in bytes. 106 107 .. versionadded:: 3.4 108 109.. attribute:: HMAC.name 110 111 The canonical name of this HMAC, always lowercase, e.g. ``hmac-md5``. 112 113 .. versionadded:: 3.4 114 115 116.. versionchanged:: 3.10 117 Removed the undocumented attributes ``HMAC.digest_cons``, ``HMAC.inner``, 118 and ``HMAC.outer``. 119 120This module also provides the following helper function: 121 122.. function:: compare_digest(a, b) 123 124 Return ``a == b``. This function uses an approach designed to prevent 125 timing analysis by avoiding content-based short circuiting behaviour, 126 making it appropriate for cryptography. *a* and *b* must both be of the 127 same type: either :class:`str` (ASCII only, as e.g. returned by 128 :meth:`HMAC.hexdigest`), or a :term:`bytes-like object`. 129 130 .. note:: 131 132 If *a* and *b* are of different lengths, or if an error occurs, 133 a timing attack could theoretically reveal information about the 134 types and lengths of *a* and *b*—but not their values. 135 136 .. versionadded:: 3.3 137 138 .. versionchanged:: 3.10 139 140 The function uses OpenSSL's ``CRYPTO_memcmp()`` internally when 141 available. 142 143 144.. seealso:: 145 146 Module :mod:`hashlib` 147 The Python module providing secure hash functions. 148