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') 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') 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') 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') 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') 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') 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') 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') 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') 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') 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') 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') 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') 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