Added documentation for all hash algorithms

(including for HMAC which, strictly speaking, does not belong with them).

13 files changed, 801 insertions, 302 deletions

diff --git a/lib/Crypto/Hash/HMAC.py b/lib/Crypto/Hash/HMAC.py
index b09cb36..6244db4 100644
--- a/lib/Crypto/Hash/HMAC.py
+++ b/lib/Crypto/Hash/HMAC.py
@@ -31,37 +31,71 @@
 # ===================================================================
 
 
-"""HMAC (Keyed-Hashing for Message Authentication) Python module.
+"""HMAC (Hash-based Message Authentication Code) algorithm
 
-Implements the HMAC algorithm as described by RFC 2104.
+HMAC is a MAC defined in RFC2104_ and FIPS-198_ and constructed using
+a cryptograpic hash algorithm.
+It is usually named *HMAC-X*, where *X* is the hash algorithm; for
+instance *HMAC-SHA1* or *HMAC-MD5*.
 
-This is just a copy of the Python 2.2 HMAC module, modified to work when
-used on versions of Python before 2.2.
+The strength of an HMAC depends on:
+
+ - the strength of the hash algorithm
+ - the length and entropy of the secret key
+
+An example of possible usage is the following:
+
+    >>> from Crypto.Hash import HMAC
+    >>>
+    >>> secret = b'Swordfish'
+    >>> h = HMAC.new(secret)
+    >>> h.update(b'Hello')
+    >>> print h.hexdigest()
+
+.. _RFC2104: http://www.ietf.org/rfc/rfc2104.txt
+.. _FIPS-198: http://csrc.nist.gov/publications/fips/fips198/fips-198a.pdf
 """
 
+# This is just a copy of the Python 2.2 HMAC module, modified to work when
+# used on versions of Python before 2.2.
+
 __revision__ = "$Id$"
 
-__all__ = ['new', 'digest_size']
+__all__ = ['new', 'digest_size', 'HMAC' ]
 
 from Crypto.Util.strxor import strxor_c
 from Crypto.Util.py3compat import *
 
-# The size of the digests returned by HMAC depends on the underlying
-# hashing module used.
+#: The size of the authentication tag produced by the MAC.
+#: It matches the digest size on the underlying
+#: hashing module used.
 digest_size = None
 
 class HMAC:
-    """RFC2104 HMAC class.
-
-    This supports the API for Cryptographic Hash Functions (PEP 247).
-    """
+    """Class that implements HMAC"""
 
+    #: The size of the authentication tag produced by the MAC.
+    #: It matches the digest size on the underlying
+    #: hashing module used.
+    digest_size = None
+    
     def __init__(self, key, msg = None, digestmod = None):
         """Create a new HMAC object.
 
-        key:       key for the keyed hash object.
-        msg:       Initial input for the hash, if provided.
-        digestmod: A module supporting PEP 247. Defaults to the md5 module.
+        :Parameters:
+          key : byte string
+            secret key for the MAC object.
+            It must be long enough to match the expected security level of the
+            MAC. However, there is no benefit in using keys longer than the
+            `digest_size` of the underlying hash algorithm.
+          msg : byte string
+            The very first chunk of the message to authenticate.
+            It is equivalent to an early call to `update()`. Optional.
+        :Parameter digestmod:
+            The hash algorithm the HMAC is based on.
+            Default is `Crypto.Hash.MD5`.
+        :Type digestmod:
+            A hash module or object instantiated from `Crypto.Hash`
         """
         if digestmod is None:
             import MD5
@@ -94,18 +128,34 @@ class HMAC:
         if (msg):
             self.update(msg)
 
-##    def clear(self):
-##        raise NotImplementedError, "clear() method not available in HMAC."
-
     def update(self, msg):
-        """Update this hashing object with the string msg.
+        """Continue authentication of a message by consuming the next chunk of data.
+        
+        Repeated calls are equivalent to a single call with the concatenation
+        of all the arguments. In other words:
+
+           >>> m.update(a); m.update(b)
+           
+        is equivalent to:
+        
+           >>> m.update(a+b)
+
+        :Parameters:
+          msg : byte string
+            The next chunk of the message being authenticated
         """
+ 
         self.inner.update(msg)
 
     def copy(self):
-        """Return a separate copy of this hashing object.
+        """Return a copy ("clone") of the MAC object.
+
+        The copy will have the same internal state as the original MAC
+        object.
+        This can be used to efficiently compute the MAC of strings that
+        share a common initial substring.
 
-        An update to this copy won't affect the original object.
+        :Returns: An `HMAC` object
         """
         other = HMAC(b(""))
         other.digestmod = self.digestmod
@@ -114,32 +164,49 @@ class HMAC:
         return other
 
     def digest(self):
-        """Return the hash value of this hashing object.
-
-        This returns a string containing 8-bit data.  The object is
-        not altered in any way by this function; you can continue
-        updating the object after calling this function.
+        """Return the **binary** (non-printable) MAC of the message that has
+        been authenticated so far.
+
+        This method does not change the state of the MAC object.
+        You can continue updating the object after calling this function.
+        
+        :Return: A byte string of `digest_size` bytes. It may contain non-ASCII
+         characters, including null bytes.
         """
         h = self.outer.copy()
         h.update(self.inner.digest())
         return h.digest()
 
     def hexdigest(self):
