Add a new Mode interface to document mode.name and start on some prose docs for interfaces.
diff --git a/cryptography/hazmat/primitives/ciphers/modes.py b/cryptography/hazmat/primitives/ciphers/modes.py
index a60e8a3..e54872a 100644
--- a/cryptography/hazmat/primitives/ciphers/modes.py
+++ b/cryptography/hazmat/primitives/ciphers/modes.py
@@ -16,6 +16,7 @@
from cryptography.hazmat.primitives import interfaces
+@interfaces.register(interfaces.Mode)
@interfaces.register(interfaces.ModeWithInitializationVector)
class CBC(object):
name = "CBC"
@@ -25,10 +26,12 @@
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 @@
self.initialization_vector = initialization_vector
+@interfaces.register(interfaces.Mode)
@interfaces.register(interfaces.ModeWithInitializationVector)
class CFB(object):
name = "CFB"
@@ -47,6 +51,7 @@
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 d3962a2..d4466e7 100644
--- a/cryptography/hazmat/primitives/interfaces.py
+++ b/cryptography/hazmat/primitives/interfaces.py
@@ -25,6 +25,14 @@
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 c81018a..614c414 100644
--- a/docs/hazmat/primitives/index.rst
+++ b/docs/hazmat/primitives/index.rst
@@ -10,3 +10,4 @@
hmac
symmetric-encryption
padding
+ interfaces
diff --git a/docs/hazmat/primitives/interfaces.rst b/docs/hazmat/primitives/interfaces.rst
new file mode 100644
index 0000000..b526158
--- /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 7d3b072..4b37d39 100644
--- a/docs/hazmat/primitives/symmetric-encryption.rst
+++ b/docs/hazmat/primitives/symmetric-encryption.rst
@@ -149,6 +149,9 @@
:param bytes key: The secret key, 32-448 bits in length (in increments of
8). This must be kept secret.
+
+.. _symmetric-encryption-modes:
+
Modes
~~~~~