From: Georg Brandl <georg@python.org>
Date: Sun, 24 Jun 2012 14:10:47 +0000 (+0200)
Subject: Merge heads.
X-Git-Tag: v3.3.0b1~61
X-Git-Url: https://granicus.if.org/sourcecode?a=commitdiff_plain;h=3b44d81cf956effe4088839ebf96e1950b92eb2c;p=python

Merge heads.
---

3b44d81cf956effe4088839ebf96e1950b92eb2c
diff --cc Doc/library/hmac.rst
index 3fa0bd66ae,2ea3fc620c..085c12b857
--- a/Doc/library/hmac.rst
+++ b/Doc/library/hmac.rst
@@@ -71,32 -70,16 +70,32 @@@ This module also provides the followin
  
  .. function:: compare_digest(a, b)
  
 -   Return ``a == b``.  This function uses an approach designed to prevent
 -   timing analysis, making it appropriate for cryptography.  *a* and *b*
 +   Return ``a == b``.  This function uses an approach designed to prevent timing
-    analysis by avoiding content based short circuiting behaviour.  The inputs
-    must either both support the buffer protocol (e.g. :class:`bytes` and
-    :class:`bytearray` instances) or be ASCII-only :class:`str` instances as
-    returned by :meth:`hexdigest`.  :class:`bytes` and :class:`str` instances
-    can't be mixed.
++   analysis by avoiding content based short circuiting behaviour, making it
++   appropriate for cryptography.  *a* and *b*
+    must both be of the same type: either :class:`str` (ASCII only, as e.g.
+    returned by :meth:`HMAC.hexdigest`), or any type that supports the
+    :term:`buffer protocol` (e.g. :class:`bytes`).
  
 +   Using a short circuiting comparison (that is, one that terminates as soon as
 +   it finds any difference between the values) to check digests for correctness
 +   can be problematic, as it introduces a potential vulnerability when an
 +   attacker can control both the message to be checked *and* the purported
 +   signature value.  By keeping the plaintext consistent and supplying different
 +   signature values, an attacker may be able to use timing variations to search
 +   the signature space for the expected value in O(n) time rather than the
 +   desired O(2**n).
 +
     .. note::
 -      If *a* and *b* are different lengths, or if an error occurs,
 -      a timing attack may be able to infer information about the types
 -      and lengths of *a* and *b*, but not their values.
 +
 +      While this function reduces the likelihood of leaking the contents of the
 +      expected digest via a timing attack, it still may leak some timing
 +      information when the input values differ in lengths as well as in error
 +      cases like unsupported types or non ASCII strings.  When the inputs have
 +      different length the timing depends solely on the length of ``b``.  It is
 +      assumed that the expected length of the digest is not a secret, as it is
 +      typically published as part of a file format, network protocol or API
 +      definition.
  
     .. versionadded:: 3.3