Doc/library/hmac.rst

   1
   2 :mod:`hmac` --- Keyed-Hashing for Message Authentication
   3 ========================================================
   4
   5 .. module:: hmac
   6    :synopsis: Keyed-Hashing for Message Authentication (HMAC) implementation for Python.
   7 .. moduleauthor:: Gerhard Häring <ghaering@users.sourceforge.net>
   8 .. sectionauthor:: Gerhard Häring <ghaering@users.sourceforge.net>
   9
  10
  11 .. versionadded:: 2.2
  12
  13 This module implements the HMAC algorithm as described by :rfc:`2104`.
  14
  15
  16 .. function:: new(key[, msg[, digestmod]])
  17
  18    Return a new hmac object.  If *msg* is present, the method call ``update(msg)``
  19    is made. *digestmod* is the digest constructor or module for the HMAC object to
  20    use. It defaults to  the :func:`hashlib.md5` constructor.
  21
  22    .. note::
  23
  24       The md5 hash has known weaknesses but remains the default for backwards
  25       compatibility. Choose a better one for your application.
  26
  27 An HMAC object has the following methods:
  28
  29
  30 .. method:: hmac.update(msg)
  31
  32    Update the hmac object with the string *msg*.  Repeated calls are equivalent to
  33    a single call with the concatenation of all the arguments: ``m.update(a);
  34    m.update(b)`` is equivalent to ``m.update(a + b)``.
  35
  36
  37 .. method:: hmac.digest()
  38
  39    Return the digest of the strings passed to the :meth:`update` method so far.
  40    This string will be the same length as the *digest_size* of the digest given to
  41    the constructor.  It may contain non-ASCII characters, including NUL bytes.
  42
  43
  44 .. method:: hmac.hexdigest()
  45
  46    Like :meth:`digest` except the digest is returned as a string twice the length
  47    containing only hexadecimal digits.  This may be used to exchange the value
  48    safely in email or other non-binary environments.
  49
  50
  51 .. method:: hmac.copy()
  52
  53    Return a copy ("clone") of the hmac object.  This can be used to efficiently
  54    compute the digests of strings that share a common initial substring.
  55
  56
  57 .. seealso::
  58
  59    Module :mod:`hashlib`
  60       The Python module providing secure hash functions.
  61