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') 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/exceptions.rst | 5 +++ docs/hazmat/primitives/symmetric-encryption.rst | 48 +++++++++++++++++++++++++ 2 files changed, 53 insertions(+) (limited to 'docs') diff --git a/docs/exceptions.rst b/docs/exceptions.rst index c6f5a7cc..7ec3cd27 100644 --- a/docs/exceptions.rst +++ b/docs/exceptions.rst @@ -7,6 +7,11 @@ Exceptions This is raised when a context is used after being finalized. +.. class:: NotFinalized + + This is raised when the AEAD tag property is accessed on a context + before it is finalized. + .. class:: UnsupportedAlgorithm 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') 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') 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 ce9c611feb4db781fcab5b7bbc68b936816d6a73 Mon Sep 17 00:00:00 2001 From: Paul Kehrer Date: Fri, 22 Nov 2013 14:10:59 -0600 Subject: enforce AEAD add_data before update --- docs/exceptions.rst | 9 ++++++++- 1 file changed, 8 insertions(+), 1 deletion(-) (limited to 'docs') diff --git a/docs/exceptions.rst b/docs/exceptions.rst index 7ec3cd27..087066b8 100644 --- a/docs/exceptions.rst +++ b/docs/exceptions.rst @@ -7,12 +7,19 @@ Exceptions This is raised when a context is used after being finalized. -.. class:: NotFinalized + +.. class:: NotYetFinalized This is raised when the AEAD tag property is accessed on a context before it is finalized. +.. class:: AlreadyUpdated + + This is raised when additional data is added to a context after update + has already been called. + + .. class:: UnsupportedAlgorithm This is raised when a backend doesn't support the requested algorithm (or -- 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') 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') 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') 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') 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') 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') 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') 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') 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') 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') 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') 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') 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') 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/conf.py | 1 + docs/hazmat/primitives/constant-time.rst | 18 ++++++++++++++---- 2 files changed, 15 insertions(+), 4 deletions(-) (limited to 'docs') diff --git a/docs/conf.py b/docs/conf.py index 77050e72..c6479ef3 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -257,6 +257,7 @@ texinfo_documents = [ # How to display URL addresses: 'footnote', 'no', or 'inline'. #texinfo_show_urls = 'footnote' +linkcheck_ignore = [r'http://rdist.root.org/'] # Example configuration for intersphinx: refer to the Python standard library. intersphinx_mapping = {'http://docs.python.org/': None} 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/bindings/interfaces.rst | 4 ++++ docs/hazmat/primitives/symmetric-encryption.rst | 4 ++-- 2 files changed, 6 insertions(+), 2 deletions(-) (limited to 'docs') diff --git a/docs/hazmat/bindings/interfaces.rst b/docs/hazmat/bindings/interfaces.rst index c55d86dc..711c82c2 100644 --- a/docs/hazmat/bindings/interfaces.rst +++ b/docs/hazmat/bindings/interfaces.rst @@ -69,6 +69,8 @@ A specific ``backend`` may provide one or more of these interfaces. :returns: :class:`~cryptography.hazmat.primitives.interfaces.CipherContext` + :raises ValueError: When tag is not None in an AEAD mode + .. method:: create_symmetric_decryption_ctx(cipher, mode) @@ -86,6 +88,8 @@ A specific ``backend`` may provide one or more of these interfaces. :returns: :class:`~cryptography.hazmat.primitives.interfaces.CipherContext` + :raises ValueError: When tag is None in an AEAD mode + .. class:: HashBackend 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 953ebf8ab4b14c96ce921caea6a619dbf69dfa77 Mon Sep 17 00:00:00 2001 From: Alex Gaynor Date: Sun, 8 Dec 2013 10:28:30 -0800 Subject: Improved the docs -- more glossary entries, more advice for writing docs --- docs/contributing.rst | 3 +++ docs/glossary.rst | 11 +++++++++++ 2 files changed, 14 insertions(+) (limited to 'docs') diff --git a/docs/contributing.rst b/docs/contributing.rst index 97f31e0b..4647818a 100644 --- a/docs/contributing.rst +++ b/docs/contributing.rst @@ -141,6 +141,9 @@ should begin with the "Hazardous Materials" warning: .. hazmat:: +When referring to a hypothetical individual (such as "a person receiving an +encrypted message") use gender neutral pronouns (they/them/their). + Development Environment ----------------------- diff --git a/docs/glossary.rst b/docs/glossary.rst index b6f2d06f..63e0a6ce 100644 --- a/docs/glossary.rst +++ b/docs/glossary.rst @@ -28,3 +28,14 @@ Glossary asymmetric cryptography Cryptographic operations where encryption and decryption use different keys. There are separate encryption and decryption keys. + + authentication + The process of verifying that a message was created by a specific + individual (or program). Like encryption, authentication can be either + symmetric or asymmetric. Authentication is necessary for effective + encryption. + + Ciphertext indistinguishability + This is a property of encryption systems whereby two encrypted messages + aren't distinguishable without knowing the encryption key. This is + considered a basic, necessary property for a working encryption system. -- cgit v1.2.3 From ae9dc8b4c1ca40d3d38859cf06c411bc83e1665a Mon Sep 17 00:00:00 2001 From: Alex Gaynor Date: Thu, 12 Dec 2013 10:13:32 -0800 Subject: Use the HTTPS verion of the link to cffi --- docs/hazmat/bindings/openssl.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'docs') diff --git a/docs/hazmat/bindings/openssl.rst b/docs/hazmat/bindings/openssl.rst index 194eeb92..d6bfa672 100644 --- a/docs/hazmat/bindings/openssl.rst +++ b/docs/hazmat/bindings/openssl.rst @@ -21,5 +21,5 @@ These are `CFFI`_ bindings to the `OpenSSL`_ C library. and access constants. -.. _`CFFI`: http://cffi.readthedocs.org/ +.. _`CFFI`: https://cffi.readthedocs.org/ .. _`OpenSSL`: https://www.openssl.org/ -- cgit v1.2.3 From 5246e2db3100160b948a632e810010e1b23a9e91 Mon Sep 17 00:00:00 2001 From: Alex Gaynor Date: Thu, 12 Dec 2013 12:23:18 -0800 Subject: Fixed headers in docs --- docs/contributing.rst | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) (limited to 'docs') diff --git a/docs/contributing.rst b/docs/contributing.rst index 4647818a..934bb45a 100644 --- a/docs/contributing.rst +++ b/docs/contributing.rst @@ -48,7 +48,7 @@ Additionally, every Python code file must contain from __future__ import absolute_import, division, print_function C bindings ----------- +~~~~~~~~~~ When binding C code with ``cffi`` we have our own style guide, it's pretty simple. @@ -161,7 +161,7 @@ dependencies, install ``cryptography`` in ``editable`` mode. For example: You are now ready to run the tests and build the documentation. Running Tests -------------- +~~~~~~~~~~~~~ ``cryptography`` unit tests are found in the ``tests/`` directory and are designed to be run using `pytest`_. `pytest`_ will discover the tests @@ -195,7 +195,7 @@ You may not have all the required Python versions installed, in which case you will see one or more ``InterpreterNotFound`` errors. Building Documentation ----------------------- +~~~~~~~~~~~~~~~~~~~~~~ ``cryptography`` documentation is stored in the ``docs/`` directory. It is written in `reStructured Text`_ and rendered using `Sphinx`_. -- cgit v1.2.3 From e21b0b25bdda1eaa5a29aa585dd858bd21ff1016 Mon Sep 17 00:00:00 2001 From: Alex Gaynor Date: Thu, 12 Dec 2013 12:39:05 -0800 Subject: Several policy reccomendations for API design --- docs/contributing.rst | 34 ++++++++++++++++++++++++++++++++++ 1 file changed, 34 insertions(+) (limited to 'docs') diff --git a/docs/contributing.rst b/docs/contributing.rst index 934bb45a..09833ed3 100644 --- a/docs/contributing.rst +++ b/docs/contributing.rst @@ -47,6 +47,40 @@ Additionally, every Python code file must contain from __future__ import absolute_import, division, print_function +API Considerations +~~~~~~~~~~~~~~~~~~ + +Most projects' APIs are designed with a philosophy of "make easy things easy, +and make hard things possible". One of the perils of writing cryptographic code +is that code that is secure looks just like code that isn't, and produces +results that are also difficult to distinguish. As a result ``cryptography`` +has, as a design philosophy: "make it hard to do insecure things". Here are a +few strategies for API design which should be both followed, and should inspire +other API choices: + +If it is incorrect to ignore the result of a method, it should raise an +exception, and not return a boolean ``True``/``False`` flag. For example, a +method to verify a signature should raise ``InvalidSignature``, and not return +whether the signature was valid. + +.. code-block:: python + + # This is bad. + def verify(sig): + # ... + return is_valid + + # Good! + def verify(sig): + # ... + if not is_valid: + raise InvalidSignature + +APIs at the :doc:`/hazmat/primitives/index` layer should always take an +explicit backend, APIs at the recipes layer should automatically use the +:func:`~cryptography.hazmat.bindings.default_backend`, but optionally allow +specifiying a different backend. + C bindings ~~~~~~~~~~ -- cgit v1.2.3 From 2a5b4a8aafcfa3122c366c4415294eca9ad8de7f Mon Sep 17 00:00:00 2001 From: Alex Gaynor Date: Thu, 12 Dec 2013 17:53:08 -0800 Subject: Fixed a mis-spelled word --- docs/contributing.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'docs') diff --git a/docs/contributing.rst b/docs/contributing.rst index 09833ed3..100f13f5 100644 --- a/docs/contributing.rst +++ b/docs/contributing.rst @@ -79,7 +79,7 @@ whether the signature was valid. APIs at the :doc:`/hazmat/primitives/index` layer should always take an explicit backend, APIs at the recipes layer should automatically use the :func:`~cryptography.hazmat.bindings.default_backend`, but optionally allow -specifiying a different backend. +specifying a different backend. C bindings ~~~~~~~~~~ -- cgit v1.2.3 From 31df5357132319de7c9eb7154dd72ddebcbc4afa Mon Sep 17 00:00:00 2001 From: Alex Gaynor Date: Thu, 12 Dec 2013 18:03:26 -0800 Subject: More info in teh index --- docs/index.rst | 19 ++++++++++++++++--- 1 file changed, 16 insertions(+), 3 deletions(-) (limited to 'docs') diff --git a/docs/index.rst b/docs/index.rst index 1b88e24e..a1a650a8 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -6,13 +6,26 @@ Welcome to ``cryptography`` ``cryptography`` is very young, and very incomplete. ``cryptography`` is a Python library which exposes cryptographic recipes and -primitives. +primitives. We hope it'll be your one-stop-shop for all your cryptographic +needs in Python. + +Installing +---------- + +We don't yet have a release on PyPI, for now you can install ``cryptography`` +directly from Github: + +.. code-block:: console + + $ pip install git+https://github.com/pyca/cryptography Why a new crypto library for Python? ------------------------------------ -We wanted to address a few issues with existing cryptography libraries in -Python: +If you've done cryptographic work in Python before, you've probably seen some +other libraries in Python, such as *M2Crypto*, *PyCrypto*, or *PyOpenSSL*. In +building ``cryptography`` we wanted to address a few issues we observed in the +existing libraries: * Lack of PyPy and Python 3 support. * Lack of maintenance. -- 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/conf.py | 2 -- docs/hazmat/primitives/constant-time.rst | 16 ++++++++++------ 2 files changed, 10 insertions(+), 8 deletions(-) (limited to 'docs') diff --git a/docs/conf.py b/docs/conf.py index c6479ef3..5092e4d3 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -257,7 +257,5 @@ texinfo_documents = [ # How to display URL addresses: 'footnote', 'no', or 'inline'. #texinfo_show_urls = 'footnote' -linkcheck_ignore = [r'http://rdist.root.org/'] - # Example configuration for intersphinx: refer to the Python standard library. intersphinx_mapping = {'http://docs.python.org/': None} 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 73cf187d7796c1c913a1607beae944a1d8cf233e Mon Sep 17 00:00:00 2001 From: Alex Gaynor Date: Fri, 13 Dec 2013 15:15:08 -0800 Subject: This warning doesn't add much value anymore --- docs/index.rst | 4 ---- 1 file changed, 4 deletions(-) (limited to 'docs') diff --git a/docs/index.rst b/docs/index.rst index a1a650a8..2263c32f 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -1,10 +1,6 @@ Welcome to ``cryptography`` =========================== -.. warning:: - - ``cryptography`` is very young, and very incomplete. - ``cryptography`` is a Python library which exposes cryptographic recipes and primitives. We hope it'll be your one-stop-shop for all your cryptographic needs in Python. -- 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') 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 f3f0018fb956dcc075798bd3d2eb49916471f23c Mon Sep 17 00:00:00 2001 From: Alex Gaynor Date: Fri, 13 Dec 2013 19:22:33 -0800 Subject: Document the need for test coverage --- docs/contributing.rst | 1 + 1 file changed, 1 insertion(+) (limited to 'docs') diff --git a/docs/contributing.rst b/docs/contributing.rst index 100f13f5..a8010a9a 100644 --- a/docs/contributing.rst +++ b/docs/contributing.rst @@ -28,6 +28,7 @@ devastating, ``cryptography`` has a strict code review policy: * If somehow the tests get into a failing state on ``master`` (such as by a backwards incompatible release of a dependency) no pull requests may be merged until this is rectified. +* All merged patches must have 100% test coverage. The purpose of these policies is to minimize the chances we merge a change which jeopardizes our users' security. -- 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') 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