From 4da28c35d93e14a5e6b0a252751e7cfbaf0fe372 Mon Sep 17 00:00:00 2001 From: Paul Kehrer Date: Thu, 7 Nov 2013 07:50:17 +0800 Subject: ARC4 support --- docs/hazmat/primitives/symmetric-encryption.rst | 10 ++++++++++ 1 file changed, 10 insertions(+) (limited to 'docs/hazmat') diff --git a/docs/hazmat/primitives/symmetric-encryption.rst b/docs/hazmat/primitives/symmetric-encryption.rst index 7d3b072d..4d0703bb 100644 --- a/docs/hazmat/primitives/symmetric-encryption.rst +++ b/docs/hazmat/primitives/symmetric-encryption.rst @@ -149,6 +149,16 @@ Weak Ciphers :param bytes key: The secret key, 32-448 bits in length (in increments of 8). This must be kept secret. +.. class:: ARC4(key) + + ARC4 (Alleged RC4) is a stream cipher with serious weaknesses in its + initial stream output. Its use is strongly discouraged. ARC4 does not use + mode constructions. + + :param bytes key: The secret key, ``40``, ``56``, ``64``, ``80``, ``128``, + ``192``, or ``256`` bits in length. This must be kept + secret. + Modes ~~~~~ -- cgit v1.2.3 From ab5f0116a2fc906b854b0593675492ec5e406a3d Mon Sep 17 00:00:00 2001 From: Alex Gaynor Date: Fri, 8 Nov 2013 10:34:00 -0800 Subject: Be more and more explicit about how to do things correctly --- docs/hazmat/primitives/cryptographic-hashes.rst | 7 ++++--- docs/hazmat/primitives/symmetric-encryption.rst | 23 +++++++++++++++++------ 2 files changed, 21 insertions(+), 9 deletions(-) (limited to 'docs/hazmat') diff --git a/docs/hazmat/primitives/cryptographic-hashes.rst b/docs/hazmat/primitives/cryptographic-hashes.rst index 76ca20c0..20fa23cf 100644 --- a/docs/hazmat/primitives/cryptographic-hashes.rst +++ b/docs/hazmat/primitives/cryptographic-hashes.rst @@ -12,9 +12,9 @@ Message Digests results (with a high probability) in different digests. This is an implementation of - :class:`cryptography.hazmat.primitives.interfaces.HashContext` meant to + :class:`~cryptography.hazmat.primitives.interfaces.HashContext` meant to be used with - :class:`cryptography.hazmat.primitives.interfaces.HashAlgorithm` + :class:`~cryptography.hazmat.primitives.interfaces.HashAlgorithm` implementations to provide an incremental interface to calculating various message digests. @@ -102,7 +102,8 @@ MD5 .. warning:: MD5 is a deprecated hash algorithm that has practical known collision - attacks. You are strongly discouraged from using it. + attacks. You are strongly discouraged from using it. Existing applications + should strongly consider moving away. .. class:: MD5() diff --git a/docs/hazmat/primitives/symmetric-encryption.rst b/docs/hazmat/primitives/symmetric-encryption.rst index 5f1a64a1..5542e832 100644 --- a/docs/hazmat/primitives/symmetric-encryption.rst +++ b/docs/hazmat/primitives/symmetric-encryption.rst @@ -14,13 +14,22 @@ Symmetric Encryption Symmetric encryption is a way to encrypt (hide the plaintext value) material -where the encrypter and decrypter both use the same key. +where the encrypter and decrypter both use the same key. Note that symmetric +encryption is **not** sufficient for most applications, because it only +provides secrecy (an attacker can't see the message) but not authenticity (an +attacker can create bogus messages and force the application to decrypt them). +For this reason it is *strongly* reccomended to combine encryption with a +message authentication code, such as :doc:`HMAC `, in +an "encrypt-then-MAC" formulation as `described by Colin Percival`_. .. class:: Cipher(algorithm, mode) - 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: + Cipher objects combine an algorithm (such as + :class:`~cryptography.hazmat.primitives.ciphers.algorithms.AES`) with a + mode (such as + :class:`~cryptography.hazmat.primitives.ciphers.modes.CBC` or + :class:`~cryptography.hazmat.primitives.ciphers.modes.CTR`). A simple + example of encrypting (and then decrypting) content with AES is: .. doctest:: @@ -143,8 +152,7 @@ Weak Ciphers Blowfish is a block cipher developed by Bruce Schneier. It is known to be susceptible to attacks when using weak keys. The author has recommended - that users of Blowfish move to newer algorithms like - :class:`AES`. + that users of Blowfish move to newer algorithms, such as :class:`AES`. :param bytes key: The secret key, 32-448 bits in length (in increments of 8). This must be kept secret. @@ -252,3 +260,6 @@ Insecure Modes ciphers. Each block of data is encrypted in the same way. This means identical plaintext blocks will always result in identical ciphertext blocks, and thus result in information leakage + + +.. _`described by Colin Percival`: http://www.daemonology.net/blog/2009-06-11-cryptographic-right-answers.html -- cgit v1.2.3 From 0994c5628a3d960a45f8aac33f0d5d985eb48cf7 Mon Sep 17 00:00:00 2001 From: Paul Kehrer Date: Sun, 10 Nov 2013 03:19:14 +0800 Subject: update docs to include arc4 example --- docs/hazmat/primitives/symmetric-encryption.rst | 11 +++++++++++ 1 file changed, 11 insertions(+) (limited to 'docs/hazmat') diff --git a/docs/hazmat/primitives/symmetric-encryption.rst b/docs/hazmat/primitives/symmetric-encryption.rst index 9d18ce50..77e61b56 100644 --- a/docs/hazmat/primitives/symmetric-encryption.rst +++ b/docs/hazmat/primitives/symmetric-encryption.rst @@ -159,6 +159,17 @@ Weak Ciphers ``192``, or ``256`` bits in length. This must be kept secret. + .. doctest:: + + >>> from cryptography.hazmat.primitives.ciphers import Cipher, algorithms, modes + >>> algorithm = algorithms.ARC4(key) + >>> cipher = Cipher(algorithm, mode=None) + >>> encryptor = cipher.encryptor() + >>> ct = encryptor.update(b"a secret message") + >>> decryptor = cipher.decryptor() + >>> decryptor.update(ct) + 'a secret message' + .. _symmetric-encryption-modes: -- cgit v1.2.3 From 6392a9c63ce134c4aceefb8a4eb9da2fa7f4f390 Mon Sep 17 00:00:00 2001 From: David Reid Date: Wed, 13 Nov 2013 10:01:15 -0800 Subject: Document AlreadyFinalized. --- docs/hazmat/primitives/cryptographic-hashes.rst | 13 +++++++++++-- 1 file changed, 11 insertions(+), 2 deletions(-) (limited to 'docs/hazmat') diff --git a/docs/hazmat/primitives/cryptographic-hashes.rst b/docs/hazmat/primitives/cryptographic-hashes.rst index 20fa23cf..7eff1b85 100644 --- a/docs/hazmat/primitives/cryptographic-hashes.rst +++ b/docs/hazmat/primitives/cryptographic-hashes.rst @@ -30,16 +30,25 @@ Message Digests .. method:: update(data) :param bytes data: The bytes you wish to hash. + :raises cryptography.exceptions.AlreadyFinalized: See :meth:`finalize` .. method:: copy() - :return: a new instance of this object with a copied internal state. + Copy this :class:`Hash` instance, usually so that we may call + :meth:`finalize` and get an intermediate digest value while we continue + to call :meth:`update` on the original. + + :return: A new instance of :class:`Hash` which can be updated + and finalized independently of the original instance. + :raises cryptography.exceptions.AlreadyFinalized: See :meth:`finalize` .. method:: finalize() Finalize the current context and return the message digest as bytes. - Once ``finalize`` is called this object can no longer be used. + Once ``finalize`` is called this object can no longer be used and + :meth:`update` and :meth:`copy` will raise + :class:`~cryptography.exceptions.AlreadyFinalized`. :return bytes: The message digest as bytes. -- cgit v1.2.3 From 9480129db921e84253d3b2a8c8e8becb5f8934b3 Mon Sep 17 00:00:00 2001 From: Alex Gaynor Date: Wed, 13 Nov 2013 10:33:01 -0800 Subject: Describe that hashes get real broken over time --- docs/hazmat/primitives/cryptographic-hashes.rst | 9 +++++++++ 1 file changed, 9 insertions(+) (limited to 'docs/hazmat') diff --git a/docs/hazmat/primitives/cryptographic-hashes.rst b/docs/hazmat/primitives/cryptographic-hashes.rst index 20fa23cf..e7b4f2d6 100644 --- a/docs/hazmat/primitives/cryptographic-hashes.rst +++ b/docs/hazmat/primitives/cryptographic-hashes.rst @@ -27,6 +27,12 @@ Message Digests >>> digest.finalize() 'l\xa1=R\xcap\xc8\x83\xe0\xf0\xbb\x10\x1eBZ\x89\xe8bM\xe5\x1d\xb2\xd29%\x93\xafj\x84\x11\x80\x90' + Keep in mind that attacks against cryptographic hashes only get stronger + with time, and that often algorithms that were once thought to be strong, + become broken. Because of this it's important to include a plan for + upgrading the hash algorithm you use over time. For more information, see + `Lifetimes of cryptographic hash functions`_. + .. method:: update(data) :param bytes data: The bytes you wish to hash. @@ -109,3 +115,6 @@ MD5 MD5 is a deprecated cryptographic hash function. It has a 128-bit message digest and has practical known collision attacks. + + +.. _`Lifetimes of cryptographic hash functions`: http://valerieaurora.org/hash.html -- cgit v1.2.3 From 34511c697f6f17915b5fe5a58214bb38d779f4a8 Mon Sep 17 00:00:00 2001 From: Alex Gaynor Date: Wed, 13 Nov 2013 13:30:30 -0800 Subject: Use AlreadyFinalized for symmetric ciphers --- docs/hazmat/primitives/symmetric-encryption.rst | 5 +++++ 1 file changed, 5 insertions(+) (limited to 'docs/hazmat') diff --git a/docs/hazmat/primitives/symmetric-encryption.rst b/docs/hazmat/primitives/symmetric-encryption.rst index 28b143ba..950ea8b0 100644 --- a/docs/hazmat/primitives/symmetric-encryption.rst +++ b/docs/hazmat/primitives/symmetric-encryption.rst @@ -79,6 +79,7 @@ an "encrypt-then-MAC" formulation as `described by Colin Percival`_. :param bytes data: The data you wish to pass into the context. :return bytes: Returns the data that was encrypted or decrypted. + :raises cryptography.exceptions.AlreadyFinalized: See :meth:`finalize` When the ``Cipher`` was constructed in a mode that turns it into a stream cipher (e.g. @@ -90,6 +91,10 @@ an "encrypt-then-MAC" formulation as `described by Colin Percival`_. :return bytes: Returns the remainder of the data. + Once ``finalize`` is called this object can no longer be used and + :meth:`update` will raise + :class:`~cryptography.exceptions.AlreadyFinalized`. + Algorithms ~~~~~~~~~~ -- cgit v1.2.3 From 2cce618311c892aa5a1be2ef899e8ff7a08ae5ef Mon Sep 17 00:00:00 2001 From: David Reid Date: Wed, 13 Nov 2013 13:49:41 -0800 Subject: Make HMAC methods raise AlreadyFinalized. --- docs/hazmat/primitives/hmac.rst | 14 ++++++++++++-- 1 file changed, 12 insertions(+), 2 deletions(-) (limited to 'docs/hazmat') diff --git a/docs/hazmat/primitives/hmac.rst b/docs/hazmat/primitives/hmac.rst index bd1a4934..cff2dbf1 100644 --- a/docs/hazmat/primitives/hmac.rst +++ b/docs/hazmat/primitives/hmac.rst @@ -36,15 +36,25 @@ message. .. method:: update(msg) :param bytes msg: The bytes to hash and authenticate. + :raises cryptography.exceptions.AlreadyFinalized: See :meth:`finalize` .. method:: copy() - :return: a new instance of this object with a copied internal state. + Copy this :class:`HMAC` instance, usually so that we may call + :meth:`finalize` and get an intermediate digest value while we continue + to call :meth:`update` on the original. + + :return: A new instance of :class:`HMAC` which can be updated + and finalized independently of the original instance. + :raises cryptography.exceptions.AlreadyFinalized: See :meth:`finalize` .. method:: finalize() Finalize the current context and return the message digest as bytes. - Once ``finalize`` is called this object can no longer be used. + Once ``finalize`` is called this object can no longer be used and + :meth:`update`, :meth:`copy`, and :meth:`finalize` will raise + :class:`~cryptography.exceptions.AlreadyFinalized`. :return bytes: The message digest as bytes. + :raises cryptography.exceptions.AlreadyFinalized: -- cgit v1.2.3 From 9b70ba37ff66e18b67efd0f7d196becc77763c41 Mon Sep 17 00:00:00 2001 From: Alex Gaynor Date: Wed, 13 Nov 2013 13:49:43 -0800 Subject: Also mention finalize --- 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 950ea8b0..4ef15459 100644 --- a/docs/hazmat/primitives/symmetric-encryption.rst +++ b/docs/hazmat/primitives/symmetric-encryption.rst @@ -92,7 +92,7 @@ an "encrypt-then-MAC" formulation as `described by Colin Percival`_. :return bytes: Returns the remainder of the data. Once ``finalize`` is called this object can no longer be used and - :meth:`update` will raise + :meth:`update` and :meth:`finalize` will raise :class:`~cryptography.exceptions.AlreadyFinalized`. Algorithms -- cgit v1.2.3 From 272d537b90af00e5e5153f3818aee7ffe1df4f65 Mon Sep 17 00:00:00 2001 From: Alex Gaynor Date: Wed, 13 Nov 2013 13:50:02 -0800 Subject: Here too --- docs/hazmat/primitives/cryptographic-hashes.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'docs/hazmat') diff --git a/docs/hazmat/primitives/cryptographic-hashes.rst b/docs/hazmat/primitives/cryptographic-hashes.rst index 525fd889..52e87702 100644 --- a/docs/hazmat/primitives/cryptographic-hashes.rst +++ b/docs/hazmat/primitives/cryptographic-hashes.rst @@ -53,7 +53,7 @@ Message Digests Finalize the current context and return the message digest as bytes. Once ``finalize`` is called this object can no longer be used and - :meth:`update` and :meth:`copy` will raise + :meth:`update`, :meth:`copy`, and :meth:`finalize` will raise :class:`~cryptography.exceptions.AlreadyFinalized`. :return bytes: The message digest as bytes. -- cgit v1.2.3 From 0a394df31c4165d0230843ebea2717b3cd3caafa Mon Sep 17 00:00:00 2001 From: David Reid Date: Fri, 15 Nov 2013 16:19:50 -0800 Subject: Implement and document an interface for cipher algorithms --- docs/hazmat/primitives/interfaces.rst | 26 ++++++++++++++++++++++++-- 1 file changed, 24 insertions(+), 2 deletions(-) (limited to 'docs/hazmat') diff --git a/docs/hazmat/primitives/interfaces.rst b/docs/hazmat/primitives/interfaces.rst index 7068316e..11cff51a 100644 --- a/docs/hazmat/primitives/interfaces.rst +++ b/docs/hazmat/primitives/interfaces.rst @@ -12,11 +12,33 @@ to document argument and return types. .. _`Abstract Base Classes`: http://docs.python.org/3.2/library/abc.html -Cipher Modes -~~~~~~~~~~~~ +Symmetric Ciphers +~~~~~~~~~~~~~~~~~ .. currentmodule:: cryptography.hazmat.primitives.interfaces + +.. class:: CipherAlgorithm + + A named symmetric encryption algorithm. + + .. attribute:: name + + :type: str + + The standard name for the mode, for example, "AES", "Camellia", or + "Blowfish". + + .. attribute:: key_size + + :type: int + + The number of bits in the key being used. + + +Cipher Modes +------------ + Interfaces used by the symmetric cipher modes described in :ref:`Symmetric Encryption Modes `. -- cgit v1.2.3 From 9316f4c54edc24487d75c7bc3cb3490d79e364a3 Mon Sep 17 00:00:00 2001 From: Alex Gaynor Date: Fri, 15 Nov 2013 16:38:42 -0800 Subject: Fixed some spelling mistakes --- 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 4ef15459..984fe81d 100644 --- a/docs/hazmat/primitives/symmetric-encryption.rst +++ b/docs/hazmat/primitives/symmetric-encryption.rst @@ -18,7 +18,7 @@ where the encrypter and decrypter both use the same key. Note that symmetric encryption is **not** sufficient for most applications, because it only provides secrecy (an attacker can't see the message) but not authenticity (an attacker can create bogus messages and force the application to decrypt them). -For this reason it is *strongly* reccomended to combine encryption with a +For this reason it is *strongly* recommended to combine encryption with a message authentication code, such as :doc:`HMAC `, in an "encrypt-then-MAC" formulation as `described by Colin Percival`_. @@ -121,10 +121,10 @@ Algorithms .. class:: TripleDES(key) - Triple DES (Data Encryption Standard), sometimes refered to as 3DES, is a - block cipher standardized by NIST. Triple DES has known cryptoanalytic + Triple DES (Data Encryption Standard), sometimes referred to as 3DES, is a + block cipher standardized by NIST. Triple DES has known crypto-analytic flaws, however none of them currently enable a practical attack. - Nonetheless, Triples DES is not reccomended for new applications because it + Nonetheless, Triples DES is not recommended for new applications because it is incredibly slow; old applications should consider moving away from it. :param bytes key: The secret key, either ``64``, ``128``, or ``192`` bits -- cgit v1.2.3 From b317c7a0dd197140b7ef1fd3446941f5b568e645 Mon Sep 17 00:00:00 2001 From: Alex Gaynor Date: Fri, 15 Nov 2013 16:45:52 -0800 Subject: Another two --- 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 984fe81d..eef359d6 100644 --- a/docs/hazmat/primitives/symmetric-encryption.rst +++ b/docs/hazmat/primitives/symmetric-encryption.rst @@ -14,7 +14,7 @@ Symmetric Encryption Symmetric encryption is a way to encrypt (hide the plaintext value) material -where the encrypter and decrypter both use the same key. Note that symmetric +where the sender and receiver both use the same key. Note that symmetric encryption is **not** sufficient for most applications, because it only provides secrecy (an attacker can't see the message) but not authenticity (an attacker can create bogus messages and force the application to decrypt them). -- cgit v1.2.3