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 the file \file{md5.doc}). Its use is quite
   6 straightforward:\ use the function \code{new} to create an
   7 \dfn{md5}-object. You can now ``feed'' this object with arbitrary
   8 strings.
   9
  10 At any time you can ask for the ``final'' digest of the object. Internally,
  11 a temporary copy of the object is made and the digest is computed and
  12 returned. Because of the copy, the digest operation is not destructive
  13 for the object. Before a more exact description of the module's use, a small
  14 example will be helpful:
  15 to obtain the digest of the string \code{'abc'}, use \ldots
  16
  17 \bcode\begin{verbatim}
  18 >>> import md5
  19 >>> m = md5.new()
  20 >>> m.update('abc')
  21 >>> m.digest()
  22 '\220\001P\230<\322O\260\326\226?}(\341\177r'
  23 \end{verbatim}\ecode
  24
  25 More condensed:
  26
  27 \bcode\begin{verbatim}
  28 >>> md5.new('abc').digest()
  29 '\220\001P\230<\322O\260\326\226?}(\341\177r'
  30 \end{verbatim}\ecode
  31
  32 \renewcommand{\indexsubitem}{(in module md5)}
  33
  34 \begin{funcdesc}{new}{\optional{arg}}
  35   Create a new md5-object. If \var{arg} is present, an initial
  36   \code{update} method is called with \var{arg} as argument.
  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 this md5-object with the string \var{arg}.
  49 \end{funcdesc}
  50
  51 \begin{funcdesc}{digest}{}
  52 % XXX The following is not quite clear; what does MD5Final do?
  53   Return the \dfn{digest} of this md5-object. Internally, a copy is made
  54   and the \C-function \code{MD5Final} is called. Finally the digest is
  55   returned.
  56 \end{funcdesc}
  57
  58 \begin{funcdesc}{copy}{}
  59   Return a separate copy of this md5-object.  An \code{update} to this
  60   copy won't affect the original object.
  61 \end{funcdesc}