Doc/lib/libmd5.tex

   1 \section{\module{md5} ---
   2          MD5 message digest algorithm}
   3
   4 \declaremodule{builtin}{md5}
   5 \modulesynopsis{RSA's MD5 message digest algorithm.}
   6
   7
   8 This module implements the interface to RSA's MD5 message digest
   9 \index{message digest, MD5}
  10 algorithm (see also Internet \rfc{1321}).  Its use is quite
  11 straightforward:\ use \function{new()} to create an md5 object.
  12 You can now feed this object with arbitrary strings using the
  13 \method{update()} method, and at any point you can ask it for the
  14 \dfn{digest} (a strong kind of 128-bit checksum,
  15 a.k.a. ``fingerprint'') of the concatenation of the strings fed to it
  16 so far using the \method{digest()} method.
  17 \index{checksum!MD5}
  18
  19 For example, to obtain the digest of the string \code{'Nobody inspects
  20 the spammish repetition'}:
  21
  22 \begin{verbatim}
  23 >>> import md5
  24 >>> m = md5.new()
  25 >>> m.update("Nobody inspects")
  26 >>> m.update(" the spammish repetition")
  27 >>> m.digest()
  28 '\xbbd\x9c\x83\xdd\x1e\xa5\xc9\xd9\xde\xc9\xa1\x8d\xf0\xff\xe9'
  29 \end{verbatim}
  30
  31 More condensed:
  32
  33 \begin{verbatim}
  34 >>> md5.new("Nobody inspects the spammish repetition").digest()
  35 '\xbbd\x9c\x83\xdd\x1e\xa5\xc9\xd9\xde\xc9\xa1\x8d\xf0\xff\xe9'
  36 \end{verbatim}
  37
  38 The following values are provided as constants in the module and as
  39 attributes of the md5 objects returned by \function{new()}:
  40
  41 \begin{datadesc}{digest_size}
  42   The size of the resulting digest in bytes.  This is always
  43   \code{16}.
  44 \end{datadesc}
  45
  46 md5 objects support the following methods:
  47
  48 \begin{funcdesc}{new}{\optional{arg}}
  49 Return a new md5 object.  If \var{arg} is present, the method call
  50 \code{update(\var{arg})} is made.
  51 \end{funcdesc}
  52
  53 \begin{funcdesc}{md5}{\optional{arg}}
  54 For backward compatibility reasons, this is an alternative name for the
  55 \function{new()} function.
  56 \end{funcdesc}
  57
  58 An md5 object has the following methods:
  59
  60 \begin{methoddesc}[md5]{update}{arg}
  61 Update the md5 object with the string \var{arg}.  Repeated calls are
  62 equivalent to a single call with the concatenation of all the
  63 arguments: \code{m.update(a); m.update(b)} is equivalent to
  64 \code{m.update(a+b)}.
  65 \end{methoddesc}
  66
  67 \begin{methoddesc}[md5]{digest}{}
  68 Return the digest of the strings passed to the \method{update()}
  69 method so far.  This is a 16-byte string which may contain
  70 non-\ASCII{} characters, including null bytes.
  71 \end{methoddesc}
  72
  73 \begin{methoddesc}[md5]{hexdigest}{}
  74 Like \method{digest()} except the digest is returned as a string of
  75 length 32, containing only hexadecimal digits.  This may
  76 be used to exchange the value safely in email or other non-binary
  77 environments.
  78 \end{methoddesc}
  79
  80 \begin{methoddesc}[md5]{copy}{}
  81 Return a copy (``clone'') of the md5 object.  This can be used to
  82 efficiently compute the digests of strings that share a common initial
  83 substring.
  84 \end{methoddesc}
  85
  86
  87 \begin{seealso}
  88   \seemodule{sha}{Similar module implementing the Secure Hash
  89                   Algorithm (SHA).  The SHA algorithm is considered a
  90                   more secure hash.}
  91 \end{seealso}