Merge branch 'master' into fernet

3 files changed, 55 insertions, 22 deletions

diff --git a/docs/hazmat/primitives/cryptographic-hashes.rst b/docs/hazmat/primitives/cryptographic-hashes.rst
index c780dcb0..76ca20c0 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,14 @@ Message Digests
 
         :return: a new instance of this object with a copied internal state.
 
-    .. method:: digest()
+    .. method:: finalize()
 
-        :return bytes: The message digest as bytes.
+        Finalize the current context and return 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/docs/hazmat/primitives/hmac.rst b/docs/hazmat/primitives/hmac.rst
index 44cc29fa..301d72d5 100644
--- a/docs/hazmat/primitives/hmac.rst
+++ b/docs/hazmat/primitives/hmac.rst
@@ -15,10 +15,10 @@ message authentication codes using a cryptographic hash function coupled with a
 secret key. You can use an HMAC to verify integrity as well as authenticate a
 message.
 
-.. class:: HMAC(key, msg=None, digestmod=None)
+.. class:: HMAC(key, algorithm)
 
-    HMAC objects take a ``key``, a hash class derived from
-    :class:`~cryptography.primitives.hashes.BaseHash`, and optional message.
+    HMAC objects take a ``key`` and a provider of
+    :class:`~cryptography.hazmat.primitives.interfaces.HashAlgorithm`.
     The ``key`` should be randomly generated bytes and is recommended to be
     equal in length to the ``digest_size`` of the hash function chosen.
     You must keep the ``key`` secret.
@@ -26,10 +26,10 @@ message.
     .. doctest::
 
         >>> from cryptography.hazmat.primitives import hashes, hmac
-        >>> h = hmac.HMAC(key, digestmod=hashes.SHA256)
+        >>> h = hmac.HMAC(key, hashes.SHA256())
         >>> h.update(b"message to hash")
-        >>> h.hexdigest()
-        '...'
+        >>> h.finalize()
+        '#F\xdaI\x8b"e\xc4\xf1\xbb\x9a\x8fc\xff\xf5\xdex.\xbc\xcd/+\x8a\x86\x1d\x84\'\xc3\xa6\x1d\xd8J'
 
     .. method:: update(msg)
 
@@ -39,11 +39,10 @@ message.
 
         :return: a new instance of this object with a copied internal state.
 
-    .. method:: digest()
+    .. method:: finalize()
 
-        :return bytes: The message digest as bytes.
-
-    .. method:: hexdigest()
+        Finalize the current context and return the message digest as bytes.
 
-        :return str: The message digest as hex.
+        Once ``finalize`` is called this object can no longer be used.
 
+        :return bytes: The message digest as bytes.
diff --git a/docs/hazmat/primitives/symmetric-encryption.rst b/docs/hazmat/primitives/symmetric-encryption.rst
index 1e047b7c..5852dc21 100644
--- a/docs/hazmat/primitives/symmetric-encryption.rst
+++ b/docs/hazmat/primitives/symmetric-encryption.rst
@@ -107,6 +107,33 @@ Ciphers
                       ``56`` bits long), they can simply be concatenated to
                       produce the full key. This must be kept secret.
 
+.. class:: CAST5(key)
+
+    CAST5 (also known as CAST-128) is a block cipher approved for use in the
+    Canadian government by their Communications Security Establishment. It is a
+    variable key length cipher and supports keys from 40-128 bits in length.
+
+    :param bytes key: The secret key, 40-128 bits in length (in increments of
+                      8).  This must be kept secret.
+
+Weak Ciphers
+------------
+
+.. warning::
+
+    These ciphers are considered weak for a variety of reasons. New
+    applications should avoid their use and existing applications should
+    strongly consider migrating away.
+
+.. class:: Blowfish(key)
+
+    Blowfish is a block cipher developed by Bruce Schneier. It is known to be
+    susceptible to attacks when using weak keys. The author has recommended
+    that users of Blowfish move to newer algorithms like
+    :class:`AES`.
+
+    :param bytes key: The secret key, 32-448 bits in length (in increments of
+                      8).  This must be kept secret.
 
 Modes
 ~~~~~