Merge branch 'master' into fernet

3 files changed, 19 insertions, 2 deletions

diff --git a/docs/exceptions.rst b/docs/exceptions.rst
index ab1b28fe..c6f5a7cc 100644
--- a/docs/exceptions.rst
+++ b/docs/exceptions.rst
@@ -12,4 +12,3 @@ Exceptions
 
     This is raised when a backend doesn't support the requested algorithm (or
     combination of algorithms).
-
diff --git a/docs/hazmat/primitives/padding.rst b/docs/hazmat/primitives/padding.rst
index aebb4d4d..4d79ac8f 100644
--- a/docs/hazmat/primitives/padding.rst
+++ b/docs/hazmat/primitives/padding.rst
@@ -25,8 +25,14 @@ multiple of the block size.
         >>> padder = padding.PKCS7(128).padder()
         >>> padder.update(b"1111111111")
         ''
-        >>> padder.finalize()
+        >>> padded_data = padder.finalize()
+        >>> padded_data
         '1111111111\x06\x06\x06\x06\x06\x06'
+        >>> unpadder = padding.PKCS7(128).unpadder()
+        >>> unpadder.update(padded_data)
+        ''
+        >>> unpadder.finalize()
+        '1111111111'
 
     :param block_size: The size of the block in bits that the data is being
                        padded to.
diff --git a/docs/hazmat/primitives/symmetric-encryption.rst b/docs/hazmat/primitives/symmetric-encryption.rst
index eef359d6..732af33c 100644
--- a/docs/hazmat/primitives/symmetric-encryption.rst
+++ b/docs/hazmat/primitives/symmetric-encryption.rst
@@ -75,6 +75,15 @@ an "encrypt-then-MAC" formulation as `described by Colin Percival`_.
     everything into the context. Once that is done call ``finalize()`` to
     finish the operation and obtain the remainder of the data.
 
+    Block ciphers require that plaintext or ciphertext always be a multiple of
+    their block size, because of that **padding** is often required to make a
+    message the correct size. ``CipherContext`` will not automatically apply
+    any padding; you'll need to add your own. For block ciphers the reccomended
+    padding is :class:`cryptography.hazmat.primitives.padding.PKCS7`. If you
+    are using a stream cipher mode (such as
+    :class:`cryptography.hazmat.primitives.modes.CTR`) you don't have to worry
+    about this.
+
     .. method:: update(data)
 
         :param bytes data: The data you wish to pass into the context.
@@ -90,6 +99,9 @@ an "encrypt-then-MAC" formulation as `described by Colin Percival`_.
     .. method:: finalize()
 
         :return bytes: Returns the remainder of the data.
+        :raises ValueError: This is raised when the data provided isn't
+                            correctly padded to be a multiple of the
+                            algorithm's block size.
 
         Once ``finalize`` is called this object can no longer be used and
         :meth:`update` and :meth:`finalize` will raise