From d1f0201fd80659395a8444efe11ba24473c212e5 Mon Sep 17 00:00:00 2001 From: Alex Gaynor Date: Fri, 1 Nov 2013 14:12:35 -0700 Subject: Document how this returns bytes --- docs/hazmat/primitives/symmetric-encryption.rst | 8 +++++++- 1 file changed, 7 insertions(+), 1 deletion(-) (limited to 'docs/hazmat') diff --git a/docs/hazmat/primitives/symmetric-encryption.rst b/docs/hazmat/primitives/symmetric-encryption.rst index 5852dc21..a0e76506 100644 --- a/docs/hazmat/primitives/symmetric-encryption.rst +++ b/docs/hazmat/primitives/symmetric-encryption.rst @@ -63,6 +63,11 @@ where the encrypter and decrypter both use the same key. :param bytes data: The data you wish to pass into the context. :return bytes: Returns the data that was encrypted or decrypted. + When the ``BlockCipher`` was constructed in a mode turns it into a + stream cipher, this will return bytes immediately, however in other + modes it will return blocks in chunks, whose size is determined by the + cipher's block size. + .. method:: finalize() :return bytes: Returns the remainder of the data. @@ -162,7 +167,8 @@ Modes block size of less than 128-bits. CTR (Counter) is a mode of operation for block ciphers. It is considered - cryptographically strong. + cryptographically strong. It transforms a block cipher into a stream + cipher. :param bytes nonce: Should be random bytes. It is critical to never reuse a ``nonce`` with a given key. Any reuse of a nonce -- cgit v1.2.3 From fc09a7cb78591ad0bf5ee0116c85dcee6d47502c Mon Sep 17 00:00:00 2001 From: Alex Gaynor Date: Fri, 1 Nov 2013 14:43:02 -0700 Subject: For example --- docs/hazmat/primitives/symmetric-encryption.rst | 7 ++++--- 1 file changed, 4 insertions(+), 3 deletions(-) (limited to 'docs/hazmat') diff --git a/docs/hazmat/primitives/symmetric-encryption.rst b/docs/hazmat/primitives/symmetric-encryption.rst index a0e76506..f68979a3 100644 --- a/docs/hazmat/primitives/symmetric-encryption.rst +++ b/docs/hazmat/primitives/symmetric-encryption.rst @@ -64,9 +64,10 @@ where the encrypter and decrypter both use the same key. :return bytes: Returns the data that was encrypted or decrypted. When the ``BlockCipher`` was constructed in a mode turns it into a - stream cipher, this will return bytes immediately, however in other - modes it will return blocks in chunks, whose size is determined by the - cipher's block size. + stream cipher (e.g. + :class:`cryptography.hazmat.primitives.block.modes.CTR`), this will + return bytes immediately, however in other modes it will return blocks + in chunks, whose size is determined by the cipher's block size. .. method:: finalize() -- cgit v1.2.3 From bf2de7458aebbc6bc855e9f145cf9a40ceec033e Mon Sep 17 00:00:00 2001 From: Alex Gaynor Date: Fri, 1 Nov 2013 14:48:19 -0700 Subject: better english --- docs/hazmat/primitives/symmetric-encryption.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) (limited to 'docs/hazmat') diff --git a/docs/hazmat/primitives/symmetric-encryption.rst b/docs/hazmat/primitives/symmetric-encryption.rst index f68979a3..b8b1c839 100644 --- a/docs/hazmat/primitives/symmetric-encryption.rst +++ b/docs/hazmat/primitives/symmetric-encryption.rst @@ -66,8 +66,8 @@ where the encrypter and decrypter both use the same key. When the ``BlockCipher`` was constructed in a mode turns it into a stream cipher (e.g. :class:`cryptography.hazmat.primitives.block.modes.CTR`), this will - return bytes immediately, however in other modes it will return blocks - in chunks, whose size is determined by the cipher's block size. + return bytes immediately, however in other modes it will return chunks, + whose size is determined by the cipher's block size. .. method:: finalize() -- cgit v1.2.3 From f1a3fc03dc7cecc7658620f342dfd7cf6bb98ba0 Mon Sep 17 00:00:00 2001 From: Alex Gaynor Date: Sat, 2 Nov 2013 14:03:34 -0700 Subject: Document and implement the public API for when the backend doesn't support the requested algorithm --- docs/hazmat/primitives/symmetric-encryption.rst | 9 +++++++++ 1 file changed, 9 insertions(+) (limited to 'docs/hazmat') diff --git a/docs/hazmat/primitives/symmetric-encryption.rst b/docs/hazmat/primitives/symmetric-encryption.rst index b8b1c839..48bad928 100644 --- a/docs/hazmat/primitives/symmetric-encryption.rst +++ b/docs/hazmat/primitives/symmetric-encryption.rst @@ -42,12 +42,21 @@ where the encrypter and decrypter both use the same key. :class:`~cryptography.hazmat.primitives.interfaces.CipherContext` provider. + If the backend doesn't support the requested combination of ``cipher`` + and ``mode`` a :class:`cryptography.exceptions.NoSuchAlgorithm` will + be raised. + .. method:: decryptor() :return: A decrypting :class:`~cryptography.hazmat.primitives.interfaces.CipherContext` provider. + If the backend doesn't support the requested combination of ``cipher`` + and ``mode`` a :class:`cryptography.exceptions.NoSuchAlgorithm` will + be raised. + + .. currentmodule:: cryptography.hazmat.primitives.interfaces .. class:: CipherContext -- cgit v1.2.3 From 3949f1171084c2e1cfe43f638857ea0e0f8f246d Mon Sep 17 00:00:00 2001 From: Alex Gaynor Date: Sat, 2 Nov 2013 16:57:10 -0700 Subject: Changed excpetion name based on feedback from dreid --- docs/hazmat/primitives/symmetric-encryption.rst | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) (limited to 'docs/hazmat') diff --git a/docs/hazmat/primitives/symmetric-encryption.rst b/docs/hazmat/primitives/symmetric-encryption.rst index 48bad928..c1c8d247 100644 --- a/docs/hazmat/primitives/symmetric-encryption.rst +++ b/docs/hazmat/primitives/symmetric-encryption.rst @@ -43,8 +43,8 @@ where the encrypter and decrypter both use the same key. provider. If the backend doesn't support the requested combination of ``cipher`` - and ``mode`` a :class:`cryptography.exceptions.NoSuchAlgorithm` will - be raised. + and ``mode`` an :class:`cryptography.exceptions.UnsupportedAlgorithm` + will be raised. .. method:: decryptor() @@ -53,8 +53,8 @@ where the encrypter and decrypter both use the same key. provider. If the backend doesn't support the requested combination of ``cipher`` - and ``mode`` a :class:`cryptography.exceptions.NoSuchAlgorithm` will - be raised. + and ``mode`` an :class:`cryptography.exceptions.UnsupportedAlgorithm` + will be raised. .. currentmodule:: cryptography.hazmat.primitives.interfaces -- cgit v1.2.3 From 58ecc8d434078e21deaa2a18312b06d876956b56 Mon Sep 17 00:00:00 2001 From: Alex Gaynor Date: Sun, 3 Nov 2013 21:21:00 -0800 Subject: Refer to the RFC in the HMAC docs --- docs/hazmat/primitives/hmac.rst | 2 ++ 1 file changed, 2 insertions(+) (limited to 'docs/hazmat') diff --git a/docs/hazmat/primitives/hmac.rst b/docs/hazmat/primitives/hmac.rst index 301d72d5..bd1a4934 100644 --- a/docs/hazmat/primitives/hmac.rst +++ b/docs/hazmat/primitives/hmac.rst @@ -23,6 +23,8 @@ message. equal in length to the ``digest_size`` of the hash function chosen. You must keep the ``key`` secret. + This is an implementation of :rfc:`2104`. + .. doctest:: >>> from cryptography.hazmat.primitives import hashes, hmac -- cgit v1.2.3 From 051099ee7ea64b902fc9821f139d0a955bfe8bc4 Mon Sep 17 00:00:00 2001 From: Paul Kehrer Date: Wed, 6 Nov 2013 15:53:40 +0800 Subject: update docs --- docs/hazmat/primitives/symmetric-encryption.rst | 27 ++++++++++++------------- 1 file changed, 13 insertions(+), 14 deletions(-) (limited to 'docs/hazmat') diff --git a/docs/hazmat/primitives/symmetric-encryption.rst b/docs/hazmat/primitives/symmetric-encryption.rst index c1c8d247..7d3b072d 100644 --- a/docs/hazmat/primitives/symmetric-encryption.rst +++ b/docs/hazmat/primitives/symmetric-encryption.rst @@ -4,7 +4,7 @@ Symmetric Encryption ==================== -.. currentmodule:: cryptography.hazmat.primitives.block +.. currentmodule:: cryptography.hazmat.primitives.ciphers .. testsetup:: @@ -16,24 +16,23 @@ 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:: BlockCipher(cipher, mode) +.. class:: Cipher(algorithm, 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 + Cipher objects combine an algorithm (such as AES) with a mode (such as CBC, CTR, or GCM). A simple example of encrypting (and then decrypting) content with AES is: .. doctest:: - >>> from cryptography.hazmat.primitives.block import BlockCipher, ciphers, modes - >>> cipher = BlockCipher(ciphers.AES(key), modes.CBC(iv)) + >>> from cryptography.hazmat.primitives.ciphers import Cipher, algorithms, modes + >>> cipher = Cipher(algorithms.AES(key), modes.CBC(iv)) >>> encryptor = cipher.encryptor() >>> ct = encryptor.update(b"a secret message") + encryptor.finalize() >>> decryptor = cipher.decryptor() >>> decryptor.update(ct) + decryptor.finalize() 'a secret message' - :param cipher: One of the ciphers described below. + :param algorithms: One of the algorithms described below. :param mode: One of the modes described below. .. method:: encryptor() @@ -61,7 +60,7 @@ where the encrypter and decrypter both use the same key. .. class:: CipherContext - When calling ``encryptor()`` or ``decryptor()`` on a ``BlockCipher`` object + When calling ``encryptor()`` or ``decryptor()`` on a ``Cipher`` object you will receive a return object conforming to the ``CipherContext`` interface. You can then call ``update(data)`` with data until you have fed everything into the context. Once that is done call ``finalize()`` to @@ -72,9 +71,9 @@ where the encrypter and decrypter both use the same key. :param bytes data: The data you wish to pass into the context. :return bytes: Returns the data that was encrypted or decrypted. - When the ``BlockCipher`` was constructed in a mode turns it into a + When the ``Cipher`` was constructed in a mode that turns it into a stream cipher (e.g. - :class:`cryptography.hazmat.primitives.block.modes.CTR`), this will + :class:`cryptography.hazmat.primitives.ciphers.modes.CTR`), this will return bytes immediately, however in other modes it will return chunks, whose size is determined by the cipher's block size. @@ -82,10 +81,10 @@ where the encrypter and decrypter both use the same key. :return bytes: Returns the remainder of the data. -Ciphers -~~~~~~~ +Algorithms +~~~~~~~~~~ -.. currentmodule:: cryptography.hazmat.primitives.block.ciphers +.. currentmodule:: cryptography.hazmat.primitives.ciphers.algorithms .. class:: AES(key) @@ -153,7 +152,7 @@ Weak Ciphers Modes ~~~~~ -.. currentmodule:: cryptography.hazmat.primitives.block.modes +.. currentmodule:: cryptography.hazmat.primitives.ciphers.modes .. class:: CBC(initialization_vector) -- 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. --- docs/hazmat/primitives/index.rst | 1 + docs/hazmat/primitives/interfaces.rst | 59 +++++++++++++++++++++++++ docs/hazmat/primitives/symmetric-encryption.rst | 3 ++ 3 files changed, 63 insertions(+) create mode 100644 docs/hazmat/primitives/interfaces.rst (limited to 'docs/hazmat') 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(-) (limited to 'docs/hazmat') 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(-) (limited to 'docs/hazmat') 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 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(-) (limited to 'docs/hazmat') 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(-) (limited to 'docs/hazmat') 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