Doc/lib/libmd5.tex

   1 \section{Built-in Module \sectcode{md5}}
   2 \bimodindex{md5}
   3
   4 This module implements the interface to RSA's MD5 message digest
   5 algorithm (see also Internet RFC 1321).  Its use is quite
   6 straightforward:\ use the \code{md5.new()} to create an md5 object.
   7 You can now feed this object with arbitrary strings using the
   8 \code{update()} method, and at any point you can ask it for the
   9 \dfn{digest} (a strong kind of 128-bit checksum,
  10 a.k.a. ``fingerprint'') of the contatenation of the strings fed to it
  11 so far using the \code{digest()} method.
  12
  13 For example, to obtain the digest of the string {\tt"Nobody inspects
  14 the spammish repetition"}:
  15
  16 \bcode\begin{verbatim}
  17 >>> import md5
  18 >>> m = md5.new()
  19 >>> m.update("Nobody inspects")
  20 >>> m.update(" the spammish repetition")
  21 >>> m.digest()
  22 '\273d\234\203\335\036\245\311\331\336\311\241\215\360\377\351'
  23 \end{verbatim}\ecode
  24
  25 More condensed:
  26
  27 \bcode\begin{verbatim}
  28 >>> md5.new("Nobody inspects the spammish repetition").digest()
  29 '\273d\234\203\335\036\245\311\331\336\311\241\215\360\377\351'
  30 \end{verbatim}\ecode
  31
  32 \renewcommand{\indexsubitem}{(in module md5)}
  33
  34 \begin{funcdesc}{new}{\optional{arg}}
  35 Return a new md5 object.  If \var{arg} is present, the method call
  36 \code{update(\var{arg})} is made.
  37 \end{funcdesc}
  38
  39 \begin{funcdesc}{md5}{\optional{arg}}
  40 For backward compatibility reasons, this is an alternative name for the
  41 \code{new()} function.
  42 \end{funcdesc}
  43
  44 An md5 object has the following methods:
  45
  46 \renewcommand{\indexsubitem}{(md5 method)}
  47 \begin{funcdesc}{update}{arg}
  48 Update the md5 object with the string \var{arg}.  Repeated calls are
  49 equivalent to a single call with the concatenation of all the
  50 arguments, i.e.\ \code{m.update(a); m.update(b)} is equivalent to
  51 \code{m.update(a+b)}.
  52 \end{funcdesc}
  53
  54 \begin{funcdesc}{digest}{}
  55 Return the digest of the strings passed to the \code{update()}
  56 method so far.  This is an 8-byte string which may contain
  57 non-\ASCII{} characters, including null bytes.
  58 \end{funcdesc}
  59
  60 \begin{funcdesc}{copy}{}
  61 Return a copy (``clone'') of the md5 object.  This can be used to
  62 efficiently compute the digests of strings that share a common initial
  63 substring.
  64 \end{funcdesc}