Merge heads.
diff --git a/Doc/library/hmac.rst b/Doc/library/hmac.rst
index 2ea3fc6..085c12b 100644
--- a/Doc/library/hmac.rst
+++ b/Doc/library/hmac.rst
@@ -70,19 +70,36 @@
.. 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, 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
+
.. seealso::
Module :mod:`hashlib`
diff --git a/Modules/operator.c b/Modules/operator.c
index 7c7ef8f..8ad5406 100644
--- a/Modules/operator.c
+++ b/Modules/operator.c
@@ -211,15 +211,14 @@
PyDoc_STRVAR(compare_digest__doc__,
"compare_digest(a, b) -> bool\n"
"\n"
-"Return ``a == b``. This function uses an approach designed to prevent\n"
-"timing analysis, making it appropriate for cryptography. *a* and *b*\n"
-"must both be of the same type: either `str` (ASCII only, as e.g.\n"
-"returned by HMAC.hexdigest()), or any type that supports the buffer\n"
-"protocol, (e.g. `bytes`).\n"
+"Return 'a == b'. This function uses an approach designed to prevent\n"
+"timing analysis, making it appropriate for cryptography.\n"
+"a and b must both be of the same type: either str (ASCII only),\n"
+"or any type that supports the buffer protocol (e.g. bytes).\n"
"\n"
-"Note: If *a* and *b* are different lengths, or if an error occurs,\n"
+"Note: If a and b are of different lengths, or if an error occurs,\n"
"a timing attack may be able to infer information about the types\n"
-"and lengths of *a* and *b*, but not their values.\n");
+"and lengths of a and b, but not their values.\n");
static PyObject*
compare_digest(PyObject *self, PyObject *args)