Merge branch 'master' into validate-iv

Conflicts:
	cryptography/hazmat/primitives/ciphers/modes.py

5 files changed, 55 insertions, 30 deletions

diff --git a/docs/architecture.rst b/docs/architecture.rst
deleted file mode 100644
index bacde1bb..00000000
--- a/docs/architecture.rst
+++ /dev/null
@@ -1,13 +0,0 @@
-Architecture
-============
-
-``cryptography`` has three different layers:
-
-* ``cryptography``: This package contains higher level recipes, for example
-  "encrypt and then MAC". This is implemented on top of
-  ``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.backends``.
-* ``cryptography.hazmat.backends``: This package contains bindings to low level
-  cryptographic libraries. Our initial target is OpenSSL.
diff --git a/docs/hazmat/backends/openssl.rst b/docs/hazmat/backends/openssl.rst
index 99b327d9..404573a3 100644
--- a/docs/hazmat/backends/openssl.rst
+++ b/docs/hazmat/backends/openssl.rst
@@ -3,23 +3,11 @@
 OpenSSL Backend
 ===============
 
-These are `CFFI`_ bindings to the `OpenSSL`_ C library.
+The `OpenSSL`_ C library.
 
 .. data:: cryptography.hazmat.backends.openssl.backend
 
-    This is the exposed API for the OpenSSL bindings. It has two public
-    attributes:
-
-    .. attribute:: ffi
-
-        This is a :class:`cffi.FFI` instance. It can be used to allocate and
-        otherwise manipulate OpenSSL structures.
-
-    .. attribute:: lib
-
-        This is a ``cffi`` library. It can be used to call OpenSSL functions,
-        and access constants.
-
+    This is the exposed API for the OpenSSL backend. It has no public attributes.    
 
 Using your own OpenSSL on Linux
 -------------------------------
@@ -48,5 +36,4 @@ You'll also need to generate your own ``openssl.ld`` file. For example::
 You should replace the version string on the first line as appropriate for your
 build.
 
-.. _`CFFI`: https://cffi.readthedocs.org/
 .. _`OpenSSL`: https://www.openssl.org/
diff --git a/docs/hazmat/bindings/index.rst b/docs/hazmat/bindings/index.rst
new file mode 100644
index 00000000..809eddfc
--- /dev/null
+++ b/docs/hazmat/bindings/index.rst
@@ -0,0 +1,22 @@
+.. hazmat::
+
+Bindings
+========
+
+.. currentmodule:: cryptography.hazmat.bindings
+
+``cryptography`` aims to provide low-level CFFI based bindings to multiple
+native C libraries. These provide no automatic initialisation of the library
+and may not provide complete wrappers for its API.
+
+Using these functions directly is likely to require you to be careful in
+managing memory allocation, locking and other resources.
+
+
+Individual Bindings
+-------------------
+
+.. toctree::
+    :maxdepth: 1
+
+    openssl
diff --git a/docs/hazmat/bindings/openssl.rst b/docs/hazmat/bindings/openssl.rst
new file mode 100644
index 00000000..373fe472
--- /dev/null
+++ b/docs/hazmat/bindings/openssl.rst
@@ -0,0 +1,27 @@
+.. hazmat::
+
+OpenSSL Binding
+===============
+
+.. currentmodule:: cryptography.hazmat.bindings.openssl.binding
+
+These are `CFFI`_ bindings to the `OpenSSL`_ C library.
+
+.. class:: cryptography.hazmat.bindings.openssl.binding.Binding()
+
+    This is the exposed API for the OpenSSL bindings. It has two public
+    attributes:
+
+    .. attribute:: ffi
+
+        This is a :class:`cffi.FFI` instance. It can be used to allocate and
+        otherwise manipulate OpenSSL structures.
+
+    .. attribute:: lib
+
+        This is a ``cffi`` library. It can be used to call OpenSSL functions,
+        and access constants.
+
+
+.. _`CFFI`: https://cffi.readthedocs.org/
+.. _`OpenSSL`: https://www.openssl.org/
diff --git a/docs/index.rst b/docs/index.rst
index 70558bda..5eb3de7d 100644
--- a/docs/index.rst
+++ b/docs/index.rst
@@ -43,7 +43,9 @@ 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.
+"hazardous materials" or "hazmat" layer. These live in the
+``cryptography.hazmat`` package, and their documentation will always contain an
+admonition at the top.
 
 We recommend using the recipes layer whenever possible, and falling back to the
 hazmat layer only when necessary.
@@ -54,7 +56,6 @@ The recipes layer
 .. toctree::
     :maxdepth: 2
 
-    architecture
     exceptions
     glossary
 
@@ -66,6 +67,7 @@ The hazardous materials layer
 
     hazmat/primitives/index
     hazmat/backends/index
+    hazmat/bindings/index
 
 The ``cryptography`` open source project
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~