Merge pull request #563 from alex/better-constant-time-docs
More clearly describe the behavior of constant_time.bytes_eq
diff --git a/docs/hazmat/primitives/constant-time.rst b/docs/hazmat/primitives/constant-time.rst
index 632e7c6..c6fcb3a 100644
--- a/docs/hazmat/primitives/constant-time.rst
+++ b/docs/hazmat/primitives/constant-time.rst
@@ -19,8 +19,10 @@
.. function:: bytes_eq(a, b)
- Compare ``a`` and ``b`` to one another in constant time if they are of the
- same length.
+ Compares ``a`` and ``b`` with one another. If ``a`` and ``b`` have
+ different lengths, this returns ``False`` immediately. Otherwise it
+ compares them in a way that takes the same amount of time, regardless of
+ how many characters are the same between the two.
.. doctest::
@@ -30,9 +32,10 @@
>>> constant_time.bytes_eq(b"foo", b"bar")
False
- :param a bytes: The left-hand side.
- :param b bytes: The right-hand side.
- :returns boolean: True if ``a`` has the same bytes as ``b``.
+ :param bytes a: The left-hand side.
+ :param bytes b: The right-hand side.
+ :returns bool: ``True`` if ``a`` has the same bytes as ``b``, otherwise
+ ``False``.
.. _`Coda Hale's blog post`: http://codahale.com/a-lesson-in-timing-attacks/