Merge pull request #26 from alex/symmetric-encryption-docs
[WIP] Started trying to document symmetric encryption
diff --git a/docs/index.rst b/docs/index.rst
index 28975f3..1d8ffda 100644
--- a/docs/index.rst
+++ b/docs/index.rst
@@ -14,4 +14,5 @@
:maxdepth: 2
architecture
+ primitives/index
community
diff --git a/docs/primitives/index.rst b/docs/primitives/index.rst
new file mode 100644
index 0000000..1066e30
--- /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 0000000..fe074f3
--- /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()