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   module for the HMAC object to use. It defaults to the
  18   \refmodule{md5} module.
  19 \end{funcdesc}
  20
  21 An HMAC object has the following methods:
  22
  23 \begin{methoddesc}[hmac]{update}{msg}
  24   Update the hmac object with the string \var{msg}.  Repeated calls
  25   are equivalent to a single call with the concatenation of all the
  26   arguments: \code{m.update(a); m.update(b)} is equivalent to
  27   \code{m.update(a + b)}.
  28 \end{methoddesc}
  29
  30 \begin{methoddesc}[hmac]{digest}{}
  31   Return the digest of the strings passed to the \method{update()}
  32   method so far.  This is a 16-byte string (for \refmodule{md5}) or a
  33   20-byte string (for \refmodule{sha}) which may contain non-\ASCII{}
  34   characters, including NUL bytes.
  35 \end{methoddesc}
  36
  37 \begin{methoddesc}[hmac]{hexdigest}{}
  38   Like \method{digest()} except the digest is returned as a string of
  39   length 32 for \refmodule{md5} (40 for \refmodule{sha}), containing
  40   only hexadecimal digits.  This may be used to exchange the value
  41   safely in email or other non-binary environments.
  42 \end{methoddesc}
  43
  44 \begin{methoddesc}[hmac]{copy}{}
  45   Return a copy (``clone'') of the hmac object.  This can be used to
  46   efficiently compute the digests of strings that share a common
  47   initial substring.
  48 \end{methoddesc}