GCM support
diff --git a/docs/exceptions.rst b/docs/exceptions.rst
index c6f5a7c..7ec3cd2 100644
--- a/docs/exceptions.rst
+++ b/docs/exceptions.rst
@@ -7,6 +7,11 @@
This is raised when a context is used after being finalized.
+.. class:: NotFinalized
+
+ This is raised when the AEAD tag property is accessed on a context
+ before it is finalized.
+
.. class:: UnsupportedAlgorithm
diff --git a/docs/hazmat/primitives/symmetric-encryption.rst b/docs/hazmat/primitives/symmetric-encryption.rst
index edf3c05..5b249c0 100644
--- a/docs/hazmat/primitives/symmetric-encryption.rst
+++ b/docs/hazmat/primitives/symmetric-encryption.rst
@@ -118,6 +118,27 @@
:meth:`update` and :meth:`finalize` will raise
:class:`~cryptography.exceptions.AlreadyFinalized`.
+.. class:: AEADCipherContext
+
+ 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 ``add_data``
+ for adding additional authenticated by non-encrypted 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.
+
+ .. method:: add_data(data)
+
+ :param bytes data: The data you wish to authenticate but not encrypt.
+ :raises: :class:`~cryptography.exceptions.AlreadyFinalized`
+
+ .. method:: tag
+
+ :return bytes: Returns the tag value as bytes.
+ :raises: :class:`~cryptography.exceptions.NotFinalized`
+
.. _symmetric-encryption-algorithms:
Algorithms
@@ -295,6 +316,33 @@
reuse an ``initialization_vector`` with
a given ``key``.
+.. class:: GCM(initialization_vector, tag=None)
+
+ GCM (Galois Counter Mode) is a mode of operation for block ciphers. It
+ is an AEAD (authenticated encryption with additional data) mode.
+
+ :param bytes initialization_vector: Must be random bytes. They do not need
+ to be kept secret (they can be included
+ in a transmitted message). Recommended
+ to be 96-bit by NIST, but can be up to
+ 2\ :sup:`64` - 1 bits. Do not reuse an
+ ``initialization_vector`` with a given
+ ``key``.
+
+ .. doctest::
+
+ >>> from cryptography.hazmat.primitives.ciphers import Cipher, algorithms, modes
+ >>> cipher = Cipher(algorithms.AES(key), modes.GCM(iv))
+ >>> encryptor = cipher.encryptor()
+ >>> encryptor.add_data(b"authenticated but encrypted payload")
+ >>> ct = encryptor.update(b"a secret message") + encryptor.finalize()
+ >>> tag = encryptor.tag
+ >>> cipher = Cipher(algorithms.AES(key), modes.GCM(iv, tag))
+ >>> decryptor = cipher.decryptor()
+ >>> decryptor.add_data(b"authenticated but encrypted payload")
+ >>> decryptor.update(ct) + decryptor.finalize()
+ 'a secret message'
+
Insecure Modes
--------------