Issue #15061: Re-implemented hmac.compare_digest() in C

1 files changed, 11 insertions, 5 deletions

diff --git a/Doc/library/hmac.rst b/Doc/library/hmac.rst
index e6ce99b..e9491fd 100644
--- a/Doc/library/hmac.rst
+++ b/Doc/library/hmac.rst
@@ -73,7 +73,10 @@ This module also provides the following helper function:
 
    Returns the equivalent of ``a == b``, but avoids content based
    short circuiting behaviour to reduce the vulnerability to timing
-   analysis. The inputs must be :class:`bytes` instances.
+   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
@@ -87,10 +90,13 @@ This module also provides the following helper function:
    .. note::
 
       While this function reduces the likelihood of leaking the contents of
-      the expected digest via a timing attack, it still uses short circuiting
-      behaviour based on the *length* of the inputs. 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.
+      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