Improve documentation.

1 files changed, 14 insertions, 4 deletions

diff --git a/docs/hazmat/primitives/constant-time.rst b/docs/hazmat/primitives/constant-time.rst
index 2e8e26d7..4e00e9b9 100644
--- a/docs/hazmat/primitives/constant-time.rst
+++ b/docs/hazmat/primitives/constant-time.rst
@@ -6,11 +6,17 @@ Constant time functions
 .. currentmodule:: cryptography.hazmat.primitives.constant_time
 
 In order for cryptographic operations to not leak information through timing
-side channels, constant time operations need to be made available.
+side channels, constant time operations need to be used.
+
+One should use these functions whenever you are comparing a secret to
+something received. This includes things like HMAC signatures as described by
+a `timing attack on KeyCzar`_.
+
 
 .. function:: bytes_eq(a, b)
 
-    Compare ``a`` and ``b`` to one another in constant time.
+    Compare ``a`` and ``b`` to one another in constant time if they are of the
+    same length.
 
     .. doctest::
 
@@ -20,5 +26,9 @@ side channels, constant time operations need to be made available.
         >>> constant_time.bytes_eq(b"foo", b"bar")
         False
 
-    :param a: ``bytes``.
-    :param b: ``bytes``.
+    :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``.
+
+
+.. _`timing attack on KeyCzar`: http://rdist.root.org/2009/05/28/timing-attack-in-google-keyczar-library/