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