move ciphercontext/aeadciphercontext to bottom of symmetric encryption
Add a bit of additional text to try to make the convoluted AEAD
explanation better.
diff --git a/docs/hazmat/primitives/symmetric-encryption.rst b/docs/hazmat/primitives/symmetric-encryption.rst
index a683bb9..c1f7bb6 100644
--- a/docs/hazmat/primitives/symmetric-encryption.rst
+++ b/docs/hazmat/primitives/symmetric-encryption.rst
@@ -74,79 +74,6 @@
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 @@
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