Started trying to document symmetric encryption

3 files changed, 30 insertions, 0 deletions

diff --git a/docs/index.rst b/docs/index.rst
index 28975f30..1d8ffda6 100644
--- a/docs/index.rst
+++ b/docs/index.rst
@@ -14,4 +14,5 @@ Contents:
     :maxdepth: 2
 
     architecture
+    primitives/index
     community
diff --git a/docs/primitives/index.rst b/docs/primitives/index.rst
new file mode 100644
index 00000000..1066e30e
--- /dev/null
+++ b/docs/primitives/index.rst
@@ -0,0 +1,7 @@
+Primitives
+==========
+
+.. toctree::
+    :maxdepth: 1
+
+    symmetric-encryption
diff --git a/docs/primitives/symmetric-encryption.rst b/docs/primitives/symmetric-encryption.rst
new file mode 100644
index 00000000..acb5fc17
--- /dev/null
+++ b/docs/primitives/symmetric-encryption.rst
@@ -0,0 +1,22 @@
+Symmetric Encryption
+====================
+
+Symmetric encryption is a way to encrypt (hide the plaintext value) material
+where the encrypter and decrypter both use the same key.
+
+Block ciphers
+-------------
+
+Block ciphers work by encrypting content in chunks, often 64- or 128-bits. They
+combine an underlying algorithm (such as AES), with a mode (such as CBC, CTR,
+or GCM). A simple example of encrypting content with AES is:
+
+.. code-block:: pycon
+
+    >>> from cryptography.primitives import BlockCipher, CBC
+    >>> from cryptography.primitives.aes import AES
+    >>> cipher = BlockCipher(AES(key), CBC(iv))
+    >>> cipher.encrypt("my secret message") + cipher.finalize()
+    # The ciphertext
+    [...]
+