move ciphercontext/aeadciphercontext to bottom of symmetric encryption

Add a bit of additional text to try to make the convoluted AEAD
explanation better.

1 files changed, 83 insertions, 73 deletions

diff --git a/docs/hazmat/primitives/symmetric-encryption.rst b/docs/hazmat/primitives/symmetric-encryption.rst
index a683bb98..c1f7bb64 100644
--- a/docs/hazmat/primitives/symmetric-encryption.rst
+++ b/docs/hazmat/primitives/symmetric-encryption.rst
@@ -74,79 +74,6 @@ an "encrypt-then-MAC" formulation as `described by Colin Percival`_.
         and ``mode`` an :class:`cryptography.exceptions.UnsupportedAlgorithm`
         will be raised.
 
-
-.. currentmodule:: cryptography.hazmat.primitives.interfaces
-
-.. class:: CipherContext
-
-    When calling ``encryptor()`` or ``decryptor()`` on a ``Cipher`` object
-    you will receive a return object conforming to the ``CipherContext``
-    interface. You can then call ``update(data)`` with data until you have fed
-    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 recommended
-    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.
-        :return bytes: Returns the data that was encrypted or decrypted.
-        :raises cryptography.exceptions.AlreadyFinalized: See :meth:`finalize`
-
-        When the ``Cipher`` was constructed in a mode that turns it into a
-        stream cipher (e.g.
-        :class:`cryptography.hazmat.primitives.ciphers.modes.CTR`), this will
-        return bytes immediately, however in other modes it will return chunks,
-        whose size is determined by the cipher's block size.
-
-    .. 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
-        :class:`~cryptography.exceptions.AlreadyFinalized`.
-
-.. class:: AEADCipherContext
-
-    When calling ``encryptor()`` or ``decryptor()`` on a ``Cipher`` object
-    with an AEAD mode you will receive a return object conforming to the
-    ``AEADCipherContext`` interface (in addition to the ``CipherContext``
-    interface). If it is an encryption context it will additionally be an
-    ``AEADEncryptionContext`` interface. ``AEADCipherContext`` contains an
-    additional method ``authenticate_additional_data`` for adding additional
-    authenticated but unencrypted data. You should call this before calls to
-    ``update``. When you are done call ``finalize()`` to finish the operation.
-
-    .. method:: authenticate_additional_data(data)
-
-        :param bytes data: The data you wish to authenticate but not encrypt.
-        :raises: :class:`~cryptography.exceptions.AlreadyFinalized`
-
-.. class:: AEADEncryptionContext
-
-    When creating an encryption context using ``encryptor()`` on a ``Cipher``
-    object with an AEAD mode you will receive a return object conforming to the
-    ``AEADEncryptionContext`` interface (as well as ``AEADCipherContext``).
-    This interface provides one additional attribute ``tag``. ``tag`` can only
-    be obtained after ``finalize()``.
-
-    .. attribute:: tag
-
-        :return bytes: Returns the tag value as bytes.
-        :raises: :class:`~cryptography.exceptions.NotYetFinalized` if called
-                 before the context is finalized.
-
 .. _symmetric-encryption-algorithms:
 
 Algorithms
@@ -448,6 +375,89 @@ Insecure Modes
     identical plaintext blocks will always result in identical ciphertext
     blocks, and thus result in information leakage
 
+Interfaces
+----------
+
+.. class:: CipherContext
+
+    When calling ``encryptor()`` or ``decryptor()`` on a ``Cipher`` object
+    you will receive a return object conforming to the ``CipherContext``
+    interface. You can then call ``update(data)`` with data until you have fed
+    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 recommended
+    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.
+        :return bytes: Returns the data that was encrypted or decrypted.
+        :raises cryptography.exceptions.AlreadyFinalized: See :meth:`finalize`
+
+        When the ``Cipher`` was constructed in a mode that turns it into a
+        stream cipher (e.g.
+        :class:`cryptography.hazmat.primitives.ciphers.modes.CTR`), this will
+        return bytes immediately, however in other modes it will return chunks,
+        whose size is determined by the cipher's block size.
+
+    .. 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
+        :class:`~cryptography.exceptions.AlreadyFinalized`.
+
+.. class:: AEADCipherContext
+
+    When calling ``encryptor()`` or ``decryptor()`` on a ``Cipher`` object
+    with an AEAD mode (e.g.
+    :class:`~cryptography.hazmat.primitives.ciphers.modes.GCM`) you will receive
+    a return object conforming to the ``AEADCipherContext`` and
+    ``CipherContext`` interfaces. If it is an encryption context it will
+    additionally be an ``AEADEncryptionContext`` interface.
+    ``AEADCipherContext`` contains an additional method
+    ``authenticate_additional_data`` for adding additional authenticated but
+    unencrypted data (see note below). You should call this before calls to
+    ``update``. When you are done call ``finalize()`` to finish the operation.
+
+    .. note::
+
+        In AEAD modes all data passed to ``update()`` will be both encrypted
+        and authenticated. Do not pass encrypted data to the
+        ``authenticate_additional_data()`` method. It is meant solely for
+        additional data you may want to authenticate but leave unencrypted.
+
+    .. method:: authenticate_additional_data(data)
+
+        :param bytes data: Any data you wish to authenticate but not encrypt.
+        :raises: :class:`~cryptography.exceptions.AlreadyFinalized`
+
+.. class:: AEADEncryptionContext
+
+    When creating an encryption context using ``encryptor()`` on a ``Cipher``
+    object with an AEAD mode (e.g.
+    :class:`~cryptography.hazmat.primitives.ciphers.modes.GCM`) you will receive
+    a return object conforming to the ``AEADEncryptionContext`` interface (as
+    well as ``AEADCipherContext``).  This interface provides one additional
+    attribute ``tag``. ``tag`` can only be obtained after ``finalize()``.
+
+    .. attribute:: tag
+
+        :return bytes: Returns the tag value as bytes.
+        :raises: :class:`~cryptography.exceptions.NotYetFinalized` if called
+                 before the context is finalized.
+
 
 .. _`described by Colin Percival`: http://www.daemonology.net/blog/2009-06-11-cryptographic-right-answers.html
 .. _`recommends 96-bit IV length`: http://csrc.nist.gov/groups/ST/toolkit/BCM/documents/proposedmodes/gcm/gcm-spec.pdf