Merge branch 'master' into no-more-generator

Conflicts:
	tests/hazmat/primitives/utils.py

12 files changed, 92 insertions, 32 deletions

diff --git a/docs/architecture.rst b/docs/architecture.rst
index 5ca2c252..bacde1bb 100644
--- a/docs/architecture.rst
+++ b/docs/architecture.rst
@@ -8,6 +8,6 @@ Architecture
   ``cryptography.hazmat.primitives``.
 * ``cryptography.hazmat.primitives``: This packages contains low level
   algorithms, things like ``AES`` or ``SHA1``. This is implemented on top of
-  ``cryptography.hazmat.bindings``.
-* ``cryptography.hazmat.bindings``: This package contains bindings to low level
-  cryptographic libraries. Our initial target will be OpenSSL.
+  ``cryptography.hazmat.backends``.
+* ``cryptography.hazmat.backends``: This package contains bindings to low level
+  cryptographic libraries. Our initial target is OpenSSL.
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/contributing.rst b/docs/contributing.rst
index 100f13f5..cb9c7283 100644
--- a/docs/contributing.rst
+++ b/docs/contributing.rst
@@ -28,6 +28,7 @@ devastating, ``cryptography`` has a strict code review policy:
 * If somehow the tests get into a failing state on ``master`` (such as by a
   backwards incompatible release of a dependency) no pull requests may be
   merged until this is rectified.
+* All merged patches must have 100% test coverage.
 
 The purpose of these policies is to minimize the chances we merge a change
 which jeopardizes our users' security.
@@ -78,7 +79,7 @@ whether the signature was valid.
 
 APIs at the :doc:`/hazmat/primitives/index` layer should always take an
 explicit backend, APIs at the recipes layer should automatically use the
-:func:`~cryptography.hazmat.bindings.default_backend`, but optionally allow
+:func:`~cryptography.hazmat.backends.default_backend`, but optionally allow
 specifying a different backend.
 
 C bindings
diff --git a/docs/hazmat/bindings/index.rst b/docs/hazmat/backends/index.rst
index 746f4596..a89cf0d5 100644
--- a/docs/hazmat/bindings/index.rst
+++ b/docs/hazmat/backends/index.rst
@@ -13,7 +13,7 @@ Bindings
 Getting a Backend Provider
 ~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-.. currentmodule:: cryptography.hazmat.bindings
+.. currentmodule:: cryptography.hazmat.backends
 
 ``cryptography`` aims to support multiple backends to ensure it can provide
 the widest number of supported cryptographic algorithms as well as supporting
diff --git a/docs/hazmat/bindings/interfaces.rst b/docs/hazmat/backends/interfaces.rst
index 711c82c2..b524943d 100644
--- a/docs/hazmat/bindings/interfaces.rst
+++ b/docs/hazmat/backends/interfaces.rst
@@ -3,7 +3,7 @@
 Backend Interfaces
 ==================
 
-.. currentmodule:: cryptography.hazmat.bindings.interfaces
+.. currentmodule:: cryptography.hazmat.backends.interfaces
 
 
 Backend implementations may provide a number of interfaces to support operations
diff --git a/docs/hazmat/bindings/openssl.rst b/docs/hazmat/backends/openssl.rst
index d6bfa672..12fbff04 100644
--- a/docs/hazmat/bindings/openssl.rst
+++ b/docs/hazmat/backends/openssl.rst
@@ -5,7 +5,7 @@ OpenSSL
 
 These are `CFFI`_ bindings to the `OpenSSL`_ C library.
 
-.. data:: cryptography.hazmat.bindings.openssl.backend
+.. data:: cryptography.hazmat.backends.openssl.backend
 
     This is the exposed API for the OpenSSL bindings. It has two public
     attributes:
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/cryptographic-hashes.rst b/docs/hazmat/primitives/cryptographic-hashes.rst
index 312d7e69..90ca198a 100644
--- a/docs/hazmat/primitives/cryptographic-hashes.rst
+++ b/docs/hazmat/primitives/cryptographic-hashes.rst
@@ -20,7 +20,7 @@ Message Digests
 
     .. doctest::
 
-        >>> from cryptography.hazmat.bindings import default_backend
+        >>> from cryptography.hazmat.backends import default_backend
         >>> from cryptography.hazmat.primitives import hashes
         >>> digest = hashes.Hash(hashes.SHA256(), backend=default_backend())
         >>> digest.update(b"abc")
@@ -39,7 +39,7 @@ Message Digests
         provider such as those described in
         :ref:`below <cryptographic-hash-algorithms>`.
     :param backend: A
-        :class:`~cryptography.hazmat.bindings.interfaces.HashBackend`
+        :class:`~cryptography.hazmat.backends.interfaces.HashBackend`
         provider.
 
     .. method:: update(data)
diff --git a/docs/hazmat/primitives/hmac.rst b/docs/hazmat/primitives/hmac.rst
index db5e98d3..0c0d0220 100644
--- a/docs/hazmat/primitives/hmac.rst
+++ b/docs/hazmat/primitives/hmac.rst
@@ -27,7 +27,7 @@ message.
 
     .. doctest::
 
