diff options
| -rw-r--r-- | Doc/library/hmac.rst | 45 | ||||
| -rw-r--r-- | Modules/operator.c | 14 |
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) |