aboutsummaryrefslogtreecommitdiffstats
path: root/docs/hazmat/primitives/symmetric-encryption.rst
diff options
context:
space:
mode:
authorPhilipp Gesang <phg@phi-gamma.net>2017-05-02 15:28:33 +0200
committerPaul Kehrer <paul.l.kehrer@gmail.com>2017-05-02 08:28:33 -0500
commit2e84daa8e2a3bdcb52750b0589e2ee7ee0fd17ec (patch)
treef9852f1d16b6fa11f524c46343b179c661bebac9 /docs/hazmat/primitives/symmetric-encryption.rst
parentcb94281f5b788f583f5f8a5b689dc9dce321ff8e (diff)
downloadcryptography-2e84daa8e2a3bdcb52750b0589e2ee7ee0fd17ec.tar.gz
cryptography-2e84daa8e2a3bdcb52750b0589e2ee7ee0fd17ec.tar.bz2
cryptography-2e84daa8e2a3bdcb52750b0589e2ee7ee0fd17ec.zip
postpone GCM authentication tag requirement until finalization (#3421)
* postpone GCM authentication tag requirement until finalization Add a .finalize_with_tag() variant of the .finalize() function of the GCM context. At the same time, do not enforce the requirement of supplying the tag with the mode ctor. This facilitates streamed decryption when the MAC is appended to the ciphertext and cannot be efficiently retrieved ahead of decryption. According to the GCM spec (section 7.2: “Algorithm for the Authenticated Decryption Function”), the tag itself is not needed until the ciphertext has been decrypted. Addresses #3380 Signed-off-by: Philipp Gesang <philipp.gesang@intra2net.com> * disallow delayed GCM tag passing for legacy OpenSSL Old versions of Ubuntu supported by Cryptography ship a v1.0.1 of OpenSSL which is no longer supported by upstream. This library seems to cause erratic test failures with the delayed GCM tag functionality which are not reproducible outside the CI. Unfortunately OpenSSL v1.0.1 does not even document the required API (``EVP_EncryptInit(3)``) so there is no by-the-book fix. For backends of version 1.0.1 and earlier, verify the GCM tag at the same stage as before. Also, indicate to the user that late passing of GCM tags is unsupported by throwing ``NotImplementedError`` for these backend versions if - the method ``finalize_with_tag()`` is invoked, or - the mode ctor is called without passing a tag. Unit tests have been adapted to account for different backend versions.
Diffstat (limited to 'docs/hazmat/primitives/symmetric-encryption.rst')
-rw-r--r--docs/hazmat/primitives/symmetric-encryption.rst56
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.