diff options
author | Paul Kehrer <paul.l.kehrer@gmail.com> | 2013-11-29 17:32:08 -0600 |
---|---|---|
committer | Paul Kehrer <paul.l.kehrer@gmail.com> | 2013-11-29 17:32:08 -0600 |
commit | 5b828b142b4e8fea021567038e2dba6cf6cd9221 (patch) | |
tree | 3f79d1acaccac896b32d9b63e51b052f130e0aad | |
parent | 5a40896cbeae2cc2673c86aa18d3953314e760ba (diff) | |
download | cryptography-5b828b142b4e8fea021567038e2dba6cf6cd9221.tar.gz cryptography-5b828b142b4e8fea021567038e2dba6cf6cd9221.tar.bz2 cryptography-5b828b142b4e8fea021567038e2dba6cf6cd9221.zip |
attempt to document the new interfaces for AEAD
-rw-r--r-- | docs/hazmat/primitives/symmetric-encryption.rst | 26 |
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 |