Merge pull request #200 from dreid/primitive-hashes

[WIP] Reduce the surface of the primitive hash interface.

7 files changed, 139 insertions, 83 deletions

diff --git a/.coveragerc b/.coveragerc
index b891cb7c..20e3224e 100644
--- a/.coveragerc
+++ b/.coveragerc
@@ -4,3 +4,4 @@ branch = True
 [report]
 exclude_lines =
     @abc.abstractmethod
+    @abc.abstractproperty
diff --git a/cryptography/hazmat/primitives/hashes.py b/cryptography/hazmat/primitives/hashes.py
index 3ccb59d1..bdad5e16 100644
--- a/cryptography/hazmat/primitives/hashes.py
+++ b/cryptography/hazmat/primitives/hashes.py
@@ -13,89 +13,94 @@
 
 from __future__ import absolute_import, division, print_function
 
-import abc
+import six
 
-import binascii
+from cryptography.hazmat.primitives import interfaces
 
-import six
 
+@interfaces.register(interfaces.HashContext)
+class Hash(object):
+    def __init__(self, algorithm, backend=None, ctx=None):
+        if not isinstance(algorithm, interfaces.HashAlgorithm):
+            raise TypeError("Expected instance of interfaces.HashAlgorithm.")
+        self.algorithm = algorithm
 
-class BaseHash(six.with_metaclass(abc.ABCMeta)):
-    def __init__(self, data=None, backend=None, ctx=None):
         if backend is None:
             from cryptography.hazmat.bindings import _default_backend
             backend = _default_backend
+
         self._backend = backend
+
         if ctx is None:
-            self._ctx = self._backend.hashes.create_ctx(self)
+            self._ctx = self._backend.hashes.create_ctx(self.algorithm)
         else:
             self._ctx = None
 
-        if data is not None:
-            self.update(data)
-
     def update(self, data):
         if isinstance(data, six.text_type):
             raise TypeError("Unicode-objects must be encoded before hashing")
         self._backend.hashes.update_ctx(self._ctx, data)
 
     def copy(self):
-        return self.__class__(backend=self._backend, ctx=self._copy_ctx())
-
-    def digest(self):
-        return self._backend.hashes.finalize_ctx(self._copy_ctx(),
-                                                 self.digest_size)
-
-    def hexdigest(self):
-        return str(binascii.hexlify(self.digest()).decode("ascii"))
+        return self.__class__(self.algorithm, backend=self._backend,
+                              ctx=self._backend.hashes.copy_ctx(self._ctx))
 
-    def _copy_ctx(self):
-        return self._backend.hashes.copy_ctx(self._ctx)
+    def finalize(self):
+        return self._backend.hashes.finalize_ctx(self._ctx,
+                                                 self.algorithm.digest_size)
 
 
-class SHA1(BaseHash):
+@interfaces.register(interfaces.HashAlgorithm)
+class SHA1(object):
     name = "sha1"
     digest_size = 20
     block_size = 64
 
 
-class SHA224(BaseHash):
+@interfaces.register(interfaces.HashAlgorithm)
+class SHA224(object):
     name = "sha224"
     digest_size = 28
     block_size = 64
 
 
-class SHA256(BaseHash):
+@interfaces.register(interfaces.HashAlgorithm)
+class SHA256(object):
     name = "sha256"
     digest_size = 32
     block_size = 64
 
 
-class SHA384(BaseHash):
+@interfaces.register(interfaces.HashAlgorithm)
+class SHA384(object):
     name = "sha384"
     digest_size = 48
     block_size = 128
 
 
-class SHA512(BaseHash):
+@interfaces.register(interfaces.HashAlgorithm)
+class SHA512(object):
     name = "sha512"
     digest_size = 64
     block_size = 128
 
 
-class RIPEMD160(BaseHash):
+@interfaces.register(interfaces.HashAlgorithm)
+class RIPEMD160(object):
     name = "ripemd160"
     digest_size = 20
     block_size = 64
 
 
