4 files changed, 43 insertions, 3 deletions
diff --git a/docs/conf.py b/docs/conf.py
index 77050e72..5092e4d3 100644
--- a/docs/conf.py
+++ b/docs/conf.py
@@ -257,6 +257,5 @@ texinfo_documents = [
 # How to display URL addresses: 'footnote', 'no', or 'inline'.
 #texinfo_show_urls = 'footnote'
 
-
 # Example configuration for intersphinx: refer to the Python standard library.
 intersphinx_mapping = {'http://docs.python.org/': None}
diff --git a/docs/hazmat/primitives/constant-time.rst b/docs/hazmat/primitives/constant-time.rst
new file mode 100644
index 00000000..632e7c68
--- /dev/null
+++ b/docs/hazmat/primitives/constant-time.rst
@@ -0,0 +1,38 @@
+.. hazmat::
+
+Constant time functions
+=======================
+
+.. currentmodule:: cryptography.hazmat.primitives.constant_time
+
+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.
+
+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.isEqual()``.
+
+
+.. function:: bytes_eq(a, b)
+
+    Compare ``a`` and ``b`` to one another in constant time if they are of the
+    same length.
+
+    .. doctest::
+
+        >>> from cryptography.hazmat.primitives import constant_time
+        >>> constant_time.bytes_eq(b"foo", b"foo")
+        True
+        >>> 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``.
+
+
+.. _`Coda Hale's blog post`: http://codahale.com/a-lesson-in-timing-attacks/
diff --git a/docs/hazmat/primitives/index.rst b/docs/hazmat/primitives/index.rst
index 614c414a..b115fdbc 100644
--- a/docs/hazmat/primitives/index.rst
+++ b/docs/hazmat/primitives/index.rst
@@ -10,4 +10,5 @@ Primitives
     hmac
     symmetric-encryption
     padding
+    constant-time
     interfaces
diff --git a/docs/hazmat/primitives/symmetric-encryption.rst b/docs/hazmat/primitives/symmetric-encryption.rst
index 9fccf552..f4d0457a 100644
--- a/docs/hazmat/primitives/symmetric-encryption.rst
+++ b/docs/hazmat/primitives/symmetric-encryption.rst
@@ -266,16 +266,18 @@ Modes
 
     A good construction looks like:
 
-    .. code-block:: pycon
+    .. doctest::
 
         >>> import os
+        >>> from cryptography.hazmat.primitives.ciphers.modes import CBC
         >>> iv = os.urandom(16)
         >>> mode = CBC(iv)
 
     While the following is bad and will leak information:
 
-    .. code-block:: pycon
+    .. doctest::
 
+        >>> from cryptography.hazmat.primitives.ciphers.modes import CBC
         >>> iv = "a" * 16
         >>> mode = CBC(iv)