aboutsummaryrefslogtreecommitdiffstats
path: root/docs/hazmat/primitives
diff options
context:
space:
mode:
authorPaul Kehrer <paul.l.kehrer@gmail.com>2013-11-29 17:32:08 -0600
committerPaul Kehrer <paul.l.kehrer@gmail.com>2013-11-29 17:32:08 -0600
commit5b828b142b4e8fea021567038e2dba6cf6cd9221 (patch)
tree3f79d1acaccac896b32d9b63e51b052f130e0aad /docs/hazmat/primitives
parent5a40896cbeae2cc2673c86aa18d3953314e760ba (diff)
downloadcryptography-5b828b142b4e8fea021567038e2dba6cf6cd9221.tar.gz
cryptography-5b828b142b4e8fea021567038e2dba6cf6cd9221.tar.bz2
cryptography-5b828b142b4e8fea021567038e2dba6cf6cd9221.zip
attempt to document the new interfaces for AEAD
Diffstat (limited to 'docs/hazmat/primitives')
-rw-r--r--docs/hazmat/primitives/symmetric-encryption.rst26
1 files changed, 20 insertions, 6 deletions
diff --git a/docs/hazmat/primitives/symmetric-encryption.rst b/docs/hazmat/primitives/symmetric-encryption.rst
index aefc2d7e..9d4f0355 100644
--- a/docs/hazmat/primitives/symmetric-encryption.rst
+++ b/docs/hazmat/primitives/symmetric-encryption.rst
@@ -122,24 +122,38 @@ an "encrypt-then-MAC" formulation as `described by Colin Percival`_.
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. ``AEADCipherContext`` contains an additional method
+ ``AEADCipherContext`` interface (in addition to the ``CipherContext``
+ interface and either the ``AEADEncryptionContext`` or ``AEADDecryptionContext``
+ 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. Once this is complete
- you can obtain the tag value from the ``tag`` property.
+ 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.
- :raises TypeError: If called on a decryption context.
+
+.. class:: AEADDecryptionContext
+
+ When creating an encryption context using ``encryptor()`` on a ``Cipher``
+ object with an AEAD mode you will receive a return object conforming to the
+ ``AEADDecryptionContext`` interface (as well as ``AEADCipherContext``). This
+ interface does not provide any additional methods or attributes.
.. _symmetric-encryption-algorithms:
@@ -320,7 +334,7 @@ Modes
.. class:: GCM(initialization_vector, tag=None)
- .. warning::
+ .. danger::
When using this mode you MUST not use the decrypted data until every
byte has been decrypted. GCM provides NO guarantees of ciphertext