-class Whirlpool(BaseHash):
+@interfaces.register(interfaces.HashAlgorithm)
+class Whirlpool(object):
     name = "whirlpool"
     digest_size = 64
     block_size = 64
 
 
-class MD5(BaseHash):
+@interfaces.register(interfaces.HashAlgorithm)
+class MD5(object):
     name = "md5"
     digest_size = 16
     block_size = 64
diff --git a/cryptography/hazmat/primitives/interfaces.py b/cryptography/hazmat/primitives/interfaces.py
index 217490fd..ebf5e31e 100644
--- a/cryptography/hazmat/primitives/interfaces.py
+++ b/cryptography/hazmat/primitives/interfaces.py
@@ -59,3 +59,49 @@ class PaddingContext(six.with_metaclass(abc.ABCMeta)):
         """
         finalize return bytes
         """
+
+
+class HashAlgorithm(six.with_metaclass(abc.ABCMeta)):
+    @abc.abstractproperty
+    def name(self):
+        """
+        A string naming this algorithm. (ex. sha256, md5)
+        """
+
+    @abc.abstractproperty
+    def digest_size(self):
+        """
+        The size of the resulting digest in bytes.
+        """
+
+    @abc.abstractproperty
+    def block_size(self):
+        """
+        The internal block size of the hash algorithm in bytes.
+        """
+
+
+class HashContext(six.with_metaclass(abc.ABCMeta)):
+    @abc.abstractproperty
+    def algorithm(self):
+        """
+        A HashAlgorithm that will be used by this context.
+        """
+
+    @abc.abstractmethod
+    def update(self, data):
+        """
+        hash data as bytes
+        """
+
+    @abc.abstractmethod
+    def finalize(self):
+        """
+        finalize this copy of the hash and return the digest as bytes.
+        """
+
+    @abc.abstractmethod
+    def copy(self):
+        """
+        return a HashContext that is a copy of the current context.
+        """
diff --git a/docs/hazmat/primitives/cryptographic-hashes.rst b/docs/hazmat/primitives/cryptographic-hashes.rst
index c780dcb0..a939998d 100644
--- a/docs/hazmat/primitives/cryptographic-hashes.rst
+++ b/docs/hazmat/primitives/cryptographic-hashes.rst
@@ -5,21 +5,27 @@ Message Digests
 
 .. currentmodule:: cryptography.hazmat.primitives.hashes
 
-.. class:: BaseHash(data=None)
+.. class:: Hash(algorithm)
 
-    Abstract base class that implements a common interface for all hash
-    algorithms that follow here.
+    A cryptographic hash function takes an arbitrary block of data and
+    calculates a fixed-size bit string (a digest), such that different data
+    results (with a high probability) in different digests.
 
-    If ``data`` is provided ``update(data)`` is called upon construction.
+    This is an implementation of
+    :class:`cryptography.hazmat.primitives.interfaces.HashContext` meant to
+    be used with
+    :class:`cryptography.hazmat.primitives.interfaces.HashAlgorithm`
+    implementations to provide an incremental interface to calculating
+    various message digests.
 
     .. doctest::
 
         >>> from cryptography.hazmat.primitives import hashes
-        >>> digest = hashes.SHA256()
+        >>> digest = hashes.Hash(hashes.SHA256())
         >>> digest.update(b"abc")
         >>> digest.update(b"123")
-        >>> digest.hexdigest()
-        '6ca13d52ca70c883e0f0bb101e425a89e8624de51db2d2392593af6a84118090'
+        >>> digest.finalize()
+        'l\xa1=R\xcap\xc8\x83\xe0\xf0\xbb\x10\x1eBZ\x89\xe8bM\xe5\x1d\xb2\xd29%\x93\xafj\x84\x11\x80\x90'
 
     .. method:: update(data)
 
@@ -29,13 +35,13 @@ Message Digests
 
         :return: a new instance of this object with a copied internal state.
 
-    .. method:: digest()
+    .. method:: finalize()
+        Finalize the current context and return the message digest as bytes.
 
-        :return bytes: The message digest as bytes.
+        Once ``finalize`` is called this object can no longer be used.
 
