Improve hmac.compare_digest() docstring and documentation, courtesy of Larry H.

2 files changed, 30 insertions, 29 deletions

diff --git a/Doc/library/hmac.rst b/Doc/library/hmac.rst
index e9491fd..3fa0bd6 100644
--- a/Doc/library/hmac.rst
+++ b/Doc/library/hmac.rst
@@ -71,35 +71,36 @@ This module also provides the following helper function:
 
 .. function:: compare_digest(a, b)
 
-   Returns the equivalent of ``a == b``, but avoids content based
-   short circuiting behaviour to reduce the vulnerability to timing
-   analysis. 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.
-
-   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).
+   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.
+
+   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::
 
-      While this function reduces the likelihood of leaking the contents of
-      the expected digest via a timing attack, it still may leak some timing
+      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.
+      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 bb3752e..8ad5406 100644
--- a/Modules/operator.c
+++ b/Modules/operator.c
@@ -211,14 +211,14 @@ _tscmp(const unsigned char *a, const unsigned char *b,
 PyDoc_STRVAR(compare_digest__doc__,
 "compare_digest(a, b) -> bool\n"
 "\n"
-"Return the equivalent of 'a == b', but avoid any short circuiting to\n"
-"counterfeit timing analysis of input data. The function should be used to\n"
-"compare cryptographic secrets. a and b must both either support the buffer\n"
-"protocol (e.g. bytes) or be ASCII only str instances at the same time.\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: In case of an error or different lengths the function may disclose\n"
-"some timing information about the types and lengths of a and b.\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");
 
 static PyObject*
 compare_digest(PyObject *self, PyObject *args)