-        """Like digest(), but returns a string of hexadecimal digits instead.
+        """Return the **printable** MAC of the message that has been
+        authenticated so far.
+
+        This method does not change the state of the MAC object.
+        
+        :Return: A string of 2* `digest_size` bytes. It contains only
+         hexadecimal ASCII digits.
         """
         return "".join(["%02x" % bord(x)
                   for x in tuple(self.digest())])
 
 def new(key, msg = None, digestmod = None):
-    """Create a new hashing object and return it.
-
-    key: The starting key for the hash.
-    msg: if available, will immediately be hashed into the object's starting
-    state.
-
-    You can now feed arbitrary strings into the object using its update()
-    method, and can ask for the hash value at any time by calling its digest()
-    method.
+    """Create a new HMAC object.
+
+    :Parameters:
+      key : byte string
+        key for the MAC object.
+        It must be long enough to match the expected security level of the
+        MAC. However, there is no benefit in using keys longer than the
+        `digest_size` of the underlying hash algorithm.
+      msg : byte string
+        The very first chunk of the message to authenticate.
+        It is equivalent to an early call to `HMAC.update()`.
+        Optional.
+    :Parameter digestmod:
+        The hash to use to implement the HMAC. Default is `Crypto.Hash.MD5`.
+    :Type digestmod:
+        A hash module or instantiated object from `Crypto.Hash`
+    :Returns: An `HMAC` object
     """
     return HMAC(key, msg, digestmod)
 
diff --git a/lib/Crypto/Hash/MD2.py b/lib/Crypto/Hash/MD2.py
index 953f763..dac959e 100644
--- a/lib/Crypto/Hash/MD2.py
+++ b/lib/Crypto/Hash/MD2.py
@@ -18,32 +18,74 @@
 # SOFTWARE.
 # ===================================================================
 
-__revision__ = "$Id$"
+"""MD2 cryptographic hash algorithm.
 
-__all__ = ['new', 'digest_size']
+MD2 is specified in RFC1319_ and it produces the 128 bit digest of a message.
 
-from Crypto.Util.wrapper import Wrapper
-from Crypto.Util.py3compat import *
+    >>> from Crypto.Hash import MD2
+    >>>
+    >>> h = MD2.new()
+    >>> h.update(b'Hello')
+    >>> print h.hexdigest()
 
-# The OID for MD2 is:
-#
-# id-md2      OBJECT IDENTIFIER ::= {
-# 			iso(1) member-body(2) us(840) rsadsi(113549)
-# 			digestAlgorithm(2) 2
-# 			}
+MD2 stand for Message Digest version 2, and it was invented by Rivest in 1989.
+
+This algorithm is both slow and insecure. Do not use it for new designs.
+
+.. _RFC1319: http://tools.ietf.org/html/rfc1319
+"""
 
-oid = b('\x06\x08\x2a\x86\x48\x86\xf7\x0d\x02\x02')
+_revision__ = "$Id$"
 
-def new(data=b("")):
-    obj = Wrapper(hashFactory, data)
-    obj.oid = oid
-    obj.new = globals()['new']
-    if not hasattr(obj, 'digest_size'):
-        obj.digest_size = digest_size
-    return obj
+__all__ = ['new', 'digest_size', 'MD2Hash' ]
+
+from Crypto.Util.py3compat import *
+from Crypto.Hash.hashalgo import HashAlgo
 
 import Crypto.Hash._MD2 as _MD2
 hashFactory = _MD2
 
-digest_size = 16
+class MD2Hash(HashAlgo):
+    """Class that implements an MD2 hash
+    
+    :undocumented: block_size
+    """
+
+    #: ASN.1 Object identifier (OID)::
+    #:
+    #:  id-md2 OBJECT IDENTIFIER ::= {
+    #:      iso(1) member-body(2) us(840) rsadsi(113549)
+    #:       digestAlgorithm(2) 2
+    #:  }
+    #:
+    #: This value uniquely identifies the MD2 algorithm.
+    oid = b('\x06\x08\x2a\x86\x48\x86\xf7\x0d\x02\x02')
+
+    digest_size = 16
+    block_size = 16
+
+    def __init__(self, data=None):
+        HashAlgo.__init__(self, hashFactory, data)
+
+    def new(self, data=None):
+        return MD2Hash(data)
+
+def new(data=None):
+    """Return a fresh instance of the hash object.
+
+    :Parameters:
+       data : byte string
+        The very first chunk of the message to hash.
+        It is equivalent to an early call to `MD2Hash.update()`.
+        Optional.
+
+    :Return: An `MD2Hash` object
+    """
+    return MD2Hash().new(data)
+
+#: The size of the resulting hash in bytes.
+digest_size = MD2Hash.digest_size
+
+#: The internal block size of the hash algorithm in bytes.
+block_size = MD2Hash.block_size
 
diff --git a/lib/Crypto/Hash/MD4.py b/lib/Crypto/Hash/MD4.py
index 8a9f595..e28a201 100644
--- a/lib/Crypto/Hash/MD4.py
+++ b/lib/Crypto/Hash/MD4.py
@@ -18,31 +18,74 @@
 # SOFTWARE.
 # ===================================================================
 
-__revision__ = "$Id$"
+"""MD4 cryptographic hash algorithm.
 
-__all__ = ['new', 'digest_size']
+MD4 is specified in RFC1320_ and produces the 128 bit digest of a message.
 
-from Crypto.Util.wrapper import Wrapper
-from Crypto.Util.py3compat import *
+    >>> from Crypto.Hash import MD4
+    >>>
+    >>> h = MD4.new()
+    >>> h.update(b'Hello')
+    >>> print h.hexdigest()
 
-# The OID for MD4 is:
-#
-# id-md2      OBJECT IDENTIFIER ::= {
-# 			iso(1) member-body(2) us(840) rsadsi(113549)
-# 			digestAlgorithm(2) 4
-# 			}
+MD4 stand for Message Digest version 4, and it was invented by Rivest in 1990.
+
+This algorithm is insecure. Do not use it for new designs.
+
+.. _RFC1320: http://tools.ietf.org/html/rfc1320
+"""
 
-oid = b('\x06\x08\x2a\x86\x48\x86\xf7\x0d\x02\x04')
+_revision__ = "$Id$"
 
