Merge pull request #26 from alex/symmetric-encryption-docs

[WIP] Started trying to document symmetric encryption

3 files changed, 77 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..fe074f3e
--- /dev/null
+++ b/docs/primitives/symmetric-encryption.rst
@@ -0,0 +1,69 @@
+Symmetric Encryption
+====================
+
+Symmetric encryption is a way to encrypt (hide the plaintext value) material
+where the encrypter and decrypter both use the same key.
+
+.. class:: cryptography.primitives.block.BlockCipher(cipher, mode)
+
+    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.block import BlockCipher, cipher, mode, padding
+        >>> cipher = BlockCipher(cipher.AES(key), mode.CBC(iv, padding.PKCS7()))
+        >>> cipher.encrypt("my secret message") + cipher.finalize()
+        # The ciphertext
+        [...]
+
+    :param cipher: One of the ciphers described below.
+    :param mode: One of the modes described below.
+
+    ``encrypt()`` should be called repeatedly with new plaintext, and once the
+    full plaintext is fed in, ``finalize()`` should be called.
+
+    .. method:: encrypt(plaintext)
+
+        :param bytes plaintext: The text you wish to encrypt.
+        :return bytes: Returns the ciphertext that was added.
+
+    .. method:: finalize()
+
+        :return bytes: Returns the remainder of the ciphertext.
+
+Ciphers
+~~~~~~~
+
+.. class:: cryptography.primitives.block.cipher.AES(key)
+
+    AES (Advanced Encryption Standard) is a block cipher standardized by NIST.
+    AES is both fast, and cryptographically strong. It is a good default
+    choice for encryption.
+
+    :param bytes key: The secret key, either ``128``, ``192``, or ``256`` bits.
+                      This must be kept secret.
+
+
+Modes
+~~~~~
+
+.. class:: cryptography.primitives.block.mode.CBC(initialization_vector, padding)
+
+    CBC (Cipher block chaining) is a mode of operation for block ciphers. It is
+    considered cryptographically strong.
+
+    :param bytes initialization_vector: Must be random bytes. They do not need
+                                        to be kept secret (they can be included
+                                        in a transmitted message). Must be the
+                                        same number of bytes as the
+                                        ``block_size`` of the cipher. Do not
+                                        reuse an ``initialization_vector`` with
+                                        a given ``key``.
+    :param padding: One of the paddings described below.
+
+Paddings
+~~~~~~~~
+
+.. class:: cryptography.primitives.block.padding.PKCS7()