78 lines
2.7 KiB
TeX
78 lines
2.7 KiB
TeX
\section{\module{sha} ---
|
|
SHA message digest algorithm}
|
|
|
|
\declaremodule{builtin}{sha}
|
|
\modulesynopsis{NIST's secure hash algorithm, SHA.}
|
|
\sectionauthor{Fred L. Drake, Jr.}{fdrake@acm.org}
|
|
|
|
|
|
This module implements the interface to NIST's\index{NIST} secure hash
|
|
algorithm,\index{Secure Hash Algorithm} known as SHA. It is used in
|
|
the same way as the \refmodule{md5} module:\ use \function{new()}
|
|
to create an sha object, then feed this object with arbitrary strings
|
|
using the \method{update()} method, and at any point you can ask it
|
|
for the \dfn{digest} of the concatenation of the strings fed to it
|
|
so far.\index{checksum!SHA} SHA digests are 160 bits instead of
|
|
MD5's 128 bits.
|
|
|
|
|
|
\begin{funcdesc}{new}{\optional{string}}
|
|
Return a new sha object. If \var{string} is present, the method
|
|
call \code{update(\var{string})} is made.
|
|
\end{funcdesc}
|
|
|
|
|
|
The following values are provided as constants in the module and as
|
|
attributes of the sha objects returned by \function{new()}:
|
|
|
|
\begin{datadesc}{blocksize}
|
|
Size of the blocks fed into the hash function; this is always
|
|
\code{1}. This size is used to allow an arbitrary string to be
|
|
hashed.
|
|
\end{datadesc}
|
|
|
|
\begin{datadesc}{digestsize}
|
|
The size of the resulting digest in bytes. This is always
|
|
\code{20}.
|
|
\end{datadesc}
|
|
|
|
|
|
An sha object has the same methods as md5 objects:
|
|
|
|
\begin{methoddesc}[sha]{update}{arg}
|
|
Update the sha object with the string \var{arg}. Repeated calls are
|
|
equivalent to a single call with the concatenation of all the
|
|
arguments, i.e.\ \code{m.update(a); m.update(b)} is equivalent to
|
|
\code{m.update(a+b)}.
|
|
\end{methoddesc}
|
|
|
|
\begin{methoddesc}[sha]{digest}{}
|
|
Return the digest of the strings passed to the \method{update()}
|
|
method so far. This is a 20-byte string which may contain
|
|
non-\ASCII{} characters, including null bytes.
|
|
\end{methoddesc}
|
|
|
|
\begin{methoddesc}[sha]{hexdigest}{}
|
|
Like \method{digest()} except the digest is returned as a string of
|
|
length 40, containing only hexadecimal digits. This may
|
|
be used to exchange the value safely in email or other non-binary
|
|
environments.
|
|
\end{methoddesc}
|
|
|
|
\begin{methoddesc}[sha]{copy}{}
|
|
Return a copy (``clone'') of the sha object. This can be used to
|
|
efficiently compute the digests of strings that share a common initial
|
|
substring.
|
|
\end{methoddesc}
|
|
|
|
\begin{seealso}
|
|
\seetitle[http://csrc.nist.gov/fips/fip180-1.txt]{Secure Hash Standard}{
|
|
The Secure Hash Algorithm is defined by NIST document FIPS
|
|
PUB 180-1:
|
|
\citetitle[http://csrc.nist.gov/fips/fip180-1.txt]{Secure
|
|
Hash Standard}, published in April of 1995. It is
|
|
available online as plain text (at least one diagram was
|
|
omitted) and as PDF at
|
|
\url{http://csrc.nist.gov/fips/fip180-1.pdf}.}
|
|
\end{seealso}
|