diff options
Diffstat (limited to 'docs/hazmat/primitives/symmetric-encryption.rst')
| -rw-r--r-- | docs/hazmat/primitives/symmetric-encryption.rst | 56 |
1 files changed, 48 insertions, 8 deletions
diff --git a/docs/hazmat/primitives/symmetric-encryption.rst b/docs/hazmat/primitives/symmetric-encryption.rst index 17d91091..5f4d7bf9 100644 --- a/docs/hazmat/primitives/symmetric-encryption.rst +++ b/docs/hazmat/primitives/symmetric-encryption.rst @@ -292,7 +292,10 @@ Modes .. danger:: When using this mode you **must** not use the decrypted data until - :meth:`~cryptography.hazmat.primitives.ciphers.CipherContext.finalize` + the appropriate finalization method + (:meth:`~cryptography.hazmat.primitives.ciphers.CipherContext.finalize` + or + :meth:`~cryptography.hazmat.primitives.ciphers.AEADDecryptionContext.finalize_with_tag`) has been called. GCM provides **no** guarantees of ciphertext integrity until decryption is complete. @@ -326,7 +329,10 @@ Modes truncation down to ``4`` bytes was always allowed. :param bytes tag: The tag bytes to verify during decryption. When - encrypting this must be ``None``. + encrypting this must be ``None``. When decrypting, it may be ``None`` + if the tag is supplied on finalization using + :meth:`~cryptography.hazmat.primitives.ciphers.AEADDecryptionContext.finalize_with_tag`. + Otherwise, the tag is mandatory. :param bytes min_tag_length: The minimum length ``tag`` must be. By default this is ``16``, meaning tag truncation is not allowed. Allowing tag @@ -334,6 +340,9 @@ Modes :raises ValueError: This is raised if ``len(tag) < min_tag_length``. + :raises NotImplementedError: This is raised if the version of the OpenSSL + backend used is 1.0.1 or earlier. + An example of securely encrypting and decrypting data with ``AES`` in the ``GCM`` mode looks like: @@ -516,12 +525,12 @@ Interfaces with an AEAD mode (e.g. :class:`~cryptography.hazmat.primitives.ciphers.modes.GCM`) the result will conform to the ``AEADCipherContext`` and ``CipherContext`` interfaces. If - it is an encryption context it will additionally be an - ``AEADEncryptionContext`` instance. ``AEADCipherContext`` contains an - additional method :meth:`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. + it is an encryption or decryption context it will additionally be an + ``AEADEncryptionContext`` or ``AEADDecryptionContext`` instance, + respectively. ``AEADCipherContext`` contains an additional method + :meth:`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:: @@ -551,6 +560,37 @@ Interfaces :raises: :class:`~cryptography.exceptions.NotYetFinalized` if called before the context is finalized. +.. class:: AEADDecryptionContext + + .. versionadded:: 1.9 + + When creating an encryption context using ``decryptor`` on a ``Cipher`` + object with an AEAD mode such as + :class:`~cryptography.hazmat.primitives.ciphers.modes.GCM` an object + conforming to both the ``AEADDecryptionContext`` and ``AEADCipherContext`` + interfaces will be returned. This interface provides one additional method + :meth:`finalize_with_tag` that allows passing the authentication tag for + validation after the ciphertext has been decrypted. + + .. method:: finalize_with_tag(tag) + + :param bytes tag: The tag bytes to verify after decryption. + :return bytes: Returns the remainder of the data. + :raises ValueError: This is raised when the data provided isn't + a multiple of the algorithm's block size, if ``min_tag_length`` is + less than 4, or if ``len(tag) < min_tag_length``. + :raises NotImplementedError: This is raised if the version of the + OpenSSL backend used is 1.0.1 or earlier. + + If the authentication tag was not already supplied to the constructor + of the :class:`~cryptography.hazmat.primitives.ciphers.modes.GCM` mode + object, this method must be used instead of + :meth:`~cryptography.hazmat.primitives.ciphers.CipherContext.finalize`. + + .. note:: + + This method is not supported when compiled against OpenSSL 1.0.1. + .. class:: CipherAlgorithm A named symmetric encryption algorithm. |