From 2c0c91e6ed245d6363828458020e90ec0670ed24 Mon Sep 17 00:00:00 2001 From: David Reid Date: Wed, 6 Nov 2013 15:00:19 -0800 Subject: Actually note the properties for cipher modes types on their ABCs. --- cryptography/hazmat/primitives/interfaces.py | 12 ++++++++++-- 1 file changed, 10 insertions(+), 2 deletions(-) diff --git a/cryptography/hazmat/primitives/interfaces.py b/cryptography/hazmat/primitives/interfaces.py index ebf5e31e..d6a05c18 100644 --- a/cryptography/hazmat/primitives/interfaces.py +++ b/cryptography/hazmat/primitives/interfaces.py @@ -26,11 +26,19 @@ def register(iface): class ModeWithInitializationVector(six.with_metaclass(abc.ABCMeta)): - pass + @abc.abstractproperty + def iv(self): + """ + The value of the initialization vector for this mode. + """ class ModeWithNonce(six.with_metaclass(abc.ABCMeta)): - pass + @abc.abstractproperty + def nonce(self): + """ + The value of the nonce for this mode. + """ class CipherContext(six.with_metaclass(abc.ABCMeta)): -- cgit v1.2.3 From a0b59223025a54c800c7844568428992f876a711 Mon Sep 17 00:00:00 2001 From: David Reid Date: Wed, 6 Nov 2013 16:07:29 -0800 Subject: Proper name for the iv thing. --- cryptography/hazmat/primitives/interfaces.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/cryptography/hazmat/primitives/interfaces.py b/cryptography/hazmat/primitives/interfaces.py index d6a05c18..d3962a2a 100644 --- a/cryptography/hazmat/primitives/interfaces.py +++ b/cryptography/hazmat/primitives/interfaces.py @@ -27,7 +27,7 @@ def register(iface): class ModeWithInitializationVector(six.with_metaclass(abc.ABCMeta)): @abc.abstractproperty - def iv(self): + def initialization_vector(self): """ The value of the initialization vector for this mode. """ -- cgit v1.2.3 From 30722b9a84ea38f70a22fbca13d8b3a6078af50a Mon Sep 17 00:00:00 2001 From: David Reid 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 `. + +.. 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 From bd18bcd915444a54648eccded360b68c26a23b99 Mon Sep 17 00:00:00 2001 From: David Reid Date: Thu, 7 Nov 2013 13:13:30 -0800 Subject: Single space. --- docs/hazmat/primitives/interfaces.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/hazmat/primitives/interfaces.rst b/docs/hazmat/primitives/interfaces.rst index b5261581..f37dbb5a 100644 --- a/docs/hazmat/primitives/interfaces.rst +++ b/docs/hazmat/primitives/interfaces.rst @@ -5,8 +5,8 @@ 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 +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/ -- cgit v1.2.3 From 9ed25e48afbd56f9f825ebbed9ef2c27c31c65e4 Mon Sep 17 00:00:00 2001 From: David Reid Date: Thu, 7 Nov 2013 13:15:27 -0800 Subject: Module documentation. --- docs/hazmat/primitives/interfaces.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/hazmat/primitives/interfaces.rst b/docs/hazmat/primitives/interfaces.rst index f37dbb5a..7068316e 100644 --- a/docs/hazmat/primitives/interfaces.rst +++ b/docs/hazmat/primitives/interfaces.rst @@ -9,7 +9,7 @@ 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/ +.. _`Abstract Base Classes`: http://docs.python.org/3.2/library/abc.html Cipher Modes -- cgit v1.2.3 From 07e8a49658945d2082ef4f9a4dd9ea01e57b6e58 Mon Sep 17 00:00:00 2001 From: David Reid Date: Thu, 7 Nov 2013 13:16:50 -0800 Subject: Consistently use e.g. --- cryptography/hazmat/primitives/interfaces.py | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/cryptography/hazmat/primitives/interfaces.py b/cryptography/hazmat/primitives/interfaces.py index d4466e72..da4fa209 100644 --- a/cryptography/hazmat/primitives/interfaces.py +++ b/cryptography/hazmat/primitives/interfaces.py @@ -29,7 +29,7 @@ class Mode(six.with_metaclass(abc.ABCMeta)): @abc.abstractproperty def name(self): """ - A string naming this mode. (ex. ECB, CBC) + A string naming this mode. (e.g. ECB, CBC) """ @@ -81,7 +81,7 @@ class HashAlgorithm(six.with_metaclass(abc.ABCMeta)): @abc.abstractproperty def name(self): """ - A string naming this algorithm. (ex. sha256, md5) + A string naming this algorithm. (e.g. sha256, md5) """ @abc.abstractproperty -- cgit v1.2.3 From f2f58738305b51e0fad98cf1fc6c5e490738066f Mon Sep 17 00:00:00 2001 From: David Reid Date: Thu, 7 Nov 2013 13:17:02 -0800 Subject: Mention return types. --- cryptography/hazmat/primitives/interfaces.py | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/cryptography/hazmat/primitives/interfaces.py b/cryptography/hazmat/primitives/interfaces.py index da4fa209..67dbe6fa 100644 --- a/cryptography/hazmat/primitives/interfaces.py +++ b/cryptography/hazmat/primitives/interfaces.py @@ -37,7 +37,7 @@ class ModeWithInitializationVector(six.with_metaclass(abc.ABCMeta)): @abc.abstractproperty def initialization_vector(self): """ - The value of the initialization vector for this mode. + The value of the initialization vector for this mode as bytes. """ @@ -45,7 +45,7 @@ class ModeWithNonce(six.with_metaclass(abc.ABCMeta)): @abc.abstractproperty def nonce(self): """ - The value of the nonce for this mode. + The value of the nonce for this mode as bytes. """ -- cgit v1.2.3 From 8ed651e717537ea69c987b78f6ef9f8d336bb734 Mon Sep 17 00:00:00 2001 From: Alex Gaynor Date: Thu, 7 Nov 2013 13:24:31 -0800 Subject: Be really explicit about what's good and bad --- docs/hazmat/primitives/symmetric-encryption.rst | 26 ++++++++++++++++++++++--- 1 file changed, 23 insertions(+), 3 deletions(-) diff --git a/docs/hazmat/primitives/symmetric-encryption.rst b/docs/hazmat/primitives/symmetric-encryption.rst index 7d3b072d..1aeb2a56 100644 --- a/docs/hazmat/primitives/symmetric-encryption.rst +++ b/docs/hazmat/primitives/symmetric-encryption.rst @@ -163,9 +163,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 + someting 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) -- cgit v1.2.3 From 9de452d02ed0be26a86526fed5695a3f1a3db3a3 Mon Sep 17 00:00:00 2001 From: Alex Gaynor Date: Thu, 7 Nov 2013 13:28:23 -0800 Subject: Typo --- docs/hazmat/primitives/symmetric-encryption.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/hazmat/primitives/symmetric-encryption.rst b/docs/hazmat/primitives/symmetric-encryption.rst index 1aeb2a56..6fa71767 100644 --- a/docs/hazmat/primitives/symmetric-encryption.rst +++ b/docs/hazmat/primitives/symmetric-encryption.rst @@ -164,7 +164,7 @@ Modes in a transmitted message). Must be the same number of bytes as the ``block_size`` of the cipher. Each time - someting is encrypted a new + something is encrypted a new ``initialization_vector`` should be generated. Do not reuse an ``initialization_vector`` with -- cgit v1.2.3