Merge branch 'master' into validate-iv

Conflicts:
	tests/hazmat/backends/test_openssl.py
	tests/hazmat/primitives/test_block.py

3 files changed, 52 insertions, 14 deletions

diff --git a/docs/hazmat/backends/index.rst b/docs/hazmat/backends/index.rst
index a89cf0d5..06951281 100644
--- a/docs/hazmat/backends/index.rst
+++ b/docs/hazmat/backends/index.rst
@@ -1,17 +1,10 @@
 .. hazmat::
 
-Bindings
+Backends
 ========
 
-.. toctree::
-    :maxdepth: 1
-
-    openssl
-    interfaces
-
-
-Getting a Backend Provider
-~~~~~~~~~~~~~~~~~~~~~~~~~~
+Getting a Backend
+-----------------
 
 .. currentmodule:: cryptography.hazmat.backends
 
@@ -19,8 +12,7 @@ Getting a Backend Provider
 the widest number of supported cryptographic algorithms as well as supporting
 platform specific implementations.
 
-You can get the default backend by calling
-:func:`~default_backend`.
+You can get the default backend by calling :func:`~default_backend`.
 
 The default backend will change over time as we implement new backends and
 the libraries we use in those backends changes.
@@ -32,3 +24,11 @@ the libraries we use in those backends changes.
         :class:`~interfaces.CipherBackend`, :class:`~interfaces.HashBackend`, and
         :class:`~interfaces.HMACBackend`.
 
+Individual Backends
+-------------------
+
+.. toctree::
+    :maxdepth: 1
+
+    openssl
+    interfaces
diff --git a/docs/hazmat/backends/interfaces.rst b/docs/hazmat/backends/interfaces.rst
index b524943d..5b6cd64d 100644
--- a/docs/hazmat/backends/interfaces.rst
+++ b/docs/hazmat/backends/interfaces.rst
@@ -126,6 +126,17 @@ A specific ``backend`` may provide one or more of these interfaces.
     A backend with methods for using cryptographic hash functions as message
     authentication codes.
 
+    .. method:: hmac_supported(algorithm)
+
+        Check if the specified ``algorithm`` is supported by this backend.
+
+        :param algorithm: An instance of a
+            :class:`~cryptography.hazmat.primitives.interfaces.HashAlgorithm`
+            provider.
+
+        :returns: ``True`` if the specified ``algorithm`` is supported for HMAC
+            by this backend, otherwise ``False``.
+
     .. method:: create_hmac_ctx(algorithm)
 
         Create a
diff --git a/docs/hazmat/backends/openssl.rst b/docs/hazmat/backends/openssl.rst
index 12fbff04..99b327d9 100644
--- a/docs/hazmat/backends/openssl.rst
+++ b/docs/hazmat/backends/openssl.rst
@@ -1,7 +1,7 @@
 .. hazmat::
 
-OpenSSL
-=======
+OpenSSL Backend
+===============
 
 These are `CFFI`_ bindings to the `OpenSSL`_ C library.
 
@@ -21,5 +21,32 @@ These are `CFFI`_ bindings to the `OpenSSL`_ C library.
         and access constants.
 
 
+Using your own OpenSSL on Linux
+-------------------------------
+
+Python links to OpenSSL for its own purposes and this can sometimes cause
+problems when you wish to use a different version of OpenSSL with cryptography.
+If you want to use cryptography with your own build of OpenSSL you will need to
+make sure that the build is configured correctly so that your version of
+OpenSSL doesn't conflict with Python's.
+
+The options you need to add allow the linker to identify every symbol correctly
+even when multiple versions of the library are linked into the same program. If
+you are using your distribution's source packages these will probably be
+patched in for you already, otherwise you'll need to use options something like
+this when configuring OpenSSL::
+
+    ./config -Wl,--version-script=openssl.ld -Wl,-Bsymbolic-functions -fPIC shared
+
+You'll also need to generate your own ``openssl.ld`` file. For example::
+
+    OPENSSL_1.0.1F_CUSTOM {
+        global:
+            *;
+    };
+
+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/