Merge pull request #130 from reaperhulk/hash-saga-thrilling-conclusion-md5

Hash Saga Part 7 (MD5 support + docs)

5 files changed, 125 insertions, 3 deletions

diff --git a/cryptography/primitives/hashes.py b/cryptography/primitives/hashes.py
index 06d90a90..e8c1f929 100644
--- a/cryptography/primitives/hashes.py
+++ b/cryptography/primitives/hashes.py
@@ -13,20 +13,24 @@
 
 from __future__ import absolute_import, division, print_function
 
+import abc
+
 import binascii
 
+import six
+
 from cryptography.bindings import _default_api
 
 
-class BaseHash(object):
+class BaseHash(six.with_metaclass(abc.ABCMeta)):
     def __init__(self, api=None, ctx=None):
         if api is None:
             api = _default_api
         self._api = api
         self._ctx = self._api.create_hash_context(self) if ctx is None else ctx
 
-    def update(self, string):
-        self._api.update_hash_context(self._ctx, string)
+    def update(self, data):
+        self._api.update_hash_context(self._ctx, data)
 
     def copy(self):
         return self.__class__(ctx=self._copy_ctx())
@@ -82,3 +86,9 @@ class Whirlpool(BaseHash):
     name = "whirlpool"
     digest_size = 64
     block_size = 64
+
+
+class MD5(BaseHash):
+    name = "md5"
+    digest_size = 16
+    block_size = 64
diff --git a/docs/primitives/cryptographic-hashes.rst b/docs/primitives/cryptographic-hashes.rst
new file mode 100644
index 00000000..397e50d7
--- /dev/null
+++ b/docs/primitives/cryptographic-hashes.rst
@@ -0,0 +1,88 @@
+Message Digests
+====================
+
+.. class:: cryptography.primitives.hashes.BaseHash
+
+   Abstract base class that implements a common interface for all hash
+   algorithms that follow here.
+
+    .. method:: update(data)
+
+        :param bytes data The bytes you wish to hash.
+
+    .. method:: copy()
+
+        :return: a new instance of this object with a copied internal state.
+
+    .. method:: digest()
+
+        :return bytes: The message digest as bytes.
+
+    .. method:: hexdigest()
+
+        :return str: The message digest as hex.
+
+SHA-1
+~~~~~
+
+.. attention::
+
+    NIST has deprecated SHA-1 in favor of the SHA-2 variants. New applications
+    are strongly suggested to use SHA-2 over SHA-1.
+
+.. class:: cryptography.primitives.hashes.SHA1()
+
+    SHA-1 is a cryptographic hash function standardized by NIST. It has a
+    160-bit message digest.
+
+SHA-2 Family
+~~~~~~~~~~~~
+
+.. class:: cryptography.primitives.hashes.SHA224()
+
+    SHA-224 is a cryptographic hash function from the SHA-2 family and
+    standardized by NIST. It has a 224-bit message digest.
+
+.. class:: cryptography.primitives.hashes.SHA256()
+
+    SHA-256 is a cryptographic hash function from the SHA-2 family and
+    standardized by NIST. It has a 256-bit message digest.
+
+.. class:: cryptography.primitives.hashes.SHA384()
+
+    SHA-384 is a cryptographic hash function from the SHA-2 family and
+    standardized by NIST. It has a 384-bit message digest.
+
+.. class:: cryptography.primitives.hashes.SHA512()
+
+    SHA-512 is a cryptographic hash function from the SHA-2 family and
+    standardized by NIST. It has a 512-bit message digest.
+
+RIPEMD160
+~~~~~~~~~
+
+.. class:: cryptography.primitives.hashes.RIPEMD160()
+
+    RIPEMD160 is a cryptographic hash function that is part of ISO/IEC
+    10118-3:2004. It has a 160-bit message digest.
+
+Whirlpool
+~~~~~~~~~
+
+.. class:: cryptography.primitives.hashes.Whirlpool()
+
+    Whirlpool is a cryptographic hash function that is part of ISO/IEC
+    10118-3:2004. It has a 512-bit message digest.
+
+MD5
+~~~
+
+.. warning::
+
+    MD5 is a deprecated hash algorithm that has practical known collision
+    attacks. You are strongly discouraged from using it.
+
+.. class:: cryptography.primitives.hashes.MD5()
+
+    MD5 is a deprecated cryptographic hash function. It has a 160-bit message
+    digest and has practical known collision attacks.
diff --git a/docs/primitives/index.rst b/docs/primitives/index.rst
index 1066e30e..c18c62ca 100644
--- a/docs/primitives/index.rst
+++ b/docs/primitives/index.rst
@@ -4,4 +4,5 @@ Primitives
 .. toctree::
     :maxdepth: 1
 
+    cryptographic-hashes
     symmetric-encryption
diff --git a/tests/primitives/test_hash_vectors.py b/tests/primitives/test_hash_vectors.py
index 52c972a3..02ef4dbb 100644
--- a/tests/primitives/test_hash_vectors.py
+++ b/tests/primitives/test_hash_vectors.py
@@ -131,3 +131,16 @@ class TestWhirlpool(object):
         only_if=lambda api: api.supports_hash(hashes.Whirlpool),
         skip_message="Does not support Whirlpool",
     )
+
+
+class TestMD5(object):
+    test_md5 = generate_hash_test(
+        load_hash_vectors_from_file,
+        os.path.join("RFC", "MD5"),
+        [
+            "rfc-1321.txt",
+        ],
+        hashes.MD5,
+        only_if=lambda api: api.supports_hash(hashes.MD5),
+        skip_message="Does not support MD5",
+    )
diff --git a/tests/primitives/test_hashes.py b/tests/primitives/test_hashes.py
index 982fc7cd..901ddabb 100644
--- a/tests/primitives/test_hashes.py
+++ b/tests/primitives/test_hashes.py
@@ -86,3 +86,13 @@ class TestWhirlpool(object):
         only_if=lambda api: api.supports_hash(hashes.Whirlpool),
         skip_message="Does not support Whirlpool",
     )
+
+
+class TestMD5(object):
+    test_MD5 = generate_base_hash_test(
+        hashes.MD5,
+        digest_size=16,
+        block_size=64,
+        only_if=lambda api: api.supports_hash(hashes.MD5),
+        skip_message="Does not support MD5",
+    )