1 files changed, 22 insertions, 5 deletions
diff --git a/Doc/library/hmac.rst b/Doc/library/hmac.rst
index a8ca3af..ce93cbc 100644
--- a/Doc/library/hmac.rst
+++ b/Doc/library/hmac.rst
@@ -70,19 +70,36 @@ This module also provides the following helper function:
 
 .. 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
    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`