Update documentation again to make it clearer what this is for. Moved to using Coda Hale's post.

1 files changed, 10 insertions, 6 deletions

diff --git a/docs/hazmat/primitives/constant-time.rst b/docs/hazmat/primitives/constant-time.rst
index 4e00e9b9..4df73b3c 100644
--- a/docs/hazmat/primitives/constant-time.rst
+++ b/docs/hazmat/primitives/constant-time.rst
@@ -5,12 +5,16 @@ 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 used.
+This module contains functions for operating with secret data in a way that
+does not leak information about that data through how long it takes to perform
+the operation. These functions should be used whenever operating on secret data
+along with data that is user supplied.
 
-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`_.
+An example would be comparing a HMAC signature received from a client to the
+one generated by the server code for authentication purposes.
+
+For more information about this sort of issue, see `Coda Hale's blog post`_
+about the timing attacks on KeyCzar and Java's ``MessageDigest.isEquals()``.
 
 
 .. function:: bytes_eq(a, b)
@@ -31,4 +35,4 @@ a `timing attack on KeyCzar`_.
     :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/
+.. _`Coda Hale's blog post`: http://codahale.com/a-lesson-in-timing-attacks/