3 files changed, 86 insertions, 3 deletions
diff --git a/docs/hazmat/primitives/index.rst b/docs/hazmat/primitives/index.rst
index c81018ae..614c414a 100644
--- a/docs/hazmat/primitives/index.rst
+++ b/docs/hazmat/primitives/index.rst
@@ -10,3 +10,4 @@ Primitives
     hmac
     symmetric-encryption
     padding
+    interfaces
diff --git a/docs/hazmat/primitives/interfaces.rst b/docs/hazmat/primitives/interfaces.rst
new file mode 100644
index 00000000..7068316e
--- /dev/null
+++ b/docs/hazmat/primitives/interfaces.rst
@@ -0,0 +1,59 @@
+.. hazmat::
+
+Interfaces
+==========
+
+
+``cryptography`` uses `Abstract Base Classes`_ as interfaces to describe the
+properties and methods of most primitive constructs. Backends may also use
+this information to influence their operation. Interfaces should also be used
+to document argument and return types.
+
+.. _`Abstract Base Classes`: http://docs.python.org/3.2/library/abc.html
+
+
+Cipher Modes
+~~~~~~~~~~~~
+
+.. currentmodule:: cryptography.hazmat.primitives.interfaces
+
+Interfaces used by the symmetric cipher modes described in
+:ref:`Symmetric Encryption Modes <symmetric-encryption-modes>`.
+
+.. class:: Mode
+
+    A named cipher mode.
+
+    .. attribute:: name
+
+        :type: str
+
+        This should be the standard shorthand name for the mode, for example
+        Cipher-Block Chaining mode is "CBC".
+
+        The name may be used by a backend to influence the operation of a
+        cipher in conjunction with the algorithm's name.
+
+
+.. class:: ModeWithInitializationVector
+
+    A cipher mode with an initialization vector.
+
+    .. attribute:: initialization_vector
+
+        :type: bytes
+
+        Exact requirements of the initialization are described by the
+        documentation of individual modes.
+
+
+.. class:: ModeWithNonce
+
+    A cipher mode with a nonce.
+
+    .. attribute:: nonce
+
+        :type: bytes
+
+        Exact requirements of the nonce are described by the documentation of
+        individual modes.
diff --git a/docs/hazmat/primitives/symmetric-encryption.rst b/docs/hazmat/primitives/symmetric-encryption.rst
index 4d0703bb..9d18ce50 100644
--- a/docs/hazmat/primitives/symmetric-encryption.rst
+++ b/docs/hazmat/primitives/symmetric-encryption.rst
@@ -159,6 +159,9 @@ Weak Ciphers
                       ``192``, or ``256`` bits in length.  This must be kept
                       secret.
 
+
+.. _symmetric-encryption-modes:
+
 Modes
 ~~~~~
 
@@ -173,9 +176,29 @@ Modes
                                         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``.
+                                        ``block_size`` of the cipher. Each time
+                                        something is encrypted a new
+                                        ``initialization_vector`` should be
+                                        generated. Do not reuse an
+                                        ``initialization_vector`` with
+                                        a given ``key``, and particularly do
+                                        not use a constant
+                                        ``initialization_vector``.
+
+    A good construction looks like:
+
+    .. code-block:: pycon
+
+        >>> import os
+        >>> iv = os.urandom(16)
+        >>> mode = CBC(iv)
+
+    While the following is bad and will leak information:
+
+    .. code-block:: pycon
+
+        >>> iv = "a" * 16
+        >>> mode = CBC(iv)
 
 
 .. class:: CTR(nonce)