-    .. method:: hexdigest()
+        :return bytes: The message digest as bytes.
 
-        :return str: The message digest as hex.
 
 SHA-1
 ~~~~~
diff --git a/tests/hazmat/primitives/test_hash_vectors.py b/tests/hazmat/primitives/test_hash_vectors.py
index 5c3e72d4..fca839c7 100644
--- a/tests/hazmat/primitives/test_hash_vectors.py
+++ b/tests/hazmat/primitives/test_hash_vectors.py
@@ -29,7 +29,7 @@ class TestSHA1(object):
             "SHA1LongMsg.rsp",
             "SHA1ShortMsg.rsp",
         ],
-        hashes.SHA1,
+        hashes.SHA1(),
         only_if=lambda backend: backend.hashes.supported(hashes.SHA1),
         skip_message="Does not support SHA1",
     )
@@ -43,7 +43,7 @@ class TestSHA224(object):
             "SHA224LongMsg.rsp",
             "SHA224ShortMsg.rsp",
         ],
-        hashes.SHA224,
+        hashes.SHA224(),
         only_if=lambda backend: backend.hashes.supported(hashes.SHA224),
         skip_message="Does not support SHA224",
     )
@@ -57,7 +57,7 @@ class TestSHA256(object):
             "SHA256LongMsg.rsp",
             "SHA256ShortMsg.rsp",
         ],
-        hashes.SHA256,
+        hashes.SHA256(),
         only_if=lambda backend: backend.hashes.supported(hashes.SHA256),
         skip_message="Does not support SHA256",
     )
@@ -71,7 +71,7 @@ class TestSHA384(object):
             "SHA384LongMsg.rsp",
             "SHA384ShortMsg.rsp",
         ],
-        hashes.SHA384,
+        hashes.SHA384(),
         only_if=lambda backend: backend.hashes.supported(hashes.SHA384),
         skip_message="Does not support SHA384",
     )
@@ -85,7 +85,7 @@ class TestSHA512(object):
             "SHA512LongMsg.rsp",
             "SHA512ShortMsg.rsp",
         ],
-        hashes.SHA512,
+        hashes.SHA512(),
         only_if=lambda backend: backend.hashes.supported(hashes.SHA512),
         skip_message="Does not support SHA512",
     )
@@ -98,13 +98,13 @@ class TestRIPEMD160(object):
         [
             "ripevectors.txt",
         ],
-        hashes.RIPEMD160,
+        hashes.RIPEMD160(),
         only_if=lambda backend: backend.hashes.supported(hashes.RIPEMD160),
         skip_message="Does not support RIPEMD160",
     )
 
     test_RIPEMD160_long_string = generate_long_string_hash_test(
-        hashes.RIPEMD160,
+        hashes.RIPEMD160(),
         "52783243c1697bdbe16d37f97f68f08325dc1528",
         only_if=lambda backend: backend.hashes.supported(hashes.RIPEMD160),
         skip_message="Does not support RIPEMD160",
@@ -118,13 +118,13 @@ class TestWhirlpool(object):
         [
             "iso-test-vectors.txt",
         ],
-        hashes.Whirlpool,
+        hashes.Whirlpool(),
         only_if=lambda backend: backend.hashes.supported(hashes.Whirlpool),
         skip_message="Does not support Whirlpool",
     )
 
     test_whirlpool_long_string = generate_long_string_hash_test(
-        hashes.Whirlpool,
+        hashes.Whirlpool(),
         ("0c99005beb57eff50a7cf005560ddf5d29057fd86b2"
          "0bfd62deca0f1ccea4af51fc15490eddc47af32bb2b"
          "66c34ff9ad8c6008ad677f77126953b226e4ed8b01"),
@@ -140,7 +140,7 @@ class TestMD5(object):
         [
             "rfc-1321.txt",
         ],
-        hashes.MD5,
+        hashes.MD5(),
         only_if=lambda backend: backend.hashes.supported(hashes.MD5),
         skip_message="Does not support MD5",
     )