-def new(data=b("")):
-    obj = Wrapper(hashFactory, data)
-    obj.oid = oid
-    obj.new = globals()['new']
-    if not hasattr(obj, 'digest_size'):
-        obj.digest_size = digest_size
-    return obj
+__all__ = ['new', 'digest_size', 'MD4Hash' ]
+
+from Crypto.Util.py3compat import *
+from Crypto.Hash.hashalgo import HashAlgo
 
 import Crypto.Hash._MD4 as _MD4
 hashFactory = _MD4
 
-digest_size = 16
+class MD4Hash(HashAlgo):
+    """Class that implements an MD4 hash
+    
+    :undocumented: block_size
+    """
+
+    #: ASN.1 Object identifier (OID)::
+    #:
+    #:  id-md2 OBJECT IDENTIFIER ::= {
+    #:      iso(1) member-body(2) us(840) rsadsi(113549)
+    #:       digestAlgorithm(2) 4
+    #:  }
+    #:
+    #: This value uniquely identifies the MD4 algorithm.
+    oid = b('\x06\x08\x2a\x86\x48\x86\xf7\x0d\x02\x04')
+
+    digest_size = 16
+    block_size = 64
+
+    def __init__(self, data=None):
+        HashAlgo.__init__(self, hashFactory, data)
+
+    def new(self, data=None):
+        return MD4Hash(data)
+
+def new(data=None):
+    """Return a fresh instance of the hash object.
+
+    :Parameters:
+       data : byte string
+        The very first chunk of the message to hash.
+        It is equivalent to an early call to `MD4Hash.update()`.
+        Optional.
+
+    :Return: A `MD4Hash` object
+    """
+    return MD4Hash().new(data)
+
+#: The size of the resulting hash in bytes.
+digest_size = MD4Hash.digest_size
+
+#: The internal block size of the hash algorithm in bytes.
+block_size = MD4Hash.block_size
+
diff --git a/lib/Crypto/Hash/MD5.py b/lib/Crypto/Hash/MD5.py
index 91e5da7..e77c787 100644
--- a/lib/Crypto/Hash/MD5.py
+++ b/lib/Crypto/Hash/MD5.py
@@ -18,30 +18,29 @@
 # SOFTWARE.
 # ===================================================================
 
-# Just use the MD5 module from the Python standard library
+"""MD5 cryptographic hash algorithm.
 
-__revision__ = "$Id$"
+MD5 is specified in RFC1321_ and produces the 128 bit digest of a message.
 
-__all__ = ['new', 'digest_size']
+    >>> from Crypto.Hash import MD5
+    >>>
+    >>> h = MD5.new()
+    >>> h.update(b'Hello')
+    >>> print h.hexdigest()
 
-from Crypto.Util.wrapper import Wrapper
-from Crypto.Util.py3compat import *
+MD4 stand for Message Digest version 5, and it was invented by Rivest in 1991.
 
-# The OID for MD5 is:
-#
-# id-md5      OBJECT IDENTIFIER ::= {
-#       iso(1) member-body(2) us(840) rsadsi(113549)
-#       digestAlgorithm(2) 5
-#         }
-oid = b('\x06\x08\x2a\x86\x48\x86\xf7\x0d\x02\x05')
-
-def new(data=b("")):
-    obj = Wrapper(hashFactory, data)
-    obj.oid = oid
-    obj.new = globals()['new']
-    if not hasattr(obj, 'digest_size'):
-        obj.digest_size = digest_size
-    return obj
+This algorithm is insecure. Do not use it for new designs.
+
+.. _RFC1321: http://tools.ietf.org/html/rfc1321 
+"""
+
+_revision__ = "$Id$"
+
+__all__ = ['new', 'digest_size', 'MD5Hash' ]
+
+from Crypto.Util.py3compat import *
+from Crypto.Hash.hashalgo import HashAlgo
 
 try:
     # The md5 module is deprecated in Python 2.6, so use hashlib when possible.
@@ -52,4 +51,47 @@ except ImportError:
     import md5
     hashFactory = md5
 
-digest_size = 16
+class MD5Hash(HashAlgo):
+    """Class that implements an MD5 hash
+    
+    :undocumented: block_size
+    """
+
+    #: ASN.1 Object identifier (OID)::
+    #:
+    #:  id-md5      OBJECT IDENTIFIER ::= {
+    #:      iso(1) member-body(2) us(840) rsadsi(113549)
+    #:       digestAlgorithm(2) 5
+    #:  }
+    #:
+    #: This value uniquely identifies the MD5 algorithm.
+    oid = b('\x06\x08\x2a\x86\x48\x86\xf7\x0d\x02\x05')
+
+    digest_size = 16
+    block_size = 64
+
+    def __init__(self, data=None):
+        HashAlgo.__init__(self, hashFactory, data)
+
+    def new(self, data=None):
+        return MD5Hash(data)
+
+def new(data=None):
+    """Return a fresh instance of the hash object.
+
+    :Parameters:
+       data : byte string
+        The very first chunk of the message to hash.
+        It is equivalent to an early call to `MD5Hash.update()`.
+        Optional.
+
+    :Return: A `MD5Hash` object
+    """
+    return MD5Hash().new(data)
+
+#: The size of the resulting hash in bytes.
+digest_size = MD5Hash.digest_size
+
+#: The internal block size of the hash algorithm in bytes.
+block_size = MD5Hash.block_size
+
diff --git a/lib/Crypto/Hash/RIPEMD.py b/lib/Crypto/Hash/RIPEMD.py
index 4a6c7bf..33099cb 100644
--- a/lib/Crypto/Hash/RIPEMD.py
+++ b/lib/Crypto/Hash/RIPEMD.py
@@ -18,33 +18,77 @@
 # SOFTWARE.
 # ===================================================================
 
