Doc/lib/libhmac.tex

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