diff --git a/tests/hazmat/primitives/test_hashes.py b/tests/hazmat/primitives/test_hashes.py
index 797fe4ff..07ab2489 100644
--- a/tests/hazmat/primitives/test_hashes.py
+++ b/tests/hazmat/primitives/test_hashes.py
@@ -25,39 +25,36 @@ from cryptography.hazmat.primitives import hashes
 from .utils import generate_base_hash_test
 
 
-class TestBaseHash(object):
-    def test_base_hash_reject_unicode(self, backend):
-        m = hashes.SHA1(backend=backend)
+class TestHashContext(object):
+    def test_hash_reject_unicode(self, backend):
+        m = hashes.Hash(hashes.SHA1(), backend=backend)
         with pytest.raises(TypeError):
             m.update(six.u("\u00FC"))
 
-    def test_base_hash_hexdigest_string_type(self, backend):
-        m = hashes.SHA1(backend=backend, data=b"")
-        assert isinstance(m.hexdigest(), str)
-
-
-class TestCopyHash(object):
     def test_copy_backend_object(self):
         pretend_hashes = pretend.stub(copy_ctx=lambda a: "copiedctx")
         pretend_backend = pretend.stub(hashes=pretend_hashes)
         pretend_ctx = pretend.stub()
-        h = hashes.SHA1(backend=pretend_backend, ctx=pretend_ctx)
+        h = hashes.Hash(hashes.SHA1(), backend=pretend_backend,
+                        ctx=pretend_ctx)
         assert h._backend is pretend_backend
         assert h.copy()._backend is h._backend
 
-
-class TestDefaultBackendSHA1(object):
     def test_default_backend_creation(self):
         """
         This test assumes the presence of SHA1 in the default backend.
         """
-        h = hashes.SHA1()
+        h = hashes.Hash(hashes.SHA1())
         assert h._backend is _default_backend
 
