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. --- cryptography/hazmat/primitives/constant_time.py | 53 +++++++++++++++++++++++++ docs/hazmat/primitives/constant-time.rst | 24 +++++++++++ docs/hazmat/primitives/index.rst | 1 + tests/hazmat/primitives/test_constant_time.py | 41 +++++++++++++++++++ 4 files changed, 119 insertions(+) create mode 100644 cryptography/hazmat/primitives/constant_time.py create mode 100644 docs/hazmat/primitives/constant-time.rst create mode 100644 tests/hazmat/primitives/test_constant_time.py diff --git a/cryptography/hazmat/primitives/constant_time.py b/cryptography/hazmat/primitives/constant_time.py new file mode 100644 index 00000000..a8351504 --- /dev/null +++ b/cryptography/hazmat/primitives/constant_time.py @@ -0,0 +1,53 @@ +# Licensed under the Apache License, Version 2.0 (the "License"); +# you may not use this file except in compliance with the License. +# You may obtain a copy of the License at +# +# http://www.apache.org/licenses/LICENSE-2.0 +# +# Unless required by applicable law or agreed to in writing, software +# distributed under the License is distributed on an "AS IS" BASIS, +# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or +# implied. +# See the License for the specific language governing permissions and +# limitations under the License. + +from __future__ import absolute_import, division, print_function + +import cffi + +import six + + +_ffi = cffi.FFI() +_ffi.cdef(""" +bool Cryptography_constant_time_bytes_eq(uint8_t *, size_t, uint8_t *, size_t); +""") +_lib = _ffi.verify(""" +#include + +bool Cryptography_constant_time_bytes_eq(uint8_t *a, size_t len_a, uint8_t *b, + size_t len_b) { + size_t i = 0; + uint8_t mismatch = 0; + if (len_a != len_b) { + return false; + } + for (i = 0; i < len_a; i++) { + mismatch |= a[i] ^ b[i]; + } + + /* Make sure any bits set are copied to the lowest bit */ + mismatch |= mismatch >> 4; + mismatch |= mismatch >> 2; + mismatch |= mismatch >> 1; + /* Now check the low bit to see if it's set */ + return (mismatch & 1) == 0; +} +""") + + +def bytes_eq(a, b): + if isinstance(a, six.text_type) or isinstance(b, six.text_type): + raise TypeError("Unicode-objects must be encoded before comparing") + + return _lib.Cryptography_constant_time_bytes_eq(a, len(a), b, len(b)) == 1 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 diff --git a/tests/hazmat/primitives/test_constant_time.py b/tests/hazmat/primitives/test_constant_time.py new file mode 100644 index 00000000..dd910dee --- /dev/null +++ b/tests/hazmat/primitives/test_constant_time.py @@ -0,0 +1,41 @@ +# Licensed under the Apache License, Version 2.0 (the "License"); +# you may not use this file except in compliance with the License. +# You may obtain a copy of the License at +# +# http://www.apache.org/licenses/LICENSE-2.0 +# +# Unless required by applicable law or agreed to in writing, software +# distributed under the License is distributed on an "AS IS" BASIS, +# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or +# implied. +# See the License for the specific language governing permissions and +# limitations under the License. + +from __future__ import absolute_import, division, print_function + +import pytest + +import six + +from cryptography.hazmat.primitives import constant_time + + +class TestConstantTimeBytesEq(object): + def test_reject_unicode(self): + with pytest.raises(TypeError): + constant_time.bytes_eq(b"foo", six.u("foo")) + + with pytest.raises(TypeError): + constant_time.bytes_eq(six.u("foo"), b"foo") + + with pytest.raises(TypeError): + constant_time.bytes_eq(six.u("foo"), six.u("foo")) + + def test_compares(self): + assert constant_time.bytes_eq(b"foo", b"foo") is True + + assert constant_time.bytes_eq(b"foo", b"bar") is False + + assert constant_time.bytes_eq(b"foobar", b"foo") is False + + assert constant_time.bytes_eq(b"foo", b"foobar") is False -- 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(-) 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 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(-) 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 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(-) 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