From 668d4803571876c1cf803b33495ddcf4433a4d83 Mon Sep 17 00:00:00 2001 From: David Reid Date: Tue, 17 Dec 2013 11:53:43 -0800 Subject: BlockCipherAlgorithm because we should document block_size and ARC4 shouldn't need block_size = 1. --- docs/hazmat/primitives/interfaces.rst | 11 +++++++++++ 1 file changed, 11 insertions(+) (limited to 'docs/hazmat/primitives') diff --git a/docs/hazmat/primitives/interfaces.rst b/docs/hazmat/primitives/interfaces.rst index 11cff51a..361b723e 100644 --- a/docs/hazmat/primitives/interfaces.rst +++ b/docs/hazmat/primitives/interfaces.rst @@ -36,6 +36,17 @@ Symmetric Ciphers The number of bits in the key being used. +.. class:: BlockCipherAlgorithm + + A block cipher algorithm. + + .. attribute:: block_size + + :type: int + + The number of bits in a block. + + Cipher Modes ------------ -- cgit v1.2.3 From 2288e30119e2af3e2b448345cf6a9e61f8d06aa0 Mon Sep 17 00:00:00 2001 From: Julian Krause Date: Tue, 17 Dec 2013 21:26:23 -0800 Subject: Add verify function to hmac and hashes. --- docs/hazmat/primitives/cryptographic-hashes.rst | 7 +++++++ docs/hazmat/primitives/hmac.rst | 7 +++++++ 2 files changed, 14 insertions(+) (limited to 'docs/hazmat/primitives') diff --git a/docs/hazmat/primitives/cryptographic-hashes.rst b/docs/hazmat/primitives/cryptographic-hashes.rst index 90ca198a..02c7b5e1 100644 --- a/docs/hazmat/primitives/cryptographic-hashes.rst +++ b/docs/hazmat/primitives/cryptographic-hashes.rst @@ -67,6 +67,13 @@ Message Digests :return bytes: The message digest as bytes. + .. method:: verify(sig) + + Finalize the current context and securely compare digest to sig. + + :raises cryptography.exceptions.AlreadyFinalized: See :meth:`finalize` + :raises cryptography.exceptions.InvalidSignature: If sig does not match digest + .. _cryptographic-hash-algorithms: diff --git a/docs/hazmat/primitives/hmac.rst b/docs/hazmat/primitives/hmac.rst index 0c0d0220..b556bd6a 100644 --- a/docs/hazmat/primitives/hmac.rst +++ b/docs/hazmat/primitives/hmac.rst @@ -69,3 +69,10 @@ message. :return bytes: The message digest as bytes. :raises cryptography.exceptions.AlreadyFinalized: + + .. method:: verify(sig) + + Finalize the current context and securely compare digest to sig. + + :raises cryptography.exceptions.AlreadyFinalized: See :meth:`finalize` + :raises cryptography.exceptions.InvalidSignature: If sig does not match digest -- cgit v1.2.3 From 1b1327cfe537b9e7bdc271239d1025c2479239c3 Mon Sep 17 00:00:00 2001 From: Alex Stapleton Date: Sat, 21 Dec 2013 15:16:57 +0000 Subject: Raise UnsupportedAlgorithm when initing Hash() Instead of just an AssertionError. --- docs/hazmat/primitives/cryptographic-hashes.rst | 3 +++ 1 file changed, 3 insertions(+) (limited to 'docs/hazmat/primitives') diff --git a/docs/hazmat/primitives/cryptographic-hashes.rst b/docs/hazmat/primitives/cryptographic-hashes.rst index 90ca198a..38347378 100644 --- a/docs/hazmat/primitives/cryptographic-hashes.rst +++ b/docs/hazmat/primitives/cryptographic-hashes.rst @@ -28,6 +28,9 @@ Message Digests >>> digest.finalize() 'l\xa1=R\xcap\xc8\x83\xe0\xf0\xbb\x10\x1eBZ\x89\xe8bM\xe5\x1d\xb2\xd29%\x93\xafj\x84\x11\x80\x90' + If the backend doesn't support the requested ``algorithm`` an + :class:`~cryptography.exceptions.UnsupportedAlgorithm` will be raised. + Keep in mind that attacks against cryptographic hashes only get stronger with time, and that often algorithms that were once thought to be strong, become broken. Because of this it's important to include a plan for -- cgit v1.2.3 From 447d64fb69e19c0059e3ba18ef3b1317a716a7c4 Mon Sep 17 00:00:00 2001 From: Alex Stapleton Date: Sat, 21 Dec 2013 21:26:55 +0000 Subject: Raise UnsupportedAlgorithm when initing HMACs --- docs/hazmat/primitives/hmac.rst | 2 ++ 1 file changed, 2 insertions(+) (limited to 'docs/hazmat/primitives') diff --git a/docs/hazmat/primitives/hmac.rst b/docs/hazmat/primitives/hmac.rst index 0c0d0220..0547b7d2 100644 --- a/docs/hazmat/primitives/hmac.rst +++ b/docs/hazmat/primitives/hmac.rst @@ -34,6 +34,8 @@ message. >>> h.finalize() '#F\xdaI\x8b"e\xc4\xf1\xbb\x9a\x8fc\xff\xf5\xdex.\xbc\xcd/+\x8a\x86\x1d\x84\'\xc3\xa6\x1d\xd8J' + If the backend doesn't support the requested ``algorithm`` an + :class:`~cryptography.exceptions.UnsupportedAlgorithm` will be raised. :param key: Secret key as ``bytes``. :param algorithm: A -- cgit v1.2.3 From ca73504e62e2c55a7235f94c78cb8ee4d3718590 Mon Sep 17 00:00:00 2001 From: Paul Kehrer Date: Sat, 21 Dec 2013 17:31:48 -0600 Subject: add note regarding not truncating tags --- docs/hazmat/primitives/symmetric-encryption.rst | 5 +++++ 1 file changed, 5 insertions(+) (limited to 'docs/hazmat/primitives') diff --git a/docs/hazmat/primitives/symmetric-encryption.rst b/docs/hazmat/primitives/symmetric-encryption.rst index f4d0457a..8ed64c7c 100644 --- a/docs/hazmat/primitives/symmetric-encryption.rst +++ b/docs/hazmat/primitives/symmetric-encryption.rst @@ -352,6 +352,11 @@ Modes Do not reuse an ``initialization_vector`` with a given ``key``. + .. note:: + + Do not truncate the GCM authentication tag unless absolutely necessary. + If you must truncate the minimum allowable length is 4 bytes. + :param bytes tag: The tag bytes to verify during decryption. When encrypting this must be None. -- cgit v1.2.3 From a7fbf07a3e96133b40df05ac5be159bbf6f1fc91 Mon Sep 17 00:00:00 2001 From: Paul Kehrer Date: Sat, 21 Dec 2013 18:12:25 -0600 Subject: doc updates --- docs/hazmat/primitives/symmetric-encryption.rst | 7 +++++-- 1 file changed, 5 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 8ed64c7c..85d7d5b1 100644 --- a/docs/hazmat/primitives/symmetric-encryption.rst +++ b/docs/hazmat/primitives/symmetric-encryption.rst @@ -354,8 +354,10 @@ Modes .. note:: - Do not truncate the GCM authentication tag unless absolutely necessary. - If you must truncate the minimum allowable length is 4 bytes. + `NIST SP-800-38D`_ recommends that GCM tags be 128, 120, 122, 104, or + 96-bits in length. Tags are shortened by truncating bytes. Longer tags + provide better security margins. If you must shorten the tag the minimum + allowed length is 4 bytes (32 bits). :param bytes tag: The tag bytes to verify during decryption. When encrypting this must be None. @@ -395,3 +397,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 +.. _`NIST SP-800-38D`: http://csrc.nist.gov/publications/nistpubs/800-38D/SP-800-38D.pdf -- cgit v1.2.3 From fc73e2d04315e21011869fbd925df9e7a99d21ae Mon Sep 17 00:00:00 2001 From: Paul Kehrer Date: Sat, 21 Dec 2013 18:41:38 -0600 Subject: prose updates for GCM tag --- docs/hazmat/primitives/symmetric-encryption.rst | 10 ++++++---- 1 file changed, 6 insertions(+), 4 deletions(-) (limited to 'docs/hazmat/primitives') diff --git a/docs/hazmat/primitives/symmetric-encryption.rst b/docs/hazmat/primitives/symmetric-encryption.rst index 85d7d5b1..f009bb78 100644 --- a/docs/hazmat/primitives/symmetric-encryption.rst +++ b/docs/hazmat/primitives/symmetric-encryption.rst @@ -354,10 +354,12 @@ Modes .. note:: - `NIST SP-800-38D`_ recommends that GCM tags be 128, 120, 122, 104, or - 96-bits in length. Tags are shortened by truncating bytes. Longer tags - provide better security margins. If you must shorten the tag the minimum - allowed length is 4 bytes (32 bits). + Cryptography will emit a 128-bit tag when finalizing encryption. + You can shorten a tag by truncating it to the desired length, but this + is **not recommended** as it lowers the security margins of the + authentication (`NIST SP-800-38D`_ recommends 96-bit or greater). + If you must shorten the tag the minimum allowed length is 4 bytes + (32 bit). :param bytes tag: The tag bytes to verify during decryption. When encrypting this must be None. -- cgit v1.2.3 From 048d6cb43a0757f3b4cca385e788d30173ebcb17 Mon Sep 17 00:00:00 2001 From: Paul Kehrer Date: Sat, 21 Dec 2013 18:53:19 -0600 Subject: a few more doc changes to gcm tag info --- docs/hazmat/primitives/symmetric-encryption.rst | 5 +++-- 1 file changed, 3 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 f009bb78..6e3c1024 100644 --- a/docs/hazmat/primitives/symmetric-encryption.rst +++ b/docs/hazmat/primitives/symmetric-encryption.rst @@ -357,9 +357,10 @@ Modes Cryptography will emit a 128-bit tag when finalizing encryption. You can shorten a tag by truncating it to the desired length, but this is **not recommended** as it lowers the security margins of the - authentication (`NIST SP-800-38D`_ recommends 96-bit or greater). + authentication (`NIST SP-800-38D`_ recommends 96-bits or greater). If you must shorten the tag the minimum allowed length is 4 bytes - (32 bit). + (32-bits). Applications **must** verify the tag is the expected length + to guarantee the expected security margin. :param bytes tag: The tag bytes to verify during decryption. When encrypting this must be None. -- cgit v1.2.3 From 35cb3659bcf97eea22ce1ad14b7fc3d0913d2be2 Mon Sep 17 00:00:00 2001 From: Alex Stapleton Date: Sat, 21 Dec 2013 16:29:45 +0000 Subject: UnsupportedAlgorithm error messages for Ciphers --- 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 f4d0457a..dfadd895 100644 --- a/docs/hazmat/primitives/symmetric-encryption.rst +++ b/docs/hazmat/primitives/symmetric-encryption.rst @@ -61,7 +61,7 @@ an "encrypt-then-MAC" formulation as `described by Colin Percival`_. provider. If the backend doesn't support the requested combination of ``cipher`` - and ``mode`` an :class:`cryptography.exceptions.UnsupportedAlgorithm` + and ``mode`` an :class:`~cryptography.exceptions.UnsupportedAlgorithm` will be raised. .. method:: decryptor() -- cgit v1.2.3 From c91fe6a21fbae3107de7b2e53b7343cd67ac8c6d Mon Sep 17 00:00:00 2001 From: Julian Krause Date: Wed, 25 Dec 2013 11:00:49 -0800 Subject: Clean up documentation and naming. --- docs/hazmat/primitives/cryptographic-hashes.rst | 7 ++++--- docs/hazmat/primitives/hmac.rst | 7 ++++--- 2 files changed, 8 insertions(+), 6 deletions(-) (limited to 'docs/hazmat/primitives') diff --git a/docs/hazmat/primitives/cryptographic-hashes.rst b/docs/hazmat/primitives/cryptographic-hashes.rst index 02c7b5e1..f6a3f7a1 100644 --- a/docs/hazmat/primitives/cryptographic-hashes.rst +++ b/docs/hazmat/primitives/cryptographic-hashes.rst @@ -67,12 +67,13 @@ Message Digests :return bytes: The message digest as bytes. - .. method:: verify(sig) + .. method:: verify(digest) - Finalize the current context and securely compare digest to sig. + Finalize the current context and securely compare that digest to ``digest``. + :param bytes digest: Received hash digest :raises cryptography.exceptions.AlreadyFinalized: See :meth:`finalize` - :raises cryptography.exceptions.InvalidSignature: If sig does not match digest + :raises cryptography.exceptions.InvalidSignature: If hash digest does not match digest .. _cryptographic-hash-algorithms: diff --git a/docs/hazmat/primitives/hmac.rst b/docs/hazmat/primitives/hmac.rst index b556bd6a..0c19f20c 100644 --- a/docs/hazmat/primitives/hmac.rst +++ b/docs/hazmat/primitives/hmac.rst @@ -70,9 +70,10 @@ message. :return bytes: The message digest as bytes. :raises cryptography.exceptions.AlreadyFinalized: - .. method:: verify(sig) + .. method:: verify(signature) - Finalize the current context and securely compare digest to sig. + Finalize the current context and securely compare digest to ``signature``. + :param bytes signature: The bytes of the HMAC signature recieved. :raises cryptography.exceptions.AlreadyFinalized: See :meth:`finalize` - :raises cryptography.exceptions.InvalidSignature: If sig does not match digest + :raises cryptography.exceptions.InvalidSignature: If signature does not match digest -- cgit v1.2.3 From b808f8cc91e302d4120eefa80c946a7cdcf9a155 Mon Sep 17 00:00:00 2001 From: Julian Krause Date: Thu, 26 Dec 2013 21:47:39 -0800 Subject: Remove verify from Hash. --- docs/hazmat/primitives/cryptographic-hashes.rst | 8 -------- 1 file changed, 8 deletions(-) (limited to 'docs/hazmat/primitives') diff --git a/docs/hazmat/primitives/cryptographic-hashes.rst b/docs/hazmat/primitives/cryptographic-hashes.rst index f00dd3f5..38347378 100644 --- a/docs/hazmat/primitives/cryptographic-hashes.rst +++ b/docs/hazmat/primitives/cryptographic-hashes.rst @@ -70,14 +70,6 @@ Message Digests :return bytes: The message digest as bytes. - .. method:: verify(digest) - - Finalize the current context and securely compare that digest to ``digest``. - - :param bytes digest: Received hash digest - :raises cryptography.exceptions.AlreadyFinalized: See :meth:`finalize` - :raises cryptography.exceptions.InvalidSignature: If hash digest does not match digest - .. _cryptographic-hash-algorithms: -- cgit v1.2.3