-__revision__ = "$Id$"
+"""RIPEMD-160 cryptographic hash algorithm.
 
-__all__ = ['new', 'digest_size']
+RIPEMD-160_ produces the 160 bit digest of a message.
 
-from Crypto.Util.wrapper import Wrapper
-from Crypto.Util.py3compat import *
+    >>> from Crypto.Hash import RIPEMD
+    >>>
+    >>> h = RIPEMD.new()
+    >>> h.update(b'Hello')
+    >>> print h.hexdigest()
 
-#
-# See http://homes.esat.kuleuven.be/~bosselae/ripemd160.html#More
-#
-# id-ripemd160      	OBJECT IDENTIFIER ::= {
-# 				iso(1) identified-organization(3) teletrust(36)
-# 				algorithm(3) hashAlgorithm(2) ripemd160(1)
-# 				}
+RIPEMD-160 stands for RACE Integrity Primitives Evaluation Message Digest
+with a 160 bit digest. It was invented by Dobbertin, Bosselaers, and Preneel.
+
+This algorithm is considered secure, although it has not been scrutinized as
+extensively as SHA-1. Moreover, it provides an informal security level of just
+80bits.
 
-oid = b("\x06\x05\x2b\x24\x03\x02\x01")
+.. _RIPEMD-160: http://homes.esat.kuleuven.be/~bosselae/ripemd160.html
+"""
 
-def new(data=b("")):
-    obj = Wrapper(hashFactory, data)
-    obj.oid = oid
-    obj.new = globals()['new']
-    if not hasattr(obj, 'digest_size'):
-        obj.digest_size = digest_size
-    return obj
+_revision__ = "$Id$"
+
+__all__ = ['new', 'digest_size', 'RIPEMD160Hash' ]
+
+from Crypto.Util.py3compat import *
+from Crypto.Hash.hashalgo import HashAlgo
 
 import Crypto.Hash._RIPEMD160 as _RIPEMD160
 hashFactory = _RIPEMD160
 
-digest_size = 20
+class RIPEMD160Hash(HashAlgo):
+    """Class that implements a RIPMD-160 hash
+    
+    :undocumented: block_size
+    """
+
+    #: ASN.1 Object identifier (OID)::
+    #:
+    #:  id-ripemd160 OBJECT IDENTIFIER ::= {
+    #:      iso(1) identified-organization(3) teletrust(36)
+    #:       algorithm(3) hashAlgorithm(2) ripemd160(1)
+    #:  }
+    #:
+    #: This value uniquely identifies the RIPMD-160 algorithm.
+    oid = b("\x06\x05\x2b\x24\x03\x02\x01")
+
+    digest_size = 20
+    block_size = 64
+
+    def __init__(self, data=None):
+        HashAlgo.__init__(self, hashFactory, data)
+
+    def new(self, data=None):
+        return RIPEMD160Hash(data)
+
+def new(data=None):
+    """Return a fresh instance of the hash object.
+
+    :Parameters:
+       data : byte string
+        The very first chunk of the message to hash.
+        It is equivalent to an early call to `RIPEMD160Hash.update()`.
+        Optional.
+
+    :Return: A `RIPEMD160Hash` object
+    """
+    return RIPEMD160Hash().new(data)
+
+#: The size of the resulting hash in bytes.
+digest_size = RIPEMD160Hash.digest_size
+
+#: The internal block size of the hash algorithm in bytes.
+block_size = RIPEMD160Hash.block_size
 
diff --git a/lib/Crypto/Hash/SHA.py b/lib/Crypto/Hash/SHA.py
index e9cd118..0bc5917 100644
--- a/lib/Crypto/Hash/SHA.py
+++ b/lib/Crypto/Hash/SHA.py
@@ -18,30 +18,29 @@
 # SOFTWARE.
 # ===================================================================
 
-# Just use the SHA module from the Python standard library
+"""SHA-1 cryptographic hash algorithm.
 
-__revision__ = "$Id$"
+SHA-1_ produces the 160 bit digest of a message.
 
-__all__ = ['new', 'digest_size']
+    >>> from Crypto.Hash import SHA
+    >>>
+    >>> h = SHA.new()
+    >>> h.update(b'Hello')
+    >>> print h.hexdigest()
 
-from Crypto.Util.py3compat import *
-from Crypto.Util.wrapper import Wrapper
+*SHA* stands for Secure Hash Algorithm.
 
-# The OID for SHA-1 is:
-#
-# id-sha1    OBJECT IDENTIFIER ::= {
-#          iso(1) identified-organization(3) oiw(14) secsig(3)
-#          algorithms(2) 26
-#      }
-oid = b('\x06\x05\x2b\x0e\x03\x02\x1a')
-
-def new(data=b("")):
-    obj = Wrapper(hashFactory, data)
-    obj.oid = oid
-    obj.new = globals()['new']
-    if not hasattr(obj, 'digest_size'):
-        obj.digest_size = digest_size
-    return obj
+This algorithm is not considered secure. Do not use it for new designs.
+
+.. _SHA-1: http://csrc.nist.gov/publications/fips/fips180-2/fips180-2.pdf
+"""
+
+_revision__ = "$Id$"
+
+__all__ = ['new', 'digest_size', 'SHA1Hash' ]
+
+from Crypto.Util.py3compat import *
+from Crypto.Hash.hashalgo import HashAlgo
 
 try:
     # The sha module is deprecated in Python 2.6, so use hashlib when possible.
@@ -52,5 +51,48 @@ except ImportError:
     import sha
     hashFactory = sha
 
