add AESGCM AEAD support (#3785)

* add AESGCM AEAD support

* remove stray newline

* move AESGCM docs above CCM

2 files changed, 76 insertions, 0 deletions

diff --git a/docs/hazmat/primitives/aead.rst b/docs/hazmat/primitives/aead.rst
index 6b13edc1..b4e4eaf5 100644
--- a/docs/hazmat/primitives/aead.rst
+++ b/docs/hazmat/primitives/aead.rst
@@ -78,6 +78,75 @@ also support providing integrity for associated data which is not encrypted.
             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 @@ also support providing integrity for associated data which is not encrypted.
             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 7e05acde..9e27540d 100644
--- a/docs/hazmat/primitives/symmetric-encryption.rst
+++ b/docs/hazmat/primitives/symmetric-encryption.rst
@@ -294,6 +294,11 @@ Modes
 
     .. 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`