From 1a278a81663e4a81c7dacaacf1c3aa5a6ace8907 Mon Sep 17 00:00:00 2001 From: Alex Gaynor Date: Wed, 27 Nov 2013 13:40:45 -0600 Subject: Learn how to spell a word --- docs/hazmat/primitives/symmetric-encryption.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'docs/hazmat/primitives') diff --git a/docs/hazmat/primitives/symmetric-encryption.rst b/docs/hazmat/primitives/symmetric-encryption.rst index 4ab91408..edf3c050 100644 --- a/docs/hazmat/primitives/symmetric-encryption.rst +++ b/docs/hazmat/primitives/symmetric-encryption.rst @@ -89,7 +89,7 @@ an "encrypt-then-MAC" formulation as `described by Colin Percival`_. Block ciphers require that plaintext or ciphertext always be a multiple of their block size, because of that **padding** is often required to make a message the correct size. ``CipherContext`` will not automatically apply - any padding; you'll need to add your own. For block ciphers the reccomended + any padding; you'll need to add your own. For block ciphers the recommended padding is :class:`cryptography.hazmat.primitives.padding.PKCS7`. If you are using a stream cipher mode (such as :class:`cryptography.hazmat.primitives.modes.CTR`) you don't have to worry -- cgit v1.2.3 From 22e80cb96e034679750a38702aaa55e30da05f69 Mon Sep 17 00:00:00 2001 From: Paul Kehrer Date: Wed, 20 Nov 2013 21:27:00 -0600 Subject: GCM support --- docs/hazmat/primitives/symmetric-encryption.rst | 48 +++++++++++++++++++++++++ 1 file changed, 48 insertions(+) (limited to 'docs/hazmat/primitives') diff --git a/docs/hazmat/primitives/symmetric-encryption.rst b/docs/hazmat/primitives/symmetric-encryption.rst index edf3c050..5b249c06 100644 --- a/docs/hazmat/primitives/symmetric-encryption.rst +++ b/docs/hazmat/primitives/symmetric-encryption.rst @@ -118,6 +118,27 @@ an "encrypt-then-MAC" formulation as `described by Colin Percival`_. :meth:`update` and :meth:`finalize` will raise :class:`~cryptography.exceptions.AlreadyFinalized`. +.. class:: AEADCipherContext + + When calling ``encryptor()`` or ``decryptor()`` on a ``Cipher`` object + with an AEAD mode you will receive a return object conforming to the + ``AEADCipherContext`` interface in addition to the ``CipherContext`` + interface. ``AEADCipherContext`` contains an additional method ``add_data`` + for adding additional authenticated by non-encrypted data. You should call + this before calls to ``update``. When you are done call ``finalize()`` to + finish the operation. Once this is complete you can obtain the tag value + from the ``tag`` property. + + .. method:: add_data(data) + + :param bytes data: The data you wish to authenticate but not encrypt. + :raises: :class:`~cryptography.exceptions.AlreadyFinalized` + + .. method:: tag + + :return bytes: Returns the tag value as bytes. + :raises: :class:`~cryptography.exceptions.NotFinalized` + .. _symmetric-encryption-algorithms: Algorithms @@ -295,6 +316,33 @@ Modes reuse an ``initialization_vector`` with a given ``key``. +.. class:: GCM(initialization_vector, tag=None) + + GCM (Galois Counter Mode) is a mode of operation for block ciphers. It + is an AEAD (authenticated encryption with additional data) mode. + + :param bytes initialization_vector: Must be random bytes. They do not need + to be kept secret (they can be included + in a transmitted message). Recommended + to be 96-bit by NIST, but can be up to + 2\ :sup:`64` - 1 bits. Do not reuse an + ``initialization_vector`` with a given + ``key``. + + .. doctest:: + + >>> from cryptography.hazmat.primitives.ciphers import Cipher, algorithms, modes + >>> cipher = Cipher(algorithms.AES(key), modes.GCM(iv)) + >>> encryptor = cipher.encryptor() + >>> encryptor.add_data(b"authenticated but encrypted payload") + >>> ct = encryptor.update(b"a secret message") + encryptor.finalize() + >>> tag = encryptor.tag + >>> cipher = Cipher(algorithms.AES(key), modes.GCM(iv, tag)) + >>> decryptor = cipher.decryptor() + >>> decryptor.add_data(b"authenticated but encrypted payload") + >>> decryptor.update(ct) + decryptor.finalize() + 'a secret message' + Insecure Modes -------------- -- cgit v1.2.3 From 65c4e0a396b9d4183d9ce16b27742d407eb9d91d Mon Sep 17 00:00:00 2001 From: Paul Kehrer Date: Thu, 21 Nov 2013 11:20:56 -0600 Subject: gcm doc fixes --- docs/hazmat/primitives/symmetric-encryption.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) (limited to 'docs/hazmat/primitives') diff --git a/docs/hazmat/primitives/symmetric-encryption.rst b/docs/hazmat/primitives/symmetric-encryption.rst index 5b249c06..bd9a3f60 100644 --- a/docs/hazmat/primitives/symmetric-encryption.rst +++ b/docs/hazmat/primitives/symmetric-encryption.rst @@ -122,7 +122,7 @@ an "encrypt-then-MAC" formulation as `described by Colin Percival`_. When calling ``encryptor()`` or ``decryptor()`` on a ``Cipher`` object with an AEAD mode you will receive a return object conforming to the - ``AEADCipherContext`` interface in addition to the ``CipherContext`` + ``AEADCipherContext`` interface, in addition to the ``CipherContext`` interface. ``AEADCipherContext`` contains an additional method ``add_data`` for adding additional authenticated by non-encrypted data. You should call this before calls to ``update``. When you are done call ``finalize()`` to @@ -134,7 +134,7 @@ an "encrypt-then-MAC" formulation as `described by Colin Percival`_. :param bytes data: The data you wish to authenticate but not encrypt. :raises: :class:`~cryptography.exceptions.AlreadyFinalized` - .. method:: tag + .. attribute:: tag :return bytes: Returns the tag value as bytes. :raises: :class:`~cryptography.exceptions.NotFinalized` -- cgit v1.2.3 From 6331daa36902edf5a5dd04e4e3fa0e188db59420 Mon Sep 17 00:00:00 2001 From: Paul Kehrer Date: Fri, 22 Nov 2013 13:42:02 -0600 Subject: gcm doc improvements --- docs/hazmat/primitives/symmetric-encryption.rst | 8 ++++++-- 1 file changed, 6 insertions(+), 2 deletions(-) (limited to 'docs/hazmat/primitives') diff --git a/docs/hazmat/primitives/symmetric-encryption.rst b/docs/hazmat/primitives/symmetric-encryption.rst index bd9a3f60..4e7990b0 100644 --- a/docs/hazmat/primitives/symmetric-encryption.rst +++ b/docs/hazmat/primitives/symmetric-encryption.rst @@ -137,7 +137,8 @@ an "encrypt-then-MAC" formulation as `described by Colin Percival`_. .. attribute:: tag :return bytes: Returns the tag value as bytes. - :raises: :class:`~cryptography.exceptions.NotFinalized` + :raises: :class:`~cryptography.exceptions.NotYetFinalized` if called + before the context is finalized. .. _symmetric-encryption-algorithms: @@ -319,7 +320,10 @@ Modes .. class:: GCM(initialization_vector, tag=None) GCM (Galois Counter Mode) is a mode of operation for block ciphers. It - is an AEAD (authenticated encryption with additional data) mode. + is an AEAD (authenticated encryption with additional data) mode. AEAD + is a type of block cipher mode that encrypts the message as well as + authenticating it (and optionally additional data that is not encrypted) + simultaneously. :param bytes initialization_vector: Must be random bytes. They do not need to be kept secret (they can be included -- cgit v1.2.3 From 2631c2b7be22f15f83810df1b8664bf388ad02a6 Mon Sep 17 00:00:00 2001 From: Paul Kehrer Date: Sun, 24 Nov 2013 10:20:50 -0600 Subject: gcm doc fixes (per review from alex) --- docs/hazmat/primitives/symmetric-encryption.rst | 7 ++++--- 1 file changed, 4 insertions(+), 3 deletions(-) (limited to 'docs/hazmat/primitives') diff --git a/docs/hazmat/primitives/symmetric-encryption.rst b/docs/hazmat/primitives/symmetric-encryption.rst index 4e7990b0..3ed8c9e2 100644 --- a/docs/hazmat/primitives/symmetric-encryption.rst +++ b/docs/hazmat/primitives/symmetric-encryption.rst @@ -323,7 +323,8 @@ Modes is an AEAD (authenticated encryption with additional data) mode. AEAD is a type of block cipher mode that encrypts the message as well as authenticating it (and optionally additional data that is not encrypted) - simultaneously. + simultaneously. Additional means of verifying integrity (like + :doc:`HMAC `) are not necessary. :param bytes initialization_vector: Must be random bytes. They do not need to be kept secret (they can be included @@ -338,12 +339,12 @@ Modes >>> from cryptography.hazmat.primitives.ciphers import Cipher, algorithms, modes >>> cipher = Cipher(algorithms.AES(key), modes.GCM(iv)) >>> encryptor = cipher.encryptor() - >>> encryptor.add_data(b"authenticated but encrypted payload") + >>> encryptor.add_data(b"authenticated but not encrypted payload") >>> ct = encryptor.update(b"a secret message") + encryptor.finalize() >>> tag = encryptor.tag >>> cipher = Cipher(algorithms.AES(key), modes.GCM(iv, tag)) >>> decryptor = cipher.decryptor() - >>> decryptor.add_data(b"authenticated but encrypted payload") + >>> decryptor.add_data(b"authenticated but not encrypted payload") >>> decryptor.update(ct) + decryptor.finalize() 'a secret message' -- cgit v1.2.3 From bc31fb22979df3f034ce286fab20da71be76fe58 Mon Sep 17 00:00:00 2001 From: Paul Kehrer Date: Sun, 24 Nov 2013 11:03:53 -0600 Subject: rename add_data to authenticate_additional_data for clarity (hopefully) --- docs/hazmat/primitives/symmetric-encryption.rst | 16 ++++++++-------- 1 file changed, 8 insertions(+), 8 deletions(-) (limited to 'docs/hazmat/primitives') diff --git a/docs/hazmat/primitives/symmetric-encryption.rst b/docs/hazmat/primitives/symmetric-encryption.rst index 3ed8c9e2..d123d15c 100644 --- a/docs/hazmat/primitives/symmetric-encryption.rst +++ b/docs/hazmat/primitives/symmetric-encryption.rst @@ -123,13 +123,13 @@ an "encrypt-then-MAC" formulation as `described by Colin Percival`_. When calling ``encryptor()`` or ``decryptor()`` on a ``Cipher`` object with an AEAD mode you will receive a return object conforming to the ``AEADCipherContext`` interface, in addition to the ``CipherContext`` - interface. ``AEADCipherContext`` contains an additional method ``add_data`` - for adding additional authenticated by non-encrypted data. You should call - this before calls to ``update``. When you are done call ``finalize()`` to - finish the operation. Once this is complete you can obtain the tag value - from the ``tag`` property. + interface. ``AEADCipherContext`` contains an additional method + ``authenticate_additional_data`` for adding additional authenticated but + unencrypted data. You should call this before calls to ``update``. When you + are done call ``finalize()`` to finish the operation. Once this is complete + you can obtain the tag value from the ``tag`` property. - .. method:: add_data(data) + .. method:: authenticate_additional_data(data) :param bytes data: The data you wish to authenticate but not encrypt. :raises: :class:`~cryptography.exceptions.AlreadyFinalized` @@ -339,12 +339,12 @@ Modes >>> from cryptography.hazmat.primitives.ciphers import Cipher, algorithms, modes >>> cipher = Cipher(algorithms.AES(key), modes.GCM(iv)) >>> encryptor = cipher.encryptor() - >>> encryptor.add_data(b"authenticated but not encrypted payload") + >>> encryptor.authenticate_additional_data(b"authenticated but not encrypted payload") >>> ct = encryptor.update(b"a secret message") + encryptor.finalize() >>> tag = encryptor.tag >>> cipher = Cipher(algorithms.AES(key), modes.GCM(iv, tag)) >>> decryptor = cipher.decryptor() - >>> decryptor.add_data(b"authenticated but not encrypted payload") + >>> decryptor.authenticate_additional_data(b"authenticated but not encrypted payload") >>> decryptor.update(ct) + decryptor.finalize() 'a secret message' -- cgit v1.2.3 From 0092c205657789e15848c7848eec768720de468f Mon Sep 17 00:00:00 2001 From: Paul Kehrer Date: Sun, 24 Nov 2013 11:39:14 -0600 Subject: raise TypeError if you attempt to get the tag attribute on a decrypt * To support this the _AEADCipherContext in base.py now needs to be aware of whether it is encrypting/decrypting --- docs/hazmat/primitives/symmetric-encryption.rst | 1 + 1 file changed, 1 insertion(+) (limited to 'docs/hazmat/primitives') diff --git a/docs/hazmat/primitives/symmetric-encryption.rst b/docs/hazmat/primitives/symmetric-encryption.rst index d123d15c..f35357d0 100644 --- a/docs/hazmat/primitives/symmetric-encryption.rst +++ b/docs/hazmat/primitives/symmetric-encryption.rst @@ -139,6 +139,7 @@ an "encrypt-then-MAC" formulation as `described by Colin Percival`_. :return bytes: Returns the tag value as bytes. :raises: :class:`~cryptography.exceptions.NotYetFinalized` if called before the context is finalized. + :raises TypeError: If called on a decryption context. .. _symmetric-encryption-algorithms: -- cgit v1.2.3 From 67abc864cb64033333aa08a03fba1dd153074dfd Mon Sep 17 00:00:00 2001 From: Paul Kehrer Date: Mon, 25 Nov 2013 14:29:35 -0600 Subject: document tag param for GCM object --- docs/hazmat/primitives/symmetric-encryption.rst | 3 +++ 1 file changed, 3 insertions(+) (limited to 'docs/hazmat/primitives') diff --git a/docs/hazmat/primitives/symmetric-encryption.rst b/docs/hazmat/primitives/symmetric-encryption.rst index f35357d0..70c3d2f4 100644 --- a/docs/hazmat/primitives/symmetric-encryption.rst +++ b/docs/hazmat/primitives/symmetric-encryption.rst @@ -335,6 +335,9 @@ Modes ``initialization_vector`` with a given ``key``. + :param bytes tag: The tag bytes to verify during decryption. Must be provided + for decryption, but is ignored when encrypting. + .. doctest:: >>> from cryptography.hazmat.primitives.ciphers import Cipher, algorithms, modes -- cgit v1.2.3 From 26c8c6adcb9a6485966070418080a17cd2445bed Mon Sep 17 00:00:00 2001 From: Paul Kehrer Date: Fri, 29 Nov 2013 16:24:56 -0600 Subject: begin adding warnings to GCM mode --- docs/hazmat/primitives/symmetric-encryption.rst | 6 ++++++ 1 file changed, 6 insertions(+) (limited to 'docs/hazmat/primitives') diff --git a/docs/hazmat/primitives/symmetric-encryption.rst b/docs/hazmat/primitives/symmetric-encryption.rst index 70c3d2f4..a77e0e79 100644 --- a/docs/hazmat/primitives/symmetric-encryption.rst +++ b/docs/hazmat/primitives/symmetric-encryption.rst @@ -320,6 +320,12 @@ Modes .. class:: GCM(initialization_vector, tag=None) + .. warning:: + + When using this mode you MUST not use the decrypted data until every + byte has been decrypted. GCM provides NO guarantees of ciphertext + integrity until decryption is complete. + GCM (Galois Counter Mode) is a mode of operation for block ciphers. It is an AEAD (authenticated encryption with additional data) mode. AEAD is a type of block cipher mode that encrypts the message as well as -- cgit v1.2.3 From e0b5bb18c3963ebaa66d537d2cf00c2cc0dd804c Mon Sep 17 00:00:00 2001 From: Paul Kehrer Date: Fri, 29 Nov 2013 16:35:04 -0600 Subject: explicit backend fix for gcm docs --- docs/hazmat/primitives/symmetric-encryption.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) (limited to 'docs/hazmat/primitives') diff --git a/docs/hazmat/primitives/symmetric-encryption.rst b/docs/hazmat/primitives/symmetric-encryption.rst index a77e0e79..aefc2d7e 100644 --- a/docs/hazmat/primitives/symmetric-encryption.rst +++ b/docs/hazmat/primitives/symmetric-encryption.rst @@ -347,12 +347,12 @@ Modes .. doctest:: >>> from cryptography.hazmat.primitives.ciphers import Cipher, algorithms, modes - >>> cipher = Cipher(algorithms.AES(key), modes.GCM(iv)) + >>> cipher = Cipher(algorithms.AES(key), modes.GCM(iv), backend) >>> encryptor = cipher.encryptor() >>> encryptor.authenticate_additional_data(b"authenticated but not encrypted payload") >>> ct = encryptor.update(b"a secret message") + encryptor.finalize() >>> tag = encryptor.tag - >>> cipher = Cipher(algorithms.AES(key), modes.GCM(iv, tag)) + >>> cipher = Cipher(algorithms.AES(key), modes.GCM(iv, tag), backend) >>> decryptor = cipher.decryptor() >>> decryptor.authenticate_additional_data(b"authenticated but not encrypted payload") >>> decryptor.update(ct) + decryptor.finalize() -- cgit v1.2.3 From 5b828b142b4e8fea021567038e2dba6cf6cd9221 Mon Sep 17 00:00:00 2001 From: Paul Kehrer Date: Fri, 29 Nov 2013 17:32:08 -0600 Subject: attempt to document the new interfaces for AEAD --- docs/hazmat/primitives/symmetric-encryption.rst | 26 +++++++++++++++++++------ 1 file changed, 20 insertions(+), 6 deletions(-) (limited to 'docs/hazmat/primitives') diff --git a/docs/hazmat/primitives/symmetric-encryption.rst b/docs/hazmat/primitives/symmetric-encryption.rst index aefc2d7e..9d4f0355 100644 --- a/docs/hazmat/primitives/symmetric-encryption.rst +++ b/docs/hazmat/primitives/symmetric-encryption.rst @@ -122,24 +122,38 @@ an "encrypt-then-MAC" formulation as `described by Colin Percival`_. When calling ``encryptor()`` or ``decryptor()`` on a ``Cipher`` object with an AEAD mode you will receive a return object conforming to the - ``AEADCipherContext`` interface, in addition to the ``CipherContext`` - interface. ``AEADCipherContext`` contains an additional method + ``AEADCipherContext`` interface (in addition to the ``CipherContext`` + interface and either the ``AEADEncryptionContext`` or ``AEADDecryptionContext`` + interface). ``AEADCipherContext`` contains an additional method ``authenticate_additional_data`` for adding additional authenticated but unencrypted data. You should call this before calls to ``update``. When you - are done call ``finalize()`` to finish the operation. Once this is complete - you can obtain the tag value from the ``tag`` property. + are done call ``finalize()`` to finish the operation. .. method:: authenticate_additional_data(data) :param bytes data: The data you wish to authenticate but not encrypt. :raises: :class:`~cryptography.exceptions.AlreadyFinalized` +.. class:: AEADEncryptionContext + + When creating an encryption context using ``encryptor()`` on a ``Cipher`` + object with an AEAD mode you will receive a return object conforming to the + ``AEADEncryptionContext`` interface (as well as ``AEADCipherContext``). + This interface provides one additional attribute ``tag``. ``tag`` can only + be obtained after ``finalize()``. + .. attribute:: tag :return bytes: Returns the tag value as bytes. :raises: :class:`~cryptography.exceptions.NotYetFinalized` if called before the context is finalized. - :raises TypeError: If called on a decryption context. + +.. class:: AEADDecryptionContext + + When creating an encryption context using ``encryptor()`` on a ``Cipher`` + object with an AEAD mode you will receive a return object conforming to the + ``AEADDecryptionContext`` interface (as well as ``AEADCipherContext``). This + interface does not provide any additional methods or attributes. .. _symmetric-encryption-algorithms: @@ -320,7 +334,7 @@ Modes .. class:: GCM(initialization_vector, tag=None) - .. warning:: + .. danger:: When using this mode you MUST not use the decrypted data until every byte has been decrypted. GCM provides NO guarantees of ciphertext -- cgit v1.2.3 From 5578c66babf3cb214114617bdd29c28129f31c37 Mon Sep 17 00:00:00 2001 From: Paul Kehrer Date: Tue, 3 Dec 2013 17:37:42 -0600 Subject: improve language for gcm docs --- docs/hazmat/primitives/symmetric-encryption.rst | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) (limited to 'docs/hazmat/primitives') diff --git a/docs/hazmat/primitives/symmetric-encryption.rst b/docs/hazmat/primitives/symmetric-encryption.rst index 9d4f0355..c97d6b0b 100644 --- a/docs/hazmat/primitives/symmetric-encryption.rst +++ b/docs/hazmat/primitives/symmetric-encryption.rst @@ -340,11 +340,11 @@ Modes byte has been decrypted. GCM provides NO guarantees of ciphertext integrity until decryption is complete. - GCM (Galois Counter Mode) is a mode of operation for block ciphers. It - is an AEAD (authenticated encryption with additional data) mode. AEAD - is a type of block cipher mode that encrypts the message as well as - authenticating it (and optionally additional data that is not encrypted) - simultaneously. Additional means of verifying integrity (like + GCM (Galois Counter Mode) is a mode of operation for block ciphers. An + AEAD (authenticated encryption with additional data) mode is a type of + block cipher mode that encrypts the message as well as authenticating it + (and optionally additional data that is not encrypted) simultaneously. + Additional means of verifying integrity (like :doc:`HMAC `) are not necessary. :param bytes initialization_vector: Must be random bytes. They do not need -- cgit v1.2.3 From cd28a7cca32c734ddd7f7ad353b27b2cf276aa6e Mon Sep 17 00:00:00 2001 From: Paul Kehrer Date: Tue, 3 Dec 2013 18:17:57 -0600 Subject: remove AEADDecryptionContext references from GCM docs --- docs/hazmat/primitives/symmetric-encryption.rst | 17 +++++------------ 1 file changed, 5 insertions(+), 12 deletions(-) (limited to 'docs/hazmat/primitives') diff --git a/docs/hazmat/primitives/symmetric-encryption.rst b/docs/hazmat/primitives/symmetric-encryption.rst index c97d6b0b..bb0308bc 100644 --- a/docs/hazmat/primitives/symmetric-encryption.rst +++ b/docs/hazmat/primitives/symmetric-encryption.rst @@ -123,11 +123,11 @@ an "encrypt-then-MAC" formulation as `described by Colin Percival`_. When calling ``encryptor()`` or ``decryptor()`` on a ``Cipher`` object with an AEAD mode you will receive a return object conforming to the ``AEADCipherContext`` interface (in addition to the ``CipherContext`` - interface and either the ``AEADEncryptionContext`` or ``AEADDecryptionContext`` - interface). ``AEADCipherContext`` contains an additional method - ``authenticate_additional_data`` for adding additional authenticated but - unencrypted data. You should call this before calls to ``update``. When you - are done call ``finalize()`` to finish the operation. + interface). If it is an encryption context it will additionally be an + ``AEADEncryptionContext`` interface. ``AEADCipherContext`` contains an + additional method ``authenticate_additional_data`` for adding additional + authenticated but unencrypted data. You should call this before calls to + ``update``. When you are done call ``finalize()`` to finish the operation. .. method:: authenticate_additional_data(data) @@ -148,13 +148,6 @@ an "encrypt-then-MAC" formulation as `described by Colin Percival`_. :raises: :class:`~cryptography.exceptions.NotYetFinalized` if called before the context is finalized. -.. class:: AEADDecryptionContext - - When creating an encryption context using ``encryptor()`` on a ``Cipher`` - object with an AEAD mode you will receive a return object conforming to the - ``AEADDecryptionContext`` interface (as well as ``AEADCipherContext``). This - interface does not provide any additional methods or attributes. - .. _symmetric-encryption-algorithms: Algorithms -- cgit v1.2.3 From 672843712d6b42404fea27a07a87b70d850cc0dd Mon Sep 17 00:00:00 2001 From: Paul Kehrer Date: Tue, 3 Dec 2013 18:58:14 -0600 Subject: link to NIST GCM PDF where NIST recommends 96-bit IV for perf with GCM Clarify that 96-bit IV is only recommended in performance critical situations...otherwise feel free to use something longer. --- docs/hazmat/primitives/symmetric-encryption.rst | 12 +++++++----- 1 file changed, 7 insertions(+), 5 deletions(-) (limited to 'docs/hazmat/primitives') diff --git a/docs/hazmat/primitives/symmetric-encryption.rst b/docs/hazmat/primitives/symmetric-encryption.rst index bb0308bc..8d8d558b 100644 --- a/docs/hazmat/primitives/symmetric-encryption.rst +++ b/docs/hazmat/primitives/symmetric-encryption.rst @@ -342,11 +342,12 @@ Modes :param bytes initialization_vector: Must be random bytes. They do not need to be kept secret (they can be included - in a transmitted message). Recommended - to be 96-bit by NIST, but can be up to - 2\ :sup:`64` - 1 bits. Do not reuse an - ``initialization_vector`` with a given - ``key``. + in a transmitted message). NIST + `recommends 96-bit IV length`_ for + performance critical situations, but it + can be up to 2\ :sup:`64` - 1 bits. + Do not reuse an ``initialization_vector`` + with a given ``key``. :param bytes tag: The tag bytes to verify during decryption. Must be provided for decryption, but is ignored when encrypting. @@ -384,3 +385,4 @@ Insecure Modes .. _`described by Colin Percival`: http://www.daemonology.net/blog/2009-06-11-cryptographic-right-answers.html +.. _`recommends 96-bit IV length`: http://csrc.nist.gov/groups/ST/toolkit/BCM/documents/proposedmodes/gcm/gcm-spec.pdf -- cgit v1.2.3 From d4f938303d1c5813bf23a8acfe9326817bcd95e9 Mon Sep 17 00:00:00 2001 From: Alex Gaynor Date: Wed, 4 Dec 2013 16:31:59 -0600 Subject: Be more specific about when you can trust authentication on GCM --- docs/hazmat/primitives/symmetric-encryption.rst | 7 ++++--- 1 file changed, 4 insertions(+), 3 deletions(-) (limited to 'docs/hazmat/primitives') diff --git a/docs/hazmat/primitives/symmetric-encryption.rst b/docs/hazmat/primitives/symmetric-encryption.rst index 8d8d558b..977a897b 100644 --- a/docs/hazmat/primitives/symmetric-encryption.rst +++ b/docs/hazmat/primitives/symmetric-encryption.rst @@ -329,9 +329,10 @@ Modes .. danger:: - When using this mode you MUST not use the decrypted data until every - byte has been decrypted. GCM provides NO guarantees of ciphertext - integrity until decryption is complete. + When using this mode you MUST not use the decrypted data until + :meth:`cryptography.hazmat.primitives.interfaces.CipherContext.finalize` + has been called. GCM provides NO guarantees of ciphertext integrity + until decryption is complete. GCM (Galois Counter Mode) is a mode of operation for block ciphers. An AEAD (authenticated encryption with additional data) mode is a type of -- cgit v1.2.3 From 9c3088fe12d844a2007e0eff0eb947af53de7f60 Mon Sep 17 00:00:00 2001 From: Julian Krause Date: Wed, 4 Dec 2013 14:49:50 -0800 Subject: Beginnings of a constant_time module. --- docs/hazmat/primitives/constant-time.rst | 24 ++++++++++++++++++++++++ docs/hazmat/primitives/index.rst | 1 + 2 files changed, 25 insertions(+) create mode 100644 docs/hazmat/primitives/constant-time.rst (limited to 'docs/hazmat/primitives') diff --git a/docs/hazmat/primitives/constant-time.rst b/docs/hazmat/primitives/constant-time.rst new file mode 100644 index 00000000..2e8e26d7 --- /dev/null +++ b/docs/hazmat/primitives/constant-time.rst @@ -0,0 +1,24 @@ +.. hazmat:: + +Constant time functions +======================= + +.. currentmodule:: cryptography.hazmat.primitives.constant_time + +In order for cryptographic operations to not leak information through timing +side channels, constant time operations need to be made available. + +.. function:: bytes_eq(a, b) + + Compare ``a`` and ``b`` to one another in constant time. + + .. doctest:: + + >>> from cryptography.hazmat.primitives import constant_time + >>> constant_time.bytes_eq(b"foo", b"foo") + True + >>> constant_time.bytes_eq(b"foo", b"bar") + False + + :param a: ``bytes``. + :param b: ``bytes``. diff --git a/docs/hazmat/primitives/index.rst b/docs/hazmat/primitives/index.rst index 614c414a..b115fdbc 100644 --- a/docs/hazmat/primitives/index.rst +++ b/docs/hazmat/primitives/index.rst @@ -10,4 +10,5 @@ Primitives hmac symmetric-encryption padding + constant-time interfaces -- cgit v1.2.3 From 0d23e94a09ea8c88d51692696363d9215c57b72a Mon Sep 17 00:00:00 2001 From: Alex Gaynor Date: Wed, 4 Dec 2013 17:28:24 -0600 Subject: Don't show so much stuff --- docs/hazmat/primitives/symmetric-encryption.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'docs/hazmat/primitives') diff --git a/docs/hazmat/primitives/symmetric-encryption.rst b/docs/hazmat/primitives/symmetric-encryption.rst index 977a897b..e2cce195 100644 --- a/docs/hazmat/primitives/symmetric-encryption.rst +++ b/docs/hazmat/primitives/symmetric-encryption.rst @@ -330,7 +330,7 @@ Modes .. danger:: When using this mode you MUST not use the decrypted data until - :meth:`cryptography.hazmat.primitives.interfaces.CipherContext.finalize` + :meth:`~cryptography.hazmat.primitives.interfaces.CipherContext.finalize` has been called. GCM provides NO guarantees of ciphertext integrity until decryption is complete. -- cgit v1.2.3 From d6f14daf49036a434bc0a6b190457694f8703be1 Mon Sep 17 00:00:00 2001 From: Julian Krause Date: Thu, 5 Dec 2013 11:06:27 -0800 Subject: Improve documentation. --- docs/hazmat/primitives/constant-time.rst | 18 ++++++++++++++---- 1 file changed, 14 insertions(+), 4 deletions(-) (limited to 'docs/hazmat/primitives') diff --git a/docs/hazmat/primitives/constant-time.rst b/docs/hazmat/primitives/constant-time.rst index 2e8e26d7..4e00e9b9 100644 --- a/docs/hazmat/primitives/constant-time.rst +++ b/docs/hazmat/primitives/constant-time.rst @@ -6,11 +6,17 @@ Constant time functions .. currentmodule:: cryptography.hazmat.primitives.constant_time In order for cryptographic operations to not leak information through timing -side channels, constant time operations need to be made available. +side channels, constant time operations need to be used. + +One should use these functions whenever you are comparing a secret to +something received. This includes things like HMAC signatures as described by +a `timing attack on KeyCzar`_. + .. function:: bytes_eq(a, b) - Compare ``a`` and ``b`` to one another in constant time. + Compare ``a`` and ``b`` to one another in constant time if they are of the + same length. .. doctest:: @@ -20,5 +26,9 @@ side channels, constant time operations need to be made available. >>> constant_time.bytes_eq(b"foo", b"bar") False - :param a: ``bytes``. - :param b: ``bytes``. + :param a bytes: The left-hand side. + :param b bytes: The right-hand side. + :returns boolean: True if ``a`` has the same bytes as ``b``. + + +.. _`timing attack on KeyCzar`: http://rdist.root.org/2009/05/28/timing-attack-in-google-keyczar-library/ -- cgit v1.2.3 From a07925a154e2b28db30499c5a3cf40fedc451d10 Mon Sep 17 00:00:00 2001 From: Paul Kehrer Date: Fri, 6 Dec 2013 11:49:42 -0600 Subject: update docs to explain tag requirements and valueerror --- docs/hazmat/primitives/symmetric-encryption.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) (limited to 'docs/hazmat/primitives') diff --git a/docs/hazmat/primitives/symmetric-encryption.rst b/docs/hazmat/primitives/symmetric-encryption.rst index 8d8d558b..46148689 100644 --- a/docs/hazmat/primitives/symmetric-encryption.rst +++ b/docs/hazmat/primitives/symmetric-encryption.rst @@ -349,8 +349,8 @@ Modes Do not reuse an ``initialization_vector`` with a given ``key``. - :param bytes tag: The tag bytes to verify during decryption. Must be provided - for decryption, but is ignored when encrypting. + :param bytes tag: The tag bytes to verify during decryption. When encrypting + this must be None. .. doctest:: -- cgit v1.2.3 From 848f770c4ab33e0d1cd98c78480ae32d5c5f134e Mon Sep 17 00:00:00 2001 From: Julian Krause Date: Thu, 12 Dec 2013 20:55:39 -0800 Subject: Update documentation again to make it clearer what this is for. Moved to using Coda Hale's post. --- docs/hazmat/primitives/constant-time.rst | 16 ++++++++++------ 1 file changed, 10 insertions(+), 6 deletions(-) (limited to 'docs/hazmat/primitives') diff --git a/docs/hazmat/primitives/constant-time.rst b/docs/hazmat/primitives/constant-time.rst index 4e00e9b9..4df73b3c 100644 --- a/docs/hazmat/primitives/constant-time.rst +++ b/docs/hazmat/primitives/constant-time.rst @@ -5,12 +5,16 @@ Constant time functions .. currentmodule:: cryptography.hazmat.primitives.constant_time -In order for cryptographic operations to not leak information through timing -side channels, constant time operations need to be used. +This module contains functions for operating with secret data in a way that +does not leak information about that data through how long it takes to perform +the operation. These functions should be used whenever operating on secret data +along with data that is user supplied. -One should use these functions whenever you are comparing a secret to -something received. This includes things like HMAC signatures as described by -a `timing attack on KeyCzar`_. +An example would be comparing a HMAC signature received from a client to the +one generated by the server code for authentication purposes. + +For more information about this sort of issue, see `Coda Hale's blog post`_ +about the timing attacks on KeyCzar and Java's ``MessageDigest.isEquals()``. .. function:: bytes_eq(a, b) @@ -31,4 +35,4 @@ a `timing attack on KeyCzar`_. :returns boolean: True if ``a`` has the same bytes as ``b``. -.. _`timing attack on KeyCzar`: http://rdist.root.org/2009/05/28/timing-attack-in-google-keyczar-library/ +.. _`Coda Hale's blog post`: http://codahale.com/a-lesson-in-timing-attacks/ -- cgit v1.2.3 From f56444df44faf8c030a82a042a198b6fa77caa72 Mon Sep 17 00:00:00 2001 From: Alex Gaynor Date: Fri, 13 Dec 2013 15:19:22 -0800 Subject: Always show where a baackend comes form in the docs --- docs/hazmat/primitives/symmetric-encryption.rst | 11 ++++++----- 1 file changed, 6 insertions(+), 5 deletions(-) (limited to 'docs/hazmat/primitives') diff --git a/docs/hazmat/primitives/symmetric-encryption.rst b/docs/hazmat/primitives/symmetric-encryption.rst index 2f390175..ef6f0871 100644 --- a/docs/hazmat/primitives/symmetric-encryption.rst +++ b/docs/hazmat/primitives/symmetric-encryption.rst @@ -12,9 +12,6 @@ Symmetric Encryption key = binascii.unhexlify(b"0" * 32) iv = binascii.unhexlify(b"0" * 32) - from cryptography.hazmat.bindings import default_backend - backend = default_backend() - Symmetric encryption is a way to encrypt (hide the plaintext value) material where the sender and receiver both use the same key. Note that symmetric @@ -37,6 +34,8 @@ an "encrypt-then-MAC" formulation as `described by Colin Percival`_. .. doctest:: >>> from cryptography.hazmat.primitives.ciphers import Cipher, algorithms, modes + >>> from cryptography.hazmat.bindings import default_backend + >>> backend = default_backend() >>> cipher = Cipher(algorithms.AES(key), modes.CBC(iv), backend=backend) >>> encryptor = cipher.encryptor() >>> ct = encryptor.update(b"a secret message") + encryptor.finalize() @@ -230,8 +229,9 @@ Weak Ciphers .. doctest:: >>> from cryptography.hazmat.primitives.ciphers import Cipher, algorithms, modes + >>> from cryptography.hazmat.bindings import default_backend >>> algorithm = algorithms.ARC4(key) - >>> cipher = Cipher(algorithm, mode=None, backend=backend) + >>> cipher = Cipher(algorithm, mode=None, backend=default_backend()) >>> encryptor = cipher.encryptor() >>> ct = encryptor.update(b"a secret message") >>> decryptor = cipher.decryptor() @@ -356,7 +356,8 @@ Modes .. doctest:: >>> from cryptography.hazmat.primitives.ciphers import Cipher, algorithms, modes - >>> cipher = Cipher(algorithms.AES(key), modes.GCM(iv), backend) + >>> from cryptography.hazmat.bindings import default_backend + >>> cipher = Cipher(algorithms.AES(key), modes.GCM(iv), backend=default_backend()) >>> encryptor = cipher.encryptor() >>> encryptor.authenticate_additional_data(b"authenticated but not encrypted payload") >>> ct = encryptor.update(b"a secret message") + encryptor.finalize() -- cgit v1.2.3 From 989061d070bdee122b07633e9a19e737fa816256 Mon Sep 17 00:00:00 2001 From: Alex Gaynor Date: Fri, 13 Dec 2013 20:22:14 -0800 Subject: Prefer executable code examples --- docs/hazmat/primitives/symmetric-encryption.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) (limited to 'docs/hazmat/primitives') diff --git a/docs/hazmat/primitives/symmetric-encryption.rst b/docs/hazmat/primitives/symmetric-encryption.rst index ef6f0871..f3def845 100644 --- a/docs/hazmat/primitives/symmetric-encryption.rst +++ b/docs/hazmat/primitives/symmetric-encryption.rst @@ -266,7 +266,7 @@ Modes A good construction looks like: - .. code-block:: pycon + .. doctest:: >>> import os >>> iv = os.urandom(16) @@ -274,7 +274,7 @@ Modes While the following is bad and will leak information: - .. code-block:: pycon + .. doctest:: >>> iv = "a" * 16 >>> mode = CBC(iv) -- cgit v1.2.3 From f8796b15a279db82cdefcd00bebfef4cdef8fee8 Mon Sep 17 00:00:00 2001 From: Alex Gaynor Date: Fri, 13 Dec 2013 20:28:55 -0800 Subject: Renamed bindings to backends --- docs/hazmat/primitives/cryptographic-hashes.rst | 4 ++-- docs/hazmat/primitives/hmac.rst | 4 ++-- docs/hazmat/primitives/symmetric-encryption.rst | 8 ++++---- 3 files changed, 8 insertions(+), 8 deletions(-) (limited to 'docs/hazmat/primitives') diff --git a/docs/hazmat/primitives/cryptographic-hashes.rst b/docs/hazmat/primitives/cryptographic-hashes.rst index 312d7e69..90ca198a 100644 --- a/docs/hazmat/primitives/cryptographic-hashes.rst +++ b/docs/hazmat/primitives/cryptographic-hashes.rst @@ -20,7 +20,7 @@ Message Digests .. doctest:: - >>> from cryptography.hazmat.bindings import default_backend + >>> from cryptography.hazmat.backends import default_backend >>> from cryptography.hazmat.primitives import hashes >>> digest = hashes.Hash(hashes.SHA256(), backend=default_backend()) >>> digest.update(b"abc") @@ -39,7 +39,7 @@ Message Digests provider such as those described in :ref:`below `. :param backend: A - :class:`~cryptography.hazmat.bindings.interfaces.HashBackend` + :class:`~cryptography.hazmat.backends.interfaces.HashBackend` provider. .. method:: update(data) diff --git a/docs/hazmat/primitives/hmac.rst b/docs/hazmat/primitives/hmac.rst index db5e98d3..0c0d0220 100644 --- a/docs/hazmat/primitives/hmac.rst +++ b/docs/hazmat/primitives/hmac.rst @@ -27,7 +27,7 @@ message. .. doctest:: - >>> from cryptography.hazmat.bindings import default_backend + >>> from cryptography.hazmat.backends import default_backend >>> from cryptography.hazmat.primitives import hashes, hmac >>> h = hmac.HMAC(key, hashes.SHA256(), backend=default_backend()) >>> h.update(b"message to hash") @@ -41,7 +41,7 @@ message. provider such as those described in :ref:`Cryptographic Hashes `. :param backend: A - :class:`~cryptography.hazmat.bindings.interfaces.HMACBackend` + :class:`~cryptography.hazmat.backends.interfaces.HMACBackend` provider. .. method:: update(msg) diff --git a/docs/hazmat/primitives/symmetric-encryption.rst b/docs/hazmat/primitives/symmetric-encryption.rst index ef6f0871..9fccf552 100644 --- a/docs/hazmat/primitives/symmetric-encryption.rst +++ b/docs/hazmat/primitives/symmetric-encryption.rst @@ -34,7 +34,7 @@ an "encrypt-then-MAC" formulation as `described by Colin Percival`_. .. doctest:: >>> from cryptography.hazmat.primitives.ciphers import Cipher, algorithms, modes - >>> from cryptography.hazmat.bindings import default_backend + >>> from cryptography.hazmat.backends import default_backend >>> backend = default_backend() >>> cipher = Cipher(algorithms.AES(key), modes.CBC(iv), backend=backend) >>> encryptor = cipher.encryptor() @@ -51,7 +51,7 @@ an "encrypt-then-MAC" formulation as `described by Colin Percival`_. provider such as those described :ref:`below `. :param backend: A - :class:`~cryptography.hazmat.bindings.interfaces.CipherBackend` + :class:`~cryptography.hazmat.backends.interfaces.CipherBackend` provider. .. method:: encryptor() @@ -229,7 +229,7 @@ Weak Ciphers .. doctest:: >>> from cryptography.hazmat.primitives.ciphers import Cipher, algorithms, modes - >>> from cryptography.hazmat.bindings import default_backend + >>> from cryptography.hazmat.backends import default_backend >>> algorithm = algorithms.ARC4(key) >>> cipher = Cipher(algorithm, mode=None, backend=default_backend()) >>> encryptor = cipher.encryptor() @@ -356,7 +356,7 @@ Modes .. doctest:: >>> from cryptography.hazmat.primitives.ciphers import Cipher, algorithms, modes - >>> from cryptography.hazmat.bindings import default_backend + >>> from cryptography.hazmat.backends import default_backend >>> cipher = Cipher(algorithms.AES(key), modes.GCM(iv), backend=default_backend()) >>> encryptor = cipher.encryptor() >>> encryptor.authenticate_additional_data(b"authenticated but not encrypted payload") -- cgit v1.2.3 From d83c5909c9de44dd523f057edffbdb33a9ae89e6 Mon Sep 17 00:00:00 2001 From: Alex Gaynor Date: Fri, 13 Dec 2013 20:43:54 -0800 Subject: Need to include the imports --- docs/hazmat/primitives/symmetric-encryption.rst | 2 ++ 1 file changed, 2 insertions(+) (limited to 'docs/hazmat/primitives') diff --git a/docs/hazmat/primitives/symmetric-encryption.rst b/docs/hazmat/primitives/symmetric-encryption.rst index f3def845..55b2dcd4 100644 --- a/docs/hazmat/primitives/symmetric-encryption.rst +++ b/docs/hazmat/primitives/symmetric-encryption.rst @@ -269,6 +269,7 @@ Modes .. doctest:: >>> import os + >>> from cryptography.hazmat.primitives.ciphers.modes import CBC >>> iv = os.urandom(16) >>> mode = CBC(iv) @@ -276,6 +277,7 @@ Modes .. doctest:: + >>> from cryptography.hazmat.primitives.ciphers.modes import CBC >>> iv = "a" * 16 >>> mode = CBC(iv) -- cgit v1.2.3 From 383a04cf47cef37ec94dcc56f52c0e6a18013dcb Mon Sep 17 00:00:00 2001 From: Julian Krause Date: Fri, 13 Dec 2013 23:47:17 -0800 Subject: Remove plural. --- docs/hazmat/primitives/constant-time.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'docs/hazmat/primitives') diff --git a/docs/hazmat/primitives/constant-time.rst b/docs/hazmat/primitives/constant-time.rst index 4df73b3c..632e7c68 100644 --- a/docs/hazmat/primitives/constant-time.rst +++ b/docs/hazmat/primitives/constant-time.rst @@ -14,7 +14,7 @@ An example would be comparing a HMAC signature received from a client to the one generated by the server code for authentication purposes. For more information about this sort of issue, see `Coda Hale's blog post`_ -about the timing attacks on KeyCzar and Java's ``MessageDigest.isEquals()``. +about the timing attacks on KeyCzar and Java's ``MessageDigest.isEqual()``. .. function:: bytes_eq(a, b) -- cgit v1.2.3