Doc/lib/libsha.tex

   1 \section{\module{sha} ---
   2          SHA message digest algorithm}
   3
   4 \declaremodule{builtin}{sha}
   5 \modulesynopsis{NIST's secure hash algorithm, SHA.}
   6 \sectionauthor{Fred L. Drake, Jr.}{fdrake@acm.org}
   7
   8
   9 This module implements the interface to NIST's\index{NIST} secure hash
  10 algorithm,\index{Secure Hash Algorithm} known as SHA.  It is used in
  11 the same way as the \refmodule{md5} module:\ use the \function{new()}
  12 to create an sha object, then feed this object with arbitrary strings
  13 using the \method{update()} method, and at any point you can ask it
  14 for the \dfn{digest} of the concatenation of the strings fed to it
  15 so far.\index{checksum!SHA}  SHA digests are 160 bits instead of 128
  16 bits.
  17
  18
  19 \begin{funcdesc}{new}{\optional{string}}
  20   Return a new sha object.  If \var{string} is present, the method
  21   call \code{update(\var{string})} is made.
  22 \end{funcdesc}
  23
  24
  25 The following values are provided as constants in the module and as
  26 attributes of the sha objects returned by \function{new()}:
  27
  28 \begin{datadesc}{blocksize}
  29   Size of the blocks fed into the hash function; this is always
  30   \code{1}.  This size is used to allow an arbitrary string to be
  31   hashed.
  32 \end{datadesc}
  33
  34 \begin{datadesc}{digestsize}
  35   The size of the resulting digest in bytes.  This is always
  36   \code{20}.
  37 \end{datadesc}
  38
  39
  40 A sha object has all the methods the md5 objects have, plus one:
  41
  42 \begin{methoddesc}[sha]{hexdigest}{}
  43   Return the digest value as a string of hexadecimal digits.  This may
  44   be used to exchange the value safely in email or other non-binary
  45   environments.
  46 \end{methoddesc}
  47
  48
  49 \begin{seealso}
  50   \seetext{The Secure Hash Algorithm is defined by NIST document FIPS
  51            PUB 180-1: \citetitle{Secure Hash Standard}, published in April
  52            of 1995.  It is available online as plain text at
  53            \url{http://csrc.nist.gov/fips/fip180-1.txt} (at least one
  54            diagram was omitted) and as PostScript at
  55            \url{http://csrc.nist.gov/fips/fip180-1.ps}.}
  56 \end{seealso}