diff -r 91f161335689 Doc/library/hmac.rst --- a/Doc/library/hmac.rst Wed Apr 11 16:49:40 2012 -0400 +++ b/Doc/library/hmac.rst Thu Apr 12 17:21:33 2012 -0400 @@ -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 attacker-supplied + digest during a verification routine, it is recommended to use the + :func:`hmac.time_independent_equals` 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 attacker-supplied + digest during a verification routine, it is recommended to use the + :func:`hmac.time_independent_equals` 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:: time_independent_equals(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, which may be + a security risk. The inputs must be either :class:`str` or :class:`bytes` + instances. + + .. note:: + + While the :func:`hmac.time_independent_equals` 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 -r 91f161335689 Lib/hmac.py --- a/Lib/hmac.py Wed Apr 11 16:49:40 2012 -0400 +++ b/Lib/hmac.py Thu Apr 12 17:21:33 2012 -0400 @@ -13,6 +13,25 @@ digest_size = None +def time_independent_equals(a, b): + 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 -r 91f161335689 Lib/test/test_hmac.py --- a/Lib/test/test_hmac.py Wed Apr 11 16:49:40 2012 -0400 +++ b/Lib/test/test_hmac.py Thu Apr 12 17:21:33 2012 -0400 @@ -302,12 +302,48 @@ self.assertEqual(h1.hexdigest(), h2.hexdigest(), "Hexdigest of copy doesn't match original hexdigest.") +class TimeIndependentTestCase(unittest.TestCase): + + def test_equality(self): + # Testing input type exception handling + a, b = 100, 200 + self.assertRaises(TypeError, hmac.time_independent_equals, a, b) + a, b = 100, "foobar" + self.assertRaises(TypeError, hmac.time_independent_equals, a, b) + a, b = "foobar", b"foobar" + self.assertRaises(TypeError, hmac.time_independent_equals, a, b) + + # Testing str/bytes of different lengths + a, b = "foobar", "foo" + self.assertFalse(hmac.time_independent_equals(a, b)) + a, b = b"foobar", b"foo" + self.assertFalse(hmac.time_independent_equals(a, b)) + a, b = b"\xde\xad\xbe\xef", b"\xde\xad" + self.assertFalse(hmac.time_independent_equals(a, b)) + + # Testing str/bytes of same lengths, different values + a, b = "foobar", "foobaz" + self.assertFalse(hmac.time_independent_equals(a, b)) + a, b = b"foobar", b"foobaz" + self.assertFalse(hmac.time_independent_equals(a, b)) + a, b = b"\xde\xad\xbe\xef", b"\xab\xad\x1d\xea" + self.assertFalse(hmac.time_independent_equals(a, b)) + + # Testing str/bytes of same lengths, same values + a, b = "foobar", "foobar" + self.assertTrue(hmac.time_independent_equals(a, b)) + a, b = b"foobar", b"foobar" + self.assertTrue(hmac.time_independent_equals(a, b)) + a, b = b"\xde\xad\xbe\xef", b"\xde\xad\xbe\xef" + self.assertTrue(hmac.time_independent_equals(a, b)) + def test_main(): support.run_unittest( TestVectorsTestCase, ConstructorTestCase, SanityTestCase, - CopyTestCase + CopyTestCase, + TimeIndependentTestCase ) if __name__ == "__main__": diff -r 91f161335689 Misc/ACKS --- a/Misc/ACKS Wed Apr 11 16:49:40 2012 -0400 +++ b/Misc/ACKS Thu Apr 12 17:21:33 2012 -0400 @@ -745,6 +745,7 @@ John O'Connor Kevin O'Connor Tim O'Malley +Jon Oberheide Pascal Oberndoerfer Jeffrey Ollie Adam Olsen