+    def test_hash_algorithm_instance(self):
+        with pytest.raises(TypeError):
+            hashes.Hash(hashes.SHA1)
+
 
 class TestSHA1(object):
     test_SHA1 = generate_base_hash_test(
-        hashes.SHA1,
+        hashes.SHA1(),
         digest_size=20,
         block_size=64,
         only_if=lambda backend: backend.hashes.supported(hashes.SHA1),
@@ -67,7 +64,7 @@ class TestSHA1(object):
 
 class TestSHA224(object):
     test_SHA224 = generate_base_hash_test(
-        hashes.SHA224,
+        hashes.SHA224(),
         digest_size=28,
         block_size=64,
         only_if=lambda backend: backend.hashes.supported(hashes.SHA224),
@@ -77,7 +74,7 @@ class TestSHA224(object):
 
 class TestSHA256(object):
     test_SHA256 = generate_base_hash_test(
-        hashes.SHA256,
+        hashes.SHA256(),
         digest_size=32,
         block_size=64,
         only_if=lambda backend: backend.hashes.supported(hashes.SHA256),
@@ -87,7 +84,7 @@ class TestSHA256(object):
 
 class TestSHA384(object):
     test_SHA384 = generate_base_hash_test(
-        hashes.SHA384,
+        hashes.SHA384(),
         digest_size=48,
         block_size=128,
         only_if=lambda backend: backend.hashes.supported(hashes.SHA384),
@@ -97,7 +94,7 @@ class TestSHA384(object):
 
 class TestSHA512(object):
     test_SHA512 = generate_base_hash_test(
-        hashes.SHA512,
+        hashes.SHA512(),
         digest_size=64,
         block_size=128,
         only_if=lambda backend: backend.hashes.supported(hashes.SHA512),
@@ -107,7 +104,7 @@ class TestSHA512(object):
 
 class TestRIPEMD160(object):
     test_RIPEMD160 = generate_base_hash_test(
-        hashes.RIPEMD160,
+        hashes.RIPEMD160(),
         digest_size=20,
         block_size=64,
         only_if=lambda backend: backend.hashes.supported(hashes.RIPEMD160),
@@ -117,7 +114,7 @@ class TestRIPEMD160(object):
 
 class TestWhirlpool(object):
     test_Whirlpool = generate_base_hash_test(
-        hashes.Whirlpool,
+        hashes.Whirlpool(),
         digest_size=64,
         block_size=64,
         only_if=lambda backend: backend.hashes.supported(hashes.Whirlpool),
@@ -127,7 +124,7 @@ class TestWhirlpool(object):
 
 class TestMD5(object):
     test_MD5 = generate_base_hash_test(
-        hashes.MD5,
+        hashes.MD5(),
         digest_size=16,
         block_size=64,
         only_if=lambda backend: backend.hashes.supported(hashes.MD5),
diff --git a/tests/hazmat/primitives/utils.py b/tests/hazmat/primitives/utils.py
index c51fef52..efc5fbf0 100644
--- a/tests/hazmat/primitives/utils.py
+++ b/tests/hazmat/primitives/utils.py
@@ -4,6 +4,7 @@ import os
 import pytest
 
 from cryptography.hazmat.bindings import _ALL_BACKENDS
+from cryptography.hazmat.primitives import hashes
 from cryptography.hazmat.primitives import hmac
 from cryptography.hazmat.primitives.block import BlockCipher
 
@@ -65,26 +66,25 @@ def generate_hash_test(param_loader, path, file_names, hash_cls,
     return test_hash
 
 
-def hash_test(backend, hash_cls, params, only_if, skip_message):
+def hash_test(backend, algorithm, params, only_if, skip_message):
     if only_if is not None and not only_if(backend):
         pytest.skip(skip_message)
     msg = params[0]
     md = params[1]
-    m = hash_cls(backend=backend)
+    m = hashes.Hash(algorithm, backend=backend)
     m.update(binascii.unhexlify(msg))
-    assert m.hexdigest() == md.replace(" ", "").lower()
-    digst = hash_cls(backend=backend, data=binascii.unhexlify(msg)).hexdigest()
-    assert digst == md.replace(" ", "").lower()
+    expected_md = md.replace(" ", "").lower().encode("ascii")
+    assert m.finalize() == binascii.unhexlify(expected_md)
 
 
-def generate_base_hash_test(hash_cls, digest_size, block_size,
+def generate_base_hash_test(algorithm, digest_size, block_size,
                             only_if=None, skip_message=None):
     def test_base_hash(self):
         for backend in _ALL_BACKENDS:
             yield (
                 base_hash_test,
                 backend,
-                hash_cls,
+                algorithm,
                 digest_size,
                 block_size,
                 only_if,
@@ -93,13 +93,14 @@ def generate_base_hash_test(hash_cls, digest_size, block_size,
     return test_base_hash
 
 
-def base_hash_test(backend, digestmod, digest_size, block_size, only_if,
+def base_hash_test(backend, algorithm, digest_size, block_size, only_if,
                    skip_message):
     if only_if is not None and not only_if(backend):
         pytest.skip(skip_message)
-    m = digestmod(backend=backend)
-    assert m.digest_size == digest_size
-    assert m.block_size == block_size
+
+    m = hashes.Hash(algorithm, backend=backend)
+    assert m.algorithm.digest_size == digest_size
+    assert m.algorithm.block_size == block_size
     m_copy = m.copy()
     assert m != m_copy
     assert m._ctx != m_copy._ctx
@@ -120,12 +121,12 @@ def generate_long_string_hash_test(hash_factory, md, only_if=None,
     return test_long_string_hash
 
 
-def long_string_hash_test(backend, hash_factory, md, only_if, skip_message):
+def long_string_hash_test(backend, algorithm, md, only_if, skip_message):
     if only_if is not None and not only_if(backend):
         pytest.skip(skip_message)
-    m = hash_factory(backend=backend)
+    m = hashes.Hash(algorithm, backend=backend)
     m.update(b"a" * 1000000)
-    assert m.hexdigest() == md.lower()
+    assert m.finalize() == binascii.unhexlify(md.lower().encode("ascii"))
 
 
 def generate_hmac_test(param_loader, path, file_names, digestmod,