-        >>> from cryptography.hazmat.bindings import default_backend
+        >>> from cryptography.hazmat.backends import default_backend
         >>> from cryptography.hazmat.primitives import hashes, hmac
         >>> h = hmac.HMAC(key, hashes.SHA256(), backend=default_backend())
         >>> h.update(b"message to hash")
@@ -41,7 +41,7 @@ message.
         provider such as those described in
         :ref:`Cryptographic Hashes <cryptographic-hash-algorithms>`.
     :param backend: A
-        :class:`~cryptography.hazmat.bindings.interfaces.HMACBackend`
+        :class:`~cryptography.hazmat.backends.interfaces.HMACBackend`
         provider.
 
     .. method:: update(msg)
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 2f390175..f4d0457a 100644
--- a/docs/hazmat/primitives/symmetric-encryption.rst
+++ b/docs/hazmat/primitives/symmetric-encryption.rst
@@ -12,9 +12,6 @@ Symmetric Encryption
     key = binascii.unhexlify(b"0" * 32)
     iv = binascii.unhexlify(b"0" * 32)
 
-    from cryptography.hazmat.bindings import default_backend
-    backend = default_backend()
-
 
 Symmetric encryption is a way to encrypt (hide the plaintext value) material
 where the sender and receiver both use the same key. Note that symmetric
@@ -37,6 +34,8 @@ an "encrypt-then-MAC" formulation as `described by Colin Percival`_.
     .. doctest::
 
         >>> from cryptography.hazmat.primitives.ciphers import Cipher, algorithms, modes
+        >>> from cryptography.hazmat.backends import default_backend
+        >>> backend = default_backend()
         >>> cipher = Cipher(algorithms.AES(key), modes.CBC(iv), backend=backend)
         >>> encryptor = cipher.encryptor()
         >>> ct = encryptor.update(b"a secret message") + encryptor.finalize()
@@ -52,7 +51,7 @@ an "encrypt-then-MAC" formulation as `described by Colin Percival`_.
         provider such as those described
         :ref:`below <symmetric-encryption-modes>`.
     :param backend: A
-        :class:`~cryptography.hazmat.bindings.interfaces.CipherBackend`
+        :class:`~cryptography.hazmat.backends.interfaces.CipherBackend`
         provider.
 
     .. method:: encryptor()
@@ -230,8 +229,9 @@ Weak Ciphers
     .. doctest::
 
         >>> from cryptography.hazmat.primitives.ciphers import Cipher, algorithms, modes
+        >>> from cryptography.hazmat.backends import default_backend
         >>> algorithm = algorithms.ARC4(key)
-        >>> cipher = Cipher(algorithm, mode=None, backend=backend)
+        >>> cipher = Cipher(algorithm, mode=None, backend=default_backend())
         >>> encryptor = cipher.encryptor()
         >>> ct = encryptor.update(b"a secret message")
         >>> decryptor = cipher.decryptor()
@@ -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)
 
@@ -356,7 +358,8 @@ Modes
     .. doctest::
 
         >>> from cryptography.hazmat.primitives.ciphers import Cipher, algorithms, modes
-        >>> cipher = Cipher(algorithms.AES(key), modes.GCM(iv), backend)
+        >>> from cryptography.hazmat.backends import default_backend
+        >>> cipher = Cipher(algorithms.AES(key), modes.GCM(iv), backend=default_backend())
         >>> encryptor = cipher.encryptor()
         >>> encryptor.authenticate_additional_data(b"authenticated but not encrypted payload")
         >>> ct = encryptor.update(b"a secret message") + encryptor.finalize()
diff --git a/docs/index.rst b/docs/index.rst
index a1a650a8..381063df 100644
--- a/docs/index.rst
+++ b/docs/index.rst
@@ -1,10 +1,6 @@
 Welcome to ``cryptography``
 ===========================
 
-.. warning::
-
-    ``cryptography`` is very young, and very incomplete.
-
 ``cryptography`` is a Python library which exposes cryptographic recipes and
 primitives. We hope it'll be your one-stop-shop for all your cryptographic
 needs in Python.
@@ -36,9 +32,24 @@ existing libraries:
 * Poor introspectability, and thus poor testability.
 * Extremely error prone APIs, and bad defaults.
 
+Layout
+------
+
+``cryptography`` is broadly divided into two levels. One with safe
+cryptographic recipes, "cryptography for humans" if you will. These are safe
+and easy to use and don't require developers to make many decisions.
+
+The other level is low-level cryptographic primitives. These are often
+dangerous and can be used incorrectly. They require making decisions and having
+an in-depth knowledge of the cryptographic concepts at work. Because of the
+potential danger in working at this level, this is referred to as the
+"hazardous materials" or "hazmat" layer.
 
-Contents
---------
+We recommend using the recipes layer whenever possible, and falling back to the
+hazmat layer only when necessary.
+
+The recipes layer
+~~~~~~~~~~~~~~~~~
 
 .. toctree::
     :maxdepth: 2
@@ -46,15 +57,22 @@ Contents
     architecture
     exceptions
     glossary
-    contributing
-    security
-    community
 
-Hazardous Materials
--------------------
+The hazardous materials layer
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 .. toctree::
     :maxdepth: 2
 
     hazmat/primitives/index
-    hazmat/bindings/index
+    hazmat/backends/index
+
+The ``cryptography`` open source project
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+.. toctree::
+    :maxdepth: 2
+
+    contributing
+    security
+    community