Login | Register For Free | Help
Search for: (Advanced)

Mailing List Archive: Python: Checkins
cpython: Issue #14532: Add a secure compare() helper to the hmac module, to mitigate
 

Index | Next | Previous | View Flat


python-checkins at python

May 13, 2012, 10:53 AM


Views: 41
Permalink
cpython: Issue #14532: Add a secure compare() helper to the hmac module, to mitigate

http://hg.python.org/cpython/rev/ddcc8ee680d7
changeset: 76906:ddcc8ee680d7
user: Charles-Fran├žois Natali <neologix [at] free>
date: Sun May 13 19:53:07 2012 +0200
summary:
Issue #14532: Add a secure_compare() helper to the hmac module, to mitigate
timing attacks. Patch by Jon Oberheide.

files:
Doc/library/hmac.rst | 32 ++++++++++++++++++++++++++
Lib/hmac.py | 21 +++++++++++++++++
Lib/test/test_hmac.py | 38 ++++++++++++++++++++++++++++++-
Misc/ACKS | 1 +
Misc/NEWS | 3 ++
5 files changed, 94 insertions(+), 1 deletions(-)


diff --git a/Doc/library/hmac.rst b/Doc/library/hmac.rst
--- a/Doc/library/hmac.rst
+++ b/Doc/library/hmac.rst
@@ -38,6 +38,13 @@
given to the constructor. It may contain non-ASCII bytes, including NUL
bytes.

+ .. warning::
+
+ When comparing the output of :meth:`digest` to an externally-supplied
+ digest during a verification routine, it is recommended to use the
+ :func:`hmac.secure_compare` function instead of the ``==`` operator
+ to avoid potential timing attacks.
+

.. method:: HMAC.hexdigest()

@@ -45,6 +52,13 @@
length containing only hexadecimal digits. This may be used to exchange the
value safely in email or other non-binary environments.

+ .. warning::
+
+ When comparing the output of :meth:`hexdigest` to an externally-supplied
+ digest during a verification routine, it is recommended to use the
+ :func:`hmac.secure_compare` function instead of the ``==`` operator
+ to avoid potential timing attacks.
+

.. method:: HMAC.copy()

@@ -52,6 +66,24 @@
compute the digests of strings that share a common initial substring.


+This module also provides the following helper function:
+
+.. function:: secure_compare(a, b)
+
+ Returns the equivalent of ``a == b``, but using a time-independent
+ comparison method. Comparing the full lengths of the inputs *a* and *b*,
+ instead of short-circuiting the comparison upon the first unequal byte,
+ prevents leaking information about the inputs being compared and mitigates
+ potential timing attacks. The inputs must be either :class:`str` or
+ :class:`bytes` instances.
+
+ .. note::
+
+ While the :func:`hmac.secure_compare` function prevents leaking the
+ contents of the inputs via a timing attack, it does leak the length
+ of the inputs. However, this generally is not a security risk.
+
+
.. seealso::

Module :mod:`hashlib`
diff --git a/Lib/hmac.py b/Lib/hmac.py
--- a/Lib/hmac.py
+++ b/Lib/hmac.py
@@ -13,6 +13,27 @@
digest_size = None


+def secure_compare(a, b):
+ """Returns the equivalent of 'a == b', but using a time-independent
+ comparison method to prevent timing attacks."""
+ if not ((isinstance(a, str) and isinstance(b, str)) or
+ (isinstance(a, bytes) and isinstance(b, bytes))):
+ raise TypeError("inputs must be strings or bytes")
+
+ if len(a) != len(b):
+ return False
+
+ result = 0
+ if isinstance(a, bytes):
+ for x, y in zip(a, b):
+ result |= x ^ y
+ else:
+ for x, y in zip(a, b):
+ result |= ord(x) ^ ord(y)
+
+ return result == 0
+
+
class HMAC:
"""RFC 2104 HMAC class. Also complies with RFC 4231.

diff --git a/Lib/test/test_hmac.py b/Lib/test/test_hmac.py
--- a/Lib/test/test_hmac.py
+++ b/Lib/test/test_hmac.py
@@ -302,12 +302,48 @@
self.assertEqual(h1.hexdigest(), h2.hexdigest(),
"Hexdigest of copy doesn't match original hexdigest.")

+class SecureCompareTestCase(unittest.TestCase):
+
+ def test_compare(self):
+ # Testing input type exception handling
+ a, b = 100, 200
+ self.assertRaises(TypeError, hmac.secure_compare, a, b)
+ a, b = 100, "foobar"
+ self.assertRaises(TypeError, hmac.secure_compare, a, b)
+ a, b = "foobar", b"foobar"
+ self.assertRaises(TypeError, hmac.secure_compare, a, b)
+
+ # Testing str/bytes of different lengths
+ a, b = "foobar", "foo"
+ self.assertFalse(hmac.secure_compare(a, b))
+ a, b = b"foobar", b"foo"
+ self.assertFalse(hmac.secure_compare(a, b))
+ a, b = b"\xde\xad\xbe\xef", b"\xde\xad"
+ self.assertFalse(hmac.secure_compare(a, b))
+
+ # Testing str/bytes of same lengths, different values
+ a, b = "foobar", "foobaz"
+ self.assertFalse(hmac.secure_compare(a, b))
+ a, b = b"foobar", b"foobaz"
+ self.assertFalse(hmac.secure_compare(a, b))
+ a, b = b"\xde\xad\xbe\xef", b"\xab\xad\x1d\xea"
+ self.assertFalse(hmac.secure_compare(a, b))
+
+ # Testing str/bytes of same lengths, same values
+ a, b = "foobar", "foobar"
+ self.assertTrue(hmac.secure_compare(a, b))
+ a, b = b"foobar", b"foobar"
+ self.assertTrue(hmac.secure_compare(a, b))
+ a, b = b"\xde\xad\xbe\xef", b"\xde\xad\xbe\xef"
+ self.assertTrue(hmac.secure_compare(a, b))
+
def test_main():
support.run_unittest(
TestVectorsTestCase,
ConstructorTestCase,
SanityTestCase,
- CopyTestCase
+ CopyTestCase,
+ SecureCompareTestCase
)

if __name__ == "__main__":
diff --git a/Misc/ACKS b/Misc/ACKS
--- a/Misc/ACKS
+++ b/Misc/ACKS
@@ -746,6 +746,7 @@
John O'Connor
Kevin O'Connor
Tim O'Malley
+Jon Oberheide
Pascal Oberndoerfer
Jeffrey Ollie
Adam Olsen
diff --git a/Misc/NEWS b/Misc/NEWS
--- a/Misc/NEWS
+++ b/Misc/NEWS
@@ -23,6 +23,9 @@
Library
-------

+- Issue #14532: Add a secure_compare() helper to the hmac module, to mitigate
+ timing attacks. Patch by Jon Oberheide.
+
- Add importlib.util.resolve_name().

- Issue #14366: Support lzma compression in zip files.

--
Repository URL: http://hg.python.org/cpython

Subject User Time
cpython: Issue #14532: Add a secure compare() helper to the hmac module, to mitigate python-checkins at python May 13, 2012, 10:53 AM

  Index | Next | Previous | View Flat
 
 


Interested in having your list archived? Contact Gossamer Threads
 
  Web Applications & Managed Hosting Powered by Gossamer Threads Inc.