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

1 files changed, 7 insertions, 7 deletions

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)