Added documentation for all hash algorithms

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

1 files changed, 63 insertions, 21 deletions

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
+