From 7208af47f8b1a34330194709e55e4ef17560cf6a Mon Sep 17 00:00:00 2001
From: "Gregory P. Smith" <greg@mad-scientist.com>
Date: Mon, 22 Aug 2005 18:31:41 +0000
Subject: whoops, missed adding this last night in my hashlib commit

---
 Doc/lib/libhashlib.tex | 114 +++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 114 insertions(+)
 create mode 100644 Doc/lib/libhashlib.tex

diff --git a/Doc/lib/libhashlib.tex b/Doc/lib/libhashlib.tex
new file mode 100644
index 0000000..829849f
--- /dev/null
+++ b/Doc/lib/libhashlib.tex
@@ -0,0 +1,114 @@
+\section{\module{hashlib} ---
+         Secure hashes and message digests}
+
+\declaremodule{builtin}{hashlib}
+\modulesynopsis{Secure hash and message digest algorithms.}
+\moduleauthor{Gregory P. Smith}{greg@users.sourceforge.net}
+\sectionauthor{Gregory P. Smith}{greg@users.sourceforge.net}
+
+\versionadded{2.5}
+
+\index{message digest, MD5}
+\index{secure hash algorithm, SHA1, SHA224, SHA256, SHA384, SHA512}
+
+This module implements a common interface to many different secure hash and
+message digest algorithms.  Included are the FIPS secure hash algorithms SHA1,
+SHA224, SHA256, SHA384, and SHA512 (defined in FIPS 180-2) as well as RSA's MD5
+algorithm (defined in Internet \rfc{1321}).
+The terms secure hash and message digest are interchangable.  Older
+algorithms were called message digests.  The modern term is secure hash.
+
+\warning{Some algorithms have known hash collision weaknesses, see the FAQ at the end.}
+
+There is one constructor method named for each type of \dfn{hash}.  All return
+a hash object with the same simple interface.
+For example: use \function{sha1()} to create a SHA1 hash object.
+You can now feed this object with arbitrary strings using the \method{update()}
+method.  At any point you can ask it for the \dfn{digest} of the concatenation
+of the strings fed to it so far using the \method{digest()} or
+\method{hexdigest()} methods.
+
+Constructors for hash algorithms that are always present in this module are
+\function{md5()}, \function{sha1()}, \function{sha224()}, \function{sha256()},
+\function{sha384()}, and \function{sha512()}.  Additional algorithms may also
+be available depending upon the OpenSSL library python uses on your platform.
+\index{OpenSSL}
+
+For example, to obtain the digest of the string \code{'Nobody inspects
+the spammish repetition'}:
+
+\begin{verbatim}
+>>> import hashlib
+>>> m = hashlib.md5()
+>>> m.update("Nobody inspects")
+>>> m.update(" the spammish repetition")
+>>> m.digest()
+'\xbbd\x9c\x83\xdd\x1e\xa5\xc9\xd9\xde\xc9\xa1\x8d\xf0\xff\xe9'
+\end{verbatim}
+
+More condensed:
+
+\begin{verbatim}
+>>> hashlib.sha224("Nobody inspects the spammish repetition").hexdigest()
+'a4337bc45a8fc544c03f52dc550cd6e1e87021bc896588bd79e901e2'
+\end{verbatim}
+
+A generic \function{new()} constructor that takes the string name of the
+desired algorithm as its first parameter also exists to allow access to the
+above listed hashes as well as any other algorithms that your OpenSSL library
+may offer.  The named constructors are much faster than \function{new()} and
+should be preferred.
+
+Using \function{new()} with an algorithm provided by OpenSSL:
+
+\begin{verbatim}
+>>> h = hashlib.new('ripemd160')
+>>> h.update("Nobody inspects the spammish repetition")
+>>> h.hexdigest()
+'cc4a5ce1b3df48aec5d22d1f16b894a0b894eccc'
+\end{verbatim}
+
+The following values are provided as constant attributes of the hash objects
+returned by the constructors:
+
+\begin{datadesc}{digest_size}
+  The size of the resulting digest in bytes.
+\end{datadesc}
+
+A hash object has the following methods:
+
+\begin{methoddesc}[hash]{update}{arg}
+Update the hash object with the string \var{arg}.  Repeated calls are
+equivalent to a single call with the concatenation of all the
+arguments: \code{m.update(a); m.update(b)} is equivalent to
+\code{m.update(a+b)}.
+\end{methoddesc}
+
+\begin{methoddesc}[hash]{digest}{}
+Return the digest of the strings passed to the \method{update()}
+method so far.  This is a 16-byte string which may contain
+non-\ASCII{} characters, including null bytes.
+\end{methoddesc}
+
+\begin{methoddesc}[hash]{hexdigest}{}
+Like \method{digest()} except the digest is returned as a string of
+double length, containing only hexadecimal digits.  This may 
+be used to exchange the value safely in email or other non-binary
+environments.
+\end{methoddesc}
+
+\begin{methoddesc}[hash]{copy}{}
+Return a copy (``clone'') of the hash object.  This can be used to
+efficiently compute the digests of strings that share a common initial
+substring.
+\end{methoddesc}
+
+\begin{seealso}
+  \seemodule{hmac}{A module to generate message authentication codes using hashes.}
+  \seemodule{base64}{Another way to encode binary hashes for non-binary environments.}
+  \seeurl{http://csrc.nist.gov/publications/fips/fips180-2/fips180-2.pdf}
+  {The FIPS 180-2 publication on Secure Hash Algorithms.}
+  \seeurl{http://www.cryptography.com/cnews/hash.html}
+  {Hash Collision FAQ with information on which algorithms have known issues and
+   what that means regarding their use.}
+\end{seealso}
-- 
cgit v0.12