-digest_size = 20
-block_size = 64
+class SHA1Hash(HashAlgo):
+    """Class that implements a SHA-1 hash
+    
+    :undocumented: block_size
+    """
+
+    #: ASN.1 Object identifier (OID)::
+    #:
+    #:  id-sha1    OBJECT IDENTIFIER ::= {
+    #:      iso(1) identified-organization(3) oiw(14) secsig(3)
+    #:       algorithms(2) 26
+    #:  }
+    #:
+    #: This value uniquely identifies the SHA-1 algorithm.
+    oid = b('\x06\x05\x2b\x0e\x03\x02\x1a')
+
+    digest_size = 20
+    block_size = 64
+
+    def __init__(self, data=None):
+        HashAlgo.__init__(self, hashFactory, data)
+
+    def new(self, data=None):
+        return SHA1Hash(data)
+
+def new(data=None):
+    """Return a fresh instance of the hash object.
+
+    :Parameters:
+       data : byte string
+        The very first chunk of the message to hash.
+        It is equivalent to an early call to `SHA1Hash.update()`.
+        Optional.
+
+    :Return: A `SHA1Hash` object
+    """
+    return SHA1Hash().new(data)
+
+#: The size of the resulting hash in bytes.
+digest_size = SHA1Hash.digest_size
+
+#: The internal block size of the hash algorithm in bytes.
+block_size = SHA1Hash.block_size
+
+
diff --git a/lib/Crypto/Hash/SHA224.py b/lib/Crypto/Hash/SHA224.py
index 872ed81..959b56d 100644
--- a/lib/Crypto/Hash/SHA224.py
+++ b/lib/Crypto/Hash/SHA224.py
@@ -18,31 +18,28 @@
 # SOFTWARE.
 # ===================================================================
 
-# Just use the SHA module from the Python standard library
+"""SHA-224 cryptographic hash algorithm.
 
-__revision__ = "$Id$"
+SHA-224 belongs to the SHA-2_ family of cryptographic hashes.
+It produces the 224 bit digest of a message.
 
-__all__ = ['new', 'digest_size']
+    >>> from Crypto.Hash import SHA224
+    >>>
+    >>> h = SHA224.new()
+    >>> h.update(b'Hello')
+    >>> print h.hexdigest()
 
-from Crypto.Util.wrapper import Wrapper
-from Crypto.Util.py3compat import *
+*SHA* stands for Secure Hash Algorithm.
 
-# The OID for SHA-224 is:
-#
-# id-sha224    OBJECT IDENTIFIER ::= {
-#			joint-iso-itu-t(2)
-#			country(16) us(840) organization(1) gov(101) csor(3)
-#			nistalgorithm(4) hashalgs(2) 4
-#		}
-oid = b('\x06\x09\x60\x86\x48\x01\x65\x03\x04\x02\x04')
-
-def new(data=b("")):
-    obj = Wrapper(hashFactory, data)
-    obj.oid = oid
-    obj.new = globals()['new']
-    if not hasattr(obj, 'digest_size'):
-        obj.digest_size = digest_size
-    return obj
+.. _SHA-2: http://csrc.nist.gov/publications/fips/fips180-2/fips180-2.pdf
+"""
+
+_revision__ = "$Id$"
+
+__all__ = ['new', 'digest_size', 'SHA224Hash' ]
+
+from Crypto.Util.py3compat import *
+from Crypto.Hash.hashalgo import HashAlgo
 
 try:
     import hashlib
@@ -52,5 +49,47 @@ except ImportError:
     from Crypto.Hash import _SHA224
     hashFactory = _SHA224
 
-digest_size = 28
-block_size = 64
+class SHA224Hash(HashAlgo):
+    """Class that implements a SHA-224 hash
+    
+    :undocumented: block_size
+    """
+
+    #: ASN.1 Object identifier (OID)::
+    #:
+    #:  id-sha224    OBJECT IDENTIFIER ::= {
+    #:      joint-iso-itu-t(2) country(16) us(840) organization(1) gov(101) csor(3)
+    #:      nistalgorithm(4) hashalgs(2) 4
+    #:  }
+    #:
+    #: This value uniquely identifies the SHA-224 algorithm.
+    oid = b('\x06\x09\x60\x86\x48\x01\x65\x03\x04\x02\x04')
+
+    digest_size = 28
+    block_size = 64
+
+    def __init__(self, data=None):
+        HashAlgo.__init__(self, hashFactory, data)
+
+    def new(self, data=None):
+        return SHA224Hash(data)
+
+def new(data=None):
+    """Return a fresh instance of the hash object.
+
+    :Parameters:
+       data : byte string
+        The very first chunk of the message to hash.
+        It is equivalent to an early call to `SHA224Hash.update()`.
+        Optional.
+
+    :Return: A `SHA224Hash` object
+    """
+    return SHA224Hash().new(data)
+
+#: The size of the resulting hash in bytes.
+digest_size = SHA224Hash.digest_size
+
+#: The internal block size of the hash algorithm in bytes.
+block_size = SHA224Hash.block_size
+
diff --git a/lib/Crypto/Hash/SHA256.py b/lib/Crypto/Hash/SHA256.py
index f583ed9..b0a99b3 100644
--- a/lib/Crypto/Hash/SHA256.py
+++ b/lib/Crypto/Hash/SHA256.py
@@ -18,29 +18,28 @@
 # SOFTWARE.
 # ===================================================================
 
-__revision__ = "$Id$"
+"""SHA-256 cryptographic hash algorithm.
 
-__all__ = ['new', 'digest_size']
+SHA-256 belongs to the SHA-2_ family of cryptographic hashes.
+It produces the 256 bit digest of a message.
 
-from Crypto.Util.wrapper import Wrapper
-from Crypto.Util.py3compat import *
+    >>> from Crypto.Hash import SHA256
+    >>>
+    >>> h = SHA256.new()
+    >>> h.update(b'Hello')
+    >>> print h.hexdigest()
 
-# The OID for SHA-256 is:
-#
-# id-sha256    OBJECT IDENTIFIER ::= {
-# 			joint-iso-itu-t(2) country(16) us(840) organization(1)
-# 			gov(101) csor(3) nistalgorithm(4) hashalgs(2) 1
-# 			}
-#
-oid = b('\x06\x09\x60\x86\x48\x01\x65\x03\x04\x02\x01')
+*SHA* stands for Secure Hash Algorithm.
+
+.. _SHA-2: http://csrc.nist.gov/publications/fips/fips180-2/fips180-2.pdf
+"""
 
