From 30722b9a84ea38f70a22fbca13d8b3a6078af50a Mon Sep 17 00:00:00 2001
From: David Reid <dreid@dreid.org>
Date: Thu, 7 Nov 2013 13:03:39 -0800
Subject: Add a new Mode interface to document mode.name and start on some
 prose docs for interfaces.

---
 cryptography/hazmat/primitives/ciphers/modes.py |  5 +++
 cryptography/hazmat/primitives/interfaces.py    |  8 ++++
 docs/hazmat/primitives/index.rst                |  1 +
 docs/hazmat/primitives/interfaces.rst           | 59 +++++++++++++++++++++++++
 docs/hazmat/primitives/symmetric-encryption.rst |  3 ++
 5 files changed, 76 insertions(+)
 create mode 100644 docs/hazmat/primitives/interfaces.rst

diff --git a/cryptography/hazmat/primitives/ciphers/modes.py b/cryptography/hazmat/primitives/ciphers/modes.py
index a60e8a34..e54872a6 100644
--- a/cryptography/hazmat/primitives/ciphers/modes.py
+++ b/cryptography/hazmat/primitives/ciphers/modes.py
@@ -16,6 +16,7 @@ from __future__ import absolute_import, division, print_function
 from cryptography.hazmat.primitives import interfaces
 
 
+@interfaces.register(interfaces.Mode)
 @interfaces.register(interfaces.ModeWithInitializationVector)
 class CBC(object):
     name = "CBC"
@@ -25,10 +26,12 @@ class CBC(object):
         self.initialization_vector = initialization_vector
 
 
+@interfaces.register(interfaces.Mode)
 class ECB(object):
     name = "ECB"
 
 
+@interfaces.register(interfaces.Mode)
 @interfaces.register(interfaces.ModeWithInitializationVector)
 class OFB(object):
     name = "OFB"
@@ -38,6 +41,7 @@ class OFB(object):
         self.initialization_vector = initialization_vector
 
 
+@interfaces.register(interfaces.Mode)
 @interfaces.register(interfaces.ModeWithInitializationVector)
 class CFB(object):
     name = "CFB"
@@ -47,6 +51,7 @@ class CFB(object):
         self.initialization_vector = initialization_vector
 
 
+@interfaces.register(interfaces.Mode)
 @interfaces.register(interfaces.ModeWithNonce)
 class CTR(object):
     name = "CTR"
diff --git a/cryptography/hazmat/primitives/interfaces.py b/cryptography/hazmat/primitives/interfaces.py
index d3962a2a..d4466e72 100644
--- a/cryptography/hazmat/primitives/interfaces.py
+++ b/cryptography/hazmat/primitives/interfaces.py
@@ -25,6 +25,14 @@ def register(iface):
     return register_decorator
 
 
+class Mode(six.with_metaclass(abc.ABCMeta)):
+    @abc.abstractproperty
+    def name(self):
+        """
+        A string naming this mode.  (ex. ECB, CBC)
+        """
+
+
 class ModeWithInitializationVector(six.with_metaclass(abc.ABCMeta)):
     @abc.abstractproperty
     def initialization_vector(self):
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..b5261581
--- /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://www.python.org/dev/peps/pep-3119/
+
+
+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 7d3b072d..4b37d396 100644
--- a/docs/hazmat/primitives/symmetric-encryption.rst
+++ b/docs/hazmat/primitives/symmetric-encryption.rst
@@ -149,6 +149,9 @@ Weak Ciphers
     :param bytes key: The secret key, 32-448 bits in length (in increments of
                       8).  This must be kept secret.
 
+
+.. _symmetric-encryption-modes:
+
 Modes
 ~~~~~
 
-- 
cgit v1.2.3