[ sf.net patch # 1121611 ]

A new hashlib module to replace the md5 and sha modules.  It adds
support for additional secure hashes such as SHA-256 and SHA-512.  The
hashlib module uses OpenSSL for fast platform optimized
implementations of algorithms when available.  The old md5 and sha
modules still exist as wrappers around hashlib to preserve backwards
compatibility.

7 files changed, 28 insertions, 7 deletions

diff --git a/Doc/ACKS b/Doc/ACKS
index 3f0706694c..2c89e2a482 100644
--- a/Doc/ACKS
+++ b/Doc/ACKS
@@ -164,6 +164,7 @@ Joakim Sernbrant
 Justin Sheehy
 Michael Simcich
 Ionel Simionescu
+Gregory P. Smith
 Roy Smith
 Clay Spence
 Nicholas Spies
diff --git a/Doc/Makefile.deps b/Doc/Makefile.deps
index b3c4dbb9cc..aa843a410c 100644
--- a/Doc/Makefile.deps
+++ b/Doc/Makefile.deps
@@ -202,6 +202,7 @@ LIBFILES= $(MANSTYLES) $(INDEXSTYLES) $(COMMONTEX) \
 	lib/librgbimg.tex \
 	lib/libossaudiodev.tex \
 	lib/libcrypto.tex \
+	lib/libhashlib.tex \
 	lib/libmd5.tex \
 	lib/libsha.tex \
 	lib/libhmac.tex \
diff --git a/Doc/lib/lib.tex b/Doc/lib/lib.tex
index 43fafb165a..bb995d81d6 100644
--- a/Doc/lib/lib.tex
+++ b/Doc/lib/lib.tex
@@ -303,6 +303,7 @@ and how to embed it in other applications.
 
 \input{libcrypto}               % Cryptographic Services
 \input{libhmac}
+\input{libhashlib}
 \input{libmd5}
 \input{libsha}
 
diff --git a/Doc/lib/libhmac.tex b/Doc/lib/libhmac.tex
index 1d49417853..5ca24d1c28 100644
--- a/Doc/lib/libhmac.tex
+++ b/Doc/lib/libhmac.tex
@@ -14,8 +14,10 @@ This module implements the HMAC algorithm as described by \rfc{2104}.
 \begin{funcdesc}{new}{key\optional{, msg\optional{, digestmod}}}
   Return a new hmac object.  If \var{msg} is present, the method call
   \code{update(\var{msg})} is made. \var{digestmod} is the digest
-  module for the HMAC object to use. It defaults to the
-  \refmodule{md5} module.
+  constructor or module for the HMAC object to use. It defaults to 
+  the \code{\refmodule{hashlib}.md5} constructor.  \note{The md5 hash
+  has known weaknesses but remains the default for backwards compatibility.
+  Choose a better one for your application.}
 \end{funcdesc}
 
 An HMAC object has the following methods:
@@ -29,14 +31,14 @@ An HMAC object has the following methods:
 
 \begin{methoddesc}[hmac]{digest}{}
   Return the digest of the strings passed to the \method{update()}
-  method so far.  This is a 16-byte string (for \refmodule{md5}) or a
-  20-byte string (for \refmodule{sha}) which may contain non-\ASCII{}
-  characters, including NUL bytes.
+  method so far.  This string will be the same length as the
+  \var{digest_size} of the digest given to the constructor.  It
+  may contain non-\ASCII{} characters, including NUL bytes.
 \end{methoddesc}
 
 \begin{methoddesc}[hmac]{hexdigest}{}
-  Like \method{digest()} except the digest is returned as a string of
-  length 32 for \refmodule{md5} (40 for \refmodule{sha}), containing
+  Like \method{digest()} except the digest is returned as a string
+  twice the length containing
   only hexadecimal digits.  This may be used to exchange the value
   safely in email or other non-binary environments.
 \end{methoddesc}
@@ -46,3 +48,7 @@ An HMAC object has the following methods:
   efficiently compute the digests of strings that share a common
   initial substring.
 \end{methoddesc}
+
+\begin{seealso}
+  \seemodule{hashlib}{The python module providing secure hash functions.}
+\end{seealso}
diff --git a/Doc/lib/libmd5.tex b/Doc/lib/libmd5.tex
index 6f837b4e89..f6b35c7901 100644
--- a/Doc/lib/libmd5.tex
+++ b/Doc/lib/libmd5.tex
@@ -4,6 +4,7 @@
 \declaremodule{builtin}{md5}
 \modulesynopsis{RSA's MD5 message digest algorithm.}
 
+\deprecated{2.5}{Use the \refmodule{hashlib} module instead.}
 
 This module implements the interface to RSA's MD5 message digest
 \index{message digest, MD5}
diff --git a/Doc/lib/libsha.tex b/Doc/lib/libsha.tex
index 4800b17e6b..6d1da68da8 100644
--- a/Doc/lib/libsha.tex
+++ b/Doc/lib/libsha.tex
@@ -5,6 +5,8 @@
 \modulesynopsis{NIST's secure hash algorithm, SHA.}
 \sectionauthor{Fred L. Drake, Jr.}{fdrake@acm.org}
 
+\deprecated{2.5}{Use the \refmodule{hashlib} module instead.}
+
 
 This module implements the interface to NIST's\index{NIST} secure hash 
 algorithm,\index{Secure Hash Algorithm} known as SHA-1.  SHA-1 is an
diff --git a/Doc/whatsnew/whatsnew25.tex b/Doc/whatsnew/whatsnew25.tex
index 4bd380aa1f..118b4c72a4 100644
--- a/Doc/whatsnew/whatsnew25.tex
+++ b/Doc/whatsnew/whatsnew25.tex
@@ -247,6 +247,15 @@ archive into the current working directory.  It's also possible to set
 a different directory as the extraction target, and to unpack only a
 subset of the archive's members.  (Contributed by Lars Gust\"abel.)
 
+\item A new \module{hashlib} module has been added to replace the
+\module{md5} and \module{sha} modules and adds support for additional
+secure hashes such as SHA-256 and SHA-512.  The \module{hashlib} module
+uses OpenSSL for fast platform optimized implementations of algorithms
+when available.  The old \module{md5} and \module{sha} modules still
+exist as wrappers around hashlib to preserve backwards compatibility.
+
+(Contributed by Gregory P. Smith.)
+
 \end{itemize}