1 files changed, 79 insertions, 0 deletions
diff --git a/docs/hazmat/primitives/aead.rst b/docs/hazmat/primitives/aead.rst
new file mode 100644
index 00000000..54343b86
--- /dev/null
+++ b/docs/hazmat/primitives/aead.rst
@@ -0,0 +1,79 @@
+.. hazmat::
+
+
+Authenticated encryption
+========================
+
+.. module:: cryptography.hazmat.primitives.ciphers.aead
+
+Authenticated encryption with associated data (AEAD) are encryption schemes
+which provide both confidentiality and integrity for their ciphertext. They
+also support providing integrity for associated data which is not encrypted.
+
+.. class:: ChaCha20Poly1305(key)
+
+    .. versionadded:: 2.0
+
+    The ChaCha20Poly1305 construction is defined in :rfc:`7539` section 2.8.
+    It is a stream cipher combined with a MAC that offers strong integrity
+    guarantees.
+
+    :param bytes key: A 32-byte key. This **must** be kept secret.
+
+    :raises cryptography.exceptions.UnsupportedAlgorithm: If the version of
+        OpenSSL does not support ChaCha20Poly1305.
+
+    .. doctest::
+
+        >>> import os
+        >>> from cryptography.hazmat.primitives.ciphers.aead import ChaCha20Poly1305
+        >>> data = b"a secret message"
+        >>> aad = b"authenticated but unencrypted data"
+        >>> key = ChaCha20Poly1305.generate_key()
+        >>> chacha = ChaCha20Poly1305(key)
+        >>> nonce = os.urandom(12)
+        >>> ct = chacha.encrypt(nonce, data, aad)
+        >>> chacha.decrypt(nonce, ct, aad)
+        'a secret message'
+
+    .. classmethod:: generate_key()
+
+        Securely generates a random ChaCha20Poly1305 key.
+
+        :returns bytes: A 32 byte 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 the ``data`` provided and authenticates the
+        ``associated_data``.  The output of this can be passed directly
+        to the ``decrypt`` method.
+
+        :param bytes nonce: A 12 byte value. **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 does not need to be 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: A 12 byte value. **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.