-def new(data=b("")):
-    obj = Wrapper(hashFactory, data)
-    obj.oid = oid
-    obj.new = globals()['new']
-    if not hasattr(obj, 'digest_size'):
-        obj.digest_size = digest_size
-    return obj
+_revision__ = "$Id$"
+
+__all__ = ['new', 'digest_size', 'SHA256Hash' ]
+
+from Crypto.Util.py3compat import *
+from Crypto.Hash.hashalgo import HashAlgo
 
 try:
     import hashlib
@@ -50,6 +49,47 @@ except ImportError:
     from Crypto.Hash import _SHA256
     hashFactory = _SHA256
 
-digest_size = 32
-block_size = 64
+class SHA256Hash(HashAlgo):
+    """Class that implements a SHA-256 hash
+    
+    :undocumented: block_size
+    """
+
+    #: ASN.1 Object identifier (OID)::
+    #:
+    #:  id-sha256    OBJECT IDENTIFIER ::= {
+    #: 	    joint-iso-itu-t(2) country(16) us(840) organization(1)
+    #: 	     gov(101) csor(3) nistalgorithm(4) hashalgs(2) 1
+    #:  }
+    #:
+    #: This value uniquely identifies the SHA-256 algorithm.
+    oid = b('\x06\x09\x60\x86\x48\x01\x65\x03\x04\x02\x01')
+
+    digest_size = 32
+    block_size = 64
+
+    def __init__(self, data=None):
+        HashAlgo.__init__(self, hashFactory, data)
+
+    def new(self, data=None):
+        return SHA256Hash(data)
+
+def new(data=None):
+    """Return a fresh instance of the hash object.
+
+    :Parameters:
+       data : byte string
+        The very first chunk of the message to hash.
+        It is equivalent to an early call to `SHA256Hash.update()`.
+        Optional.
+
+    :Return: A `SHA256Hash` object
+    """
+    return SHA256Hash().new(data)
+
+#: The size of the resulting hash in bytes.
+digest_size = SHA256Hash.digest_size
+
+#: The internal block size of the hash algorithm in bytes.
+block_size = SHA256Hash.block_size
 
diff --git a/lib/Crypto/Hash/SHA384.py b/lib/Crypto/Hash/SHA384.py
index 1549e8e..3490b02 100644
--- a/lib/Crypto/Hash/SHA384.py
+++ b/lib/Crypto/Hash/SHA384.py
@@ -18,31 +18,28 @@
 # SOFTWARE.
 # ===================================================================
 
-# Just use the SHA module from the Python standard library
+"""SHA-384 cryptographic hash algorithm.
 
-__revision__ = "$Id$"
+SHA-384 belongs to the SHA-2_ family of cryptographic hashes.
+It produces the 384 bit digest of a message.
 
-__all__ = ['new', 'digest_size']
+    >>> from Crypto.Hash import SHA384
+    >>>
+    >>> h = SHA384.new()
+    >>> h.update(b'Hello')
+    >>> print h.hexdigest()
 
-from Crypto.Util.wrapper import Wrapper
-from Crypto.Util.py3compat import *
+*SHA* stands for Secure Hash Algorithm.
 
-# The OID for SHA-384 is:
-#
-# id-sha384    OBJECT IDENTIFIER ::= {
-#			joint-iso-itu-t(2)
-#			country(16) us(840) organization(1) gov(101) csor(3)
-#			nistalgorithm(4) hashalgs(2) 2
-#		}
-oid = b('\x06\x09\x60\x86\x48\x01\x65\x03\x04\x02\x02')
-
-def new(data=b("")):
-    obj = Wrapper(hashFactory, data)
-    obj.oid = oid
-    obj.new = globals()['new']
-    if not hasattr(obj, 'digest_size'):
-        obj.digest_size = digest_size
-    return obj
+.. _SHA-2: http://csrc.nist.gov/publications/fips/fips180-2/fips180-2.pdf
+"""
+
+_revision__ = "$Id$"
+
+__all__ = ['new', 'digest_size', 'SHA384Hash' ]
+
+from Crypto.Util.py3compat import *
+from Crypto.Hash.hashalgo import HashAlgo
 
 try:
     import hashlib
@@ -52,6 +49,48 @@ except ImportError:
     from Crypto.Hash import _SHA384
     hashFactory = _SHA384
 
-digest_size = 48 
-block_size = 128
+class SHA384Hash(HashAlgo):
+    """Class that implements a SHA-384 hash
+    
+    :undocumented: block_size
+    """
+
+    #: ASN.1 Object identifier (OID)::
+    #:
+    #:  id-sha384    OBJECT IDENTIFIER ::= {
+    #:      joint-iso-itu-t(2) country(16) us(840) organization(1) gov(101) csor(3)
+    #:	     nistalgorithm(4) hashalgs(2) 2
+    #:  }
+    #:
+    #: This value uniquely identifies the SHA-384 algorithm.
+    oid = b('\x06\x09\x60\x86\x48\x01\x65\x03\x04\x02\x02')
+
+    digest_size = 48
+    block_size = 128
+
+    def __init__(self, data=None):
+        HashAlgo.__init__(self, hashFactory, data)
+
+    def new(self, data=None):
+        return SHA384Hash(data)
+
+def new(data=None):
+    """Return a fresh instance of the hash object.
+
+    :Parameters:
+       data : byte string
+        The very first chunk of the message to hash.
+        It is equivalent to an early call to `SHA384Hash.update()`.
+        Optional.
+
+    :Return: A `SHA384Hash` object
+    """
+    return SHA384Hash().new(data)
+
+#: The size of the resulting hash in bytes.
+digest_size = SHA384Hash.digest_size
+
+#: The internal block size of the hash algorithm in bytes.
+block_size = SHA384Hash.block_size
+
 
diff --git a/lib/Crypto/Hash/SHA512.py b/lib/Crypto/Hash/SHA512.py
index 182ec74..d57548d 100644
--- a/lib/Crypto/Hash/SHA512.py
+++ b/lib/Crypto/Hash/SHA512.py
@@ -18,31 +18,28 @@
 # SOFTWARE.
 # ===================================================================
 
