add AESGCM AEAD support (#3785)
* add AESGCM AEAD support
* remove stray newline
* move AESGCM docs above CCM
diff --git a/docs/hazmat/primitives/aead.rst b/docs/hazmat/primitives/aead.rst
index 6b13edc..b4e4eaf 100644
--- a/docs/hazmat/primitives/aead.rst
+++ b/docs/hazmat/primitives/aead.rst
@@ -78,6 +78,75 @@
when the ciphertext has been changed, but will also occur when the
key, nonce, or associated data are wrong.
+.. class:: AESGCM(key)
+
+ .. versionadded:: 2.0
+
+ The AES-GCM construction is composed of the
+ :class:`~cryptography.hazmat.primitives.ciphers.algorithms.AES` block
+ cipher utilizing Galois Counter Mode (GCM).
+
+ :param bytes key: A 128, 192, or 256-bit key. This **must** be kept secret.
+
+ .. doctest::
+
+ >>> import os
+ >>> from cryptography.hazmat.primitives.ciphers.aead import AESGCM
+ >>> data = b"a secret message"
+ >>> aad = b"authenticated but unencrypted data"
+ >>> key = AESGCM.generate_key(bit_length=128)
+ >>> aesgcm = AESGCM(key)
+ >>> nonce = os.urandom(12)
+ >>> ct = aesgcm.encrypt(nonce, data, aad)
+ >>> aesgcm.decrypt(nonce, ct, aad)
+ 'a secret message'
+
+ .. classmethod:: generate_key(bit_length)
+
+ Securely generates a random AES-GCM key.
+
+ :param bit_length: The bit length of the key to generate. Must be
+ 128, 192, or 256.
+
+ :returns bytes: The generated key.
+
+ .. method:: encrypt(nonce, data, associated_data)
+
+ .. warning::
+
+ Reuse of a ``nonce`` with a given ``key`` compromises the security
+ of any message with that ``nonce`` and ``key`` pair.
+
+ Encrypts and authenticates the ``data`` provided as well as
+ authenticating the ``associated_data``. The output of this can be
+ passed directly to the ``decrypt`` method.
+
+ :param bytes nonce: NIST `recommends a 96-bit IV length`_ for best
+ performance but it can be up to 2\ :sup:`64` - 1 bits.
+ **NEVER REUSE A NONCE** with a key.
+ :param bytes data: The data to encrypt.
+ :param bytes associated_data: Additional data that should be
+ authenticated with the key, but is not encrypted. Can be ``None``.
+ :returns bytes: The ciphertext bytes with the 16 byte tag appended.
+
+ .. method:: decrypt(nonce, data, associated_data)
+
+ Decrypts the ``data`` and authenticates the ``associated_data``. If you
+ called encrypt with ``associated_data`` you must pass the same
+ ``associated_data`` in decrypt or the integrity check will fail.
+
+ :param bytes nonce: NIST `recommends a 96-bit IV length`_ for best
+ performance but it can be up to 2\ :sup:`64` - 1 bits.
+ **NEVER REUSE A NONCE** with a key.
+ :param bytes data: The data to decrypt (with tag appended).
+ :param bytes associated_data: Additional data to authenticate. Can be
+ ``None`` if none was passed during encryption.
+ :returns bytes: The original plaintext.
+ :raises cryptography.exceptions.InvalidTag: If the authentication tag
+ doesn't validate this exception will be raised. This will occur
+ when the ciphertext has been changed, but will also occur when the
+ key, nonce, or associated data are wrong.
+
.. class:: AESCCM(key, tag_length=16)
.. versionadded:: 2.0
@@ -161,3 +230,5 @@
doesn't validate this exception will be raised. This will occur
when the ciphertext has been changed, but will also occur when the
key, nonce, or associated data are wrong.
+
+.. _`recommends a 96-bit IV length`: http://csrc.nist.gov/groups/ST/toolkit/BCM/documents/proposedmodes/gcm/gcm-spec.pdf
diff --git a/docs/hazmat/primitives/symmetric-encryption.rst b/docs/hazmat/primitives/symmetric-encryption.rst
index 7e05acd..9e27540 100644
--- a/docs/hazmat/primitives/symmetric-encryption.rst
+++ b/docs/hazmat/primitives/symmetric-encryption.rst
@@ -294,6 +294,11 @@
.. danger::
+ If you are encrypting data that can fit into memory you should strongly
+ consider using
+ :class:`~cryptography.hazmat.primitives.ciphers.aead.AESGCM` instead
+ of this.
+
When using this mode you **must** not use the decrypted data until
the appropriate finalization method
(:meth:`~cryptography.hazmat.primitives.ciphers.CipherContext.finalize`