1 :mod:`hmac` --- Keyed-Hashing for Message Authentication 2 ======================================================== 3 4 .. module:: hmac 5 :synopsis: Keyed-Hashing for Message Authentication (HMAC) implementation 6 .. moduleauthor:: Gerhard Hring <ghaering (a] users.sourceforge.net> 7 .. sectionauthor:: Gerhard Hring <ghaering (a] users.sourceforge.net> 8 9 10 .. versionadded:: 2.2 11 12 **Source code:** :source:`Lib/hmac.py` 13 14 -------------- 15 16 This module implements the HMAC algorithm as described by :rfc:`2104`. 17 18 19 .. function:: new(key[, msg[, digestmod]]) 20 21 Return a new hmac object. If *msg* is present, the method call ``update(msg)`` 22 is made. *digestmod* is the digest constructor or module for the HMAC object to 23 use. It defaults to the :data:`hashlib.md5` constructor. 24 25 26 An HMAC object has the following methods: 27 28 .. method:: HMAC.update(msg) 29 30 Update the hmac object with the string *msg*. Repeated calls are equivalent to 31 a single call with the concatenation of all the arguments: ``m.update(a); 32 m.update(b)`` is equivalent to ``m.update(a + b)``. 33 34 35 .. method:: HMAC.digest() 36 37 Return the digest of the strings passed to the :meth:`update` method so far. 38 This string will be the same length as the *digest_size* of the digest given to 39 the constructor. It may contain non-ASCII characters, including NUL bytes. 40 41 .. warning:: 42 43 When comparing the output of :meth:`digest` to an externally-supplied 44 digest during a verification routine, it is recommended to use the 45 :func:`compare_digest` function instead of the ``==`` operator 46 to reduce the vulnerability to timing attacks. 47 48 49 .. method:: HMAC.hexdigest() 50 51 Like :meth:`digest` except the digest is returned as a string twice the length 52 containing only hexadecimal digits. This may be used to exchange the value 53 safely in email or other non-binary environments. 54 55 .. warning:: 56 57 When comparing the output of :meth:`hexdigest` to an externally-supplied 58 digest during a verification routine, it is recommended to use the 59 :func:`compare_digest` function instead of the ``==`` operator 60 to reduce the vulnerability to timing attacks. 61 62 63 .. method:: HMAC.copy() 64 65 Return a copy ("clone") of the hmac object. This can be used to efficiently 66 compute the digests of strings that share a common initial substring. 67 68 69 This module also provides the following helper function: 70 71 .. function:: compare_digest(a, b) 72 73 Return ``a == b``. This function uses an approach designed to prevent 74 timing analysis by avoiding content-based short circuiting behaviour, 75 making it appropriate for cryptography. *a* and *b* must both be of the 76 same type: either :class:`unicode` or a :term:`bytes-like object`. 77 78 .. note:: 79 80 If *a* and *b* are of different lengths, or if an error occurs, 81 a timing attack could theoretically reveal information about the 82 types and lengths of *a* and *b*but not their values. 83 84 85 .. versionadded:: 2.7.7 86 87 88 .. seealso:: 89 90 Module :mod:`hashlib` 91 The Python module providing secure hash functions. 92 93