-# Just use the SHA module from the Python standard library
+"""SHA-512 cryptographic hash algorithm.
 
-__revision__ = "$Id$"
+SHA-512 belongs to the SHA-2_ family of cryptographic hashes.
+It produces the 512 bit digest of a message.
 
-__all__ = ['new', 'digest_size']
+    >>> from Crypto.Hash import SHA512
+    >>>
+    >>> h = SHA512.new()
+    >>> h.update(b'Hello')
+    >>> print h.hexdigest()
 
-from Crypto.Util.wrapper import Wrapper
-from Crypto.Util.py3compat import *
+*SHA* stands for Secure Hash Algorithm.
 
-# The OID for SHA-512 is:
-#
-# id-sha512    OBJECT IDENTIFIER ::= {
-#			joint-iso-itu-t(2)
-#			country(16) us(840) organization(1) gov(101) csor(3)
-#			nistalgorithm(4) hashalgs(2) 3
-#		}
-oid = b('\x06\x09\x60\x86\x48\x01\x65\x03\x04\x02\x03')
-
-def new(data=b("")):
-    obj = Wrapper(hashFactory, data)
-    obj.oid = oid
-    obj.new = globals()['new']
-    if not hasattr(obj, 'digest_size'):
-        obj.digest_size = digest_size
-    return obj
+.. _SHA-2: http://csrc.nist.gov/publications/fips/fips180-2/fips180-2.pdf
+"""
+
+_revision__ = "$Id$"
+
+__all__ = ['new', 'digest_size', 'SHA512Hash' ]
+
+from Crypto.Util.py3compat import *
+from Crypto.Hash.hashalgo import HashAlgo
 
 try:
     import hashlib
@@ -52,6 +49,47 @@ except ImportError:
     from Crypto.Hash import _SHA512
     hashFactory = _SHA512
 
-digest_size = 64
-block_size = 128
+class SHA512Hash(HashAlgo):
+    """Class that implements a SHA-512 hash
+    
+    :undocumented: block_size
+    """
+
+    #: ASN.1 Object identifier (OID)::
+    #:
+    #:  id-sha512    OBJECT IDENTIFIER ::= {
+    #:	    joint-iso-itu-t(2)
+    #:	    country(16) us(840) organization(1) gov(101) csor(3) nistalgorithm(4) hashalgs(2) 3
+    #:  }
+    #:
+    #: This value uniquely identifies the SHA-512 algorithm.
+    oid = b('\x06\x09\x60\x86\x48\x01\x65\x03\x04\x02\x03')
+
+    digest_size = 64
+    block_size = 128
+
+    def __init__(self, data=None):
+        HashAlgo.__init__(self, hashFactory, data)
+
+    def new(self, data=None):
+        return SHA512Hash(data)
+
+def new(data=None):
+    """Return a fresh instance of the hash object.
+
+    :Parameters:
+       data : byte string
+        The very first chunk of the message to hash.
+        It is equivalent to an early call to `SHA512Hash.update()`.
+        Optional.
+
+    :Return: A `SHA512Hash` object
+    """
+    return SHA512Hash().new(data)
+
+#: The size of the resulting hash in bytes.
+digest_size = SHA512Hash.digest_size
+
+#: The internal block size of the hash algorithm in bytes.
+block_size = SHA512Hash.block_size
 
