Try making the AEAD examples less dense.
diff --git a/docs/hazmat/primitives/symmetric-encryption.rst b/docs/hazmat/primitives/symmetric-encryption.rst
index e05248f..d3ba731 100644
--- a/docs/hazmat/primitives/symmetric-encryption.rst
+++ b/docs/hazmat/primitives/symmetric-encryption.rst
@@ -365,20 +365,45 @@
:param bytes tag: The tag bytes to verify during decryption. When encrypting
this must be None.
- .. doctest::
+ .. code-block:: python
- >>> from cryptography.hazmat.primitives.ciphers import Cipher, algorithms, modes
- >>> from cryptography.hazmat.backends import default_backend
- >>> cipher = Cipher(algorithms.AES(key), modes.GCM(iv), backend=default_backend())
- >>> encryptor = cipher.encryptor()
- >>> encryptor.authenticate_additional_data(b"authenticated but not encrypted payload")
- >>> ct = encryptor.update(b"a secret message") + encryptor.finalize()
- >>> tag = encryptor.tag
- >>> cipher = Cipher(algorithms.AES(key), modes.GCM(iv, tag), backend)
- >>> decryptor = cipher.decryptor()
- >>> decryptor.authenticate_additional_data(b"authenticated but not encrypted payload")
- >>> decryptor.update(ct) + decryptor.finalize()
- 'a secret message'
+ def encrypt(key, plaintext, associated_data):
+ iv = os.urandom(12)
+ cipher = Cipher(
+ algorithms.AES(key),
+ modes.GCM(iv),
+ backend=default_backend()
+ )
+
+ encryptor = cipher.encryptor()
+ encryptor.authenticate_additional_data(associated_data)
+ ciphertext = encryptor.update(plaintext) + encryptor.finalize()
+
+ return (associated_data, iv, ciphertext, encryptor.tag)
+
+ def decrypt(key, associated_data, iv, ciphertext, tag):
+ cipher = Cipher(
+ algorithms.AES(key),
+ modes.GCM(iv, tag),
+ backend=default_backend()
+ )
+
+ decryptor = cipher.decryptor()
+ decryptor.authenticate_additional_data(associated_data)
+
+ return decryptor.update(ciphertext) + decryptor.finalize()
+
+ associated_data, iv, ciphertext, tag = encrypt(
+ key,
+ b"a secret message",
+ b"authenticated but not encrypted payload"
+ )
+
+ print(decrypt(key, associated_data, iv, ciphertext, tag))
+
+ .. testoutput::
+
+ a secret message
Insecure Modes