diff --git a/lib/Crypto/Hash/__init__.py b/lib/Crypto/Hash/__init__.py
index f704b51..4582c66 100644
--- a/lib/Crypto/Hash/__init__.py
+++ b/lib/Crypto/Hash/__init__.py
@@ -20,39 +20,33 @@
 
 """Hashing algorithms
 
-Hash functions take arbitrary strings as input, and produce an output
-of fixed size that is dependent on the input; it should never be
-possible to derive the input data given only the hash function's
-output.  Hash functions can be used simply as a checksum, or, in
+Hash functions take arbitrary binary strings as input, and produce a random-like output
+of fixed size that is dependent on the input; it should be practically infeasible 
+to derive the original input data given only the hash function's
+output. In other words, the hash function is *one-way*.
+
+It should also not be practically feasible to find a second piece of data
+(a *second pre-image*) whose hash is the same as the original message
+(*weak collision resistance*).
+
+Finally, it should not be feasible to find two arbitrary messages with the
+same hash (*strong collision resistance*).
+
+The output of the hash function is called the *digest* of the input message.
+In general, the security of a hash function is related to the length of the
+digest. If the digest is *n* bits long, its security level is roughly comparable
+to the the one offered by an *n/2* bit encryption algorithm.
+
+Hash functions can be used simply as a integrity check, or, in
 association with a public-key algorithm, can be used to implement
 digital signatures.
 
-The hashing modules here all support the interface described in PEP
-247, "API for Cryptographic Hash Functions".
-
-Submodules:
-
-Crypto.Hash.HMAC
- RFC 2104. Keyed-Hashing for Message Authentication.
-Crypto.Hash.MD2
- RFC1319. Rivest's Message Digest algorithm, with a 128 bit digest. This algorithm is both slow and insecure.
-Crypto.Hash.MD4
- RFC1320. Rivest's Message Digest algorithm, with a 128 bit digest. This algorithm is insecure.
-Crypto.Hash.MD5
- RFC1321. Rivest's Message Digest algorithm, with a 128 bit digest. This algorithm is insecure.
-Crypto.Hash.RIPEMD
- RACE Integrity Primitives Evaluation Message Digest algorithm, with a 160 bit digest.
-Crypto.Hash.SHA
- Secure Hash Algorithm 1 (SHA-1), with a 160 bit digest. Published in FIPS PUB 180-1/2/3.
-Crypto.Hash.SHA224
- Secure Hash Algorithm 2 (SHA-2 family), with a 224 bit digest. Published in FIPS PUB 180-2/3.
-Crypto.Hash.SHA256
- Secure Hash Algorithm 2 (SHA-2 family), with a 256 bit digest. Published in FIPS PUB 180-2/3.
-Crypto.Hash.SHA384
- Secure Hash Algorithm 2 (SHA-2 family), with a 384 bit digest. Published in FIPS PUB 180-2/3.
-Crypto.Hash.SHA512
- Secure Hash Algorithm 2 (SHA-2 family), with a 512 bit digest. Published in FIPS PUB 180-2/3.
+The hashing modules here all support the interface described in `PEP
+247`_ , "API for Cryptographic Hash Functions". 
+
+.. _`PEP 247` : http://www.python.org/dev/peps/pep-0247/
 
+:undocumented: _MD2, _MD4, _RIPEMD160, _SHA224, _SHA256, _SHA384, _SHA512
 """
 
 __all__ = ['HMAC', 'MD2', 'MD4', 'MD5', 'RIPEMD', 'SHA',
diff --git a/lib/Crypto/Hash/hashalgo.py b/lib/Crypto/Hash/hashalgo.py
new file mode 100644
index 0000000..b38b3a6
--- /dev/null
+++ b/lib/Crypto/Hash/hashalgo.py
@@ -0,0 +1,116 @@
+# -*- coding: utf-8 -*-
+#
+# ===================================================================
+# The contents of this file are dedicated to the public domain.  To
+# the extent that dedication to the public domain is not available,
+# everyone is granted a worldwide, perpetual, royalty-free,
+# non-exclusive license to exercise all rights associated with the
+# contents of this file for any purpose whatsoever.
+# No rights are reserved.
+#
+# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+# EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+# MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+# NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS
+# BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN
+# ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN
+# CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+# SOFTWARE.
+# ===================================================================
+
+from binascii import hexlify
+
+class HashAlgo:
+    """A generic class for an abstract cryptographic hash algorithm.
+    
+    :undocumented: block_size
+    """
+
+    #: The size of the resulting hash in bytes.
+    digest_size = None
+    #: The internal block size of the hash algorithm in bytes.
+    block_size = None
+
+    def __init__(self, hashFactory, data=None):
+        """Initialize the hash object.
+
+        :Parameters:
+         hashFactory : callable
+            An object that will generate the actual hash implementation.
+            *hashFactory* must have a *new()* method, or must be directly
+            callable.
+         data : byte string
+            The very first chunk of the message to hash.
+            It is equivalent to an early call to `update()`.
+        """
+        if hasattr(hashFactory, 'new'):
+            self._hash = hashFactory.new()
+        else:
+            self._hash = hashFactory()
+        if data:
+            self.update(data)
+
+    def update(self, data):
+        """Continue hashing of a message by consuming the next chunk of data.
+        
+        Repeated calls are equivalent to a single call with the concatenation
+        of all the arguments. In other words:
+
+           >>> m.update(a); m.update(b)
+           
+        is equivalent to:
+        
+           >>> m.update(a+b)
+
+        :Parameters:
+          data : byte string
+            The next chunk of the message being hashed.
+        """
+        return self._hash.update(data)
+
+    def digest(self):
+        """Return the **binary** (non-printable) digest of the message that has been hashed so far.
+
+        This method does not change the state of the hash object.
+        You can continue updating the object after calling this function.
+        
+        :Return: A byte string of `digest_size` bytes. It may contain non-ASCII
+         characters, including null bytes.
+        """
+        return self._hash.digest()
+
+    def hexdigest(self):
+        """Return the **printable** digest of the message that has been hashed so far.
+
+        This method does not change the state of the hash object.
+        
+        :Return: A string of 2* `digest_size` characters. It contains only
+         hexadecimal ASCII digits.
+        """
+        return self._hash.hexdigest()
+
+    def copy(self):
+        """Return a copy ("clone") of the hash object.
+
+        The copy will have the same internal state as the original hash
+        object.
+        This can be used to efficiently compute the digests of strings that
+        share a common initial substring.
+
+        :Return: A hash object of the same type
+        """
+        return self._hash.copy()
+
+    def new(self, data=None):
+        """Return a fresh instance of the hash object.
+
+        Unlike the `copy` method, the internal state of the object is empty.
+
+        :Parameters:
+          data : byte string
+            The next chunk of the message being hashed.
+
+        :Return: A hash object of the same type
+        """
+        pass
+
diff --git a/lib/Crypto/Util/wrapper.py b/lib/Crypto/Util/wrapper.py
deleted file mode 100644
index 1090fc7..0000000
--- a/lib/Crypto/Util/wrapper.py
+++ /dev/null
@@ -1,47 +0,0 @@
-#
-#   wrapper.py: Small class to wrap an object, instantiated from a class
-#       or generated by a module.
-#
-# ===================================================================
-# The contents of this file are dedicated to the public domain.  To
-# the extent that dedication to the public domain is not available,
-# everyone is granted a worldwide, perpetual, royalty-free,
-# non-exclusive license to exercise all rights associated with the
-# contents of this file for any purpose whatsoever.
-# No rights are reserved.
-#
-# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
-# EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
-# MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
-# NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS
-# BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN
-# ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN
-# CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
-# SOFTWARE.
-# ===================================================================
-#
-
-__all__ = [ 'Wrapper' ]
-
-class Wrapper:
-    '''
-    Wrapper for an object, instantiated from a class
-    or from a call to a new() function in a module.
-    '''
-    def __init__(self, wrapped, *args):
-        """
-        wrapped is either a class or a module with a new() function.
-        """
-        if hasattr(wrapped, 'new'):
-            self._wrapped = wrapped.new(*args)
-        else:
-            self._wrapped = wrapped(*args)
-    
-    def __getattr__(self, name):
-        try:
-            return getattr(getattr(self,'_wrapped'),name)
-        except AttributeError:
-            if hasattr(self, name):
-                return getattr(self,name)
-            raise
-