Merge branch 'master' into reorder_libs

10 files changed, 201 insertions, 136 deletions

diff --git a/docs/development/test-vectors.rst b/docs/development/test-vectors.rst
index 5f31e304..2682d37e 100644
--- a/docs/development/test-vectors.rst
+++ b/docs/development/test-vectors.rst
@@ -22,6 +22,7 @@ Asymmetric ciphers
 * RSA FIPS 186-2 and PKCS1 v1.5 vulnerability test vectors from `NIST CAVP`_.
 * FIPS 186-2 and FIPS 186-3 DSA test vectors from `NIST CAVP`_.
 * FIPS 186-2 and FIPS 186-3 ECDSA test vectors from `NIST CAVP`_.
+* DH and ECDH test vectors from `NIST CAVP`_.
 * Ed25519 test vectors from the `Ed25519 website_`.
 * OpenSSL PEM RSA serialization vectors from the `OpenSSL example key`_ and
   `GnuTLS key parsing tests`_.
diff --git a/docs/hazmat/backends/interfaces.rst b/docs/hazmat/backends/interfaces.rst
index 86229125..63f84067 100644
--- a/docs/hazmat/backends/interfaces.rst
+++ b/docs/hazmat/backends/interfaces.rst
@@ -148,6 +148,33 @@ A specific ``backend`` may provide one or more of these interfaces.
             :class:`~cryptography.hazmat.primitives.interfaces.HashContext`
 
 
+.. class:: CMACBackend
+
+    .. versionadded:: 0.4
+
+    A backend with methods for using CMAC
+
+    .. method:: cmac_algorithm_supported(algorithm)
+
+        :param algorithm: An instance of a
+            :class:`~cryptography.hazmat.primitives.interfaces.BlockCipherAlgorithm`
+            provider.
+        :return: Returns True if the block cipher is supported for CMAC by this backend
+
+    .. method:: create_cmac_ctx(algorithm)
+
+        Create a
+        :class:`~cryptography.hazmat.primitives.interfaces.CMACContext` that
+        uses the specified ``algorithm`` to calculate a message authentication code.
+
+        :param algorithm: An instance of a
+            :class:`~cryptography.hazmat.primitives.interfaces.BlockCipherAlgorithm`
+            provider.
+
+        :returns:
+            :class:`~cryptography.hazmat.primitives.interfaces.CMACContext`
+
+
 .. class:: PBKDF2HMACBackend
 
     .. versionadded:: 0.2
@@ -364,29 +391,6 @@ A specific ``backend`` may provide one or more of these interfaces.
             any backend specific criteria are not met.
 
 
-.. class:: TraditionalOpenSSLSerializationBackend
-
-    .. versionadded:: 0.3
-
-    A backend with methods for working with OpenSSL's "traditional" PKCS #1
-    style key serialization.
-
-    .. method:: load_openssl_pem_private_key(data, password)
-
-        :param bytes data: PEM data to deserialize.
-
-        :param bytes password: The password to use if this data is encrypted.
-            Should be None if the data is not encrypted.
-
-        :return: A new instance of the appropriate private key or public key
-            that the serialized data contains.
-
-        :raises ValueError: If the data could not be deserialized correctly.
-
-        :raises cryptography.exceptions.UnsupportedAlgorithm: If the data is
-            encrypted with an unsupported algorithm.
-
-
 .. class:: DSABackend
 
     .. versionadded:: 0.4
@@ -524,56 +528,6 @@ A specific ``backend`` may provide one or more of these interfaces.
             any backend specific criteria are not met.
 
 
-
-.. class:: CMACBackend
-
-    .. versionadded:: 0.4
-
-    A backend with methods for using CMAC
-
-    .. method:: cmac_algorithm_supported(algorithm)
-
-        :param algorithm: An instance of a
-            :class:`~cryptography.hazmat.primitives.interfaces.BlockCipherAlgorithm`
-            provider.
-        :return: Returns True if the block cipher is supported for CMAC by this backend
-
-    .. method:: create_cmac_ctx(algorithm)
-
-        Create a
-        :class:`~cryptography.hazmat.primitives.interfaces.CMACContext` that
-        uses the specified ``algorithm`` to calculate a message authentication code.
-
-        :param algorithm: An instance of a
-            :class:`~cryptography.hazmat.primitives.interfaces.BlockCipherAlgorithm`
-            provider.
-
-        :returns:
-            :class:`~cryptography.hazmat.primitives.interfaces.CMACContext`
-
-
-.. class:: PKCS8SerializationBackend
-
-    .. versionadded:: 0.5
-
-    A backend with methods for working with PKCS #8 key serialization.
-
-    .. method:: load_pkcs8_pem_private_key(data, password)
-
-        :param bytes data: PEM data to deserialize.
-
-        :param bytes password: The password to use if this data is encrypted.
-            Should be None if the data is not encrypted.
-
-        :return: A new instance of the appropriate private key or public key
-            that the serialized data contains.
-
-        :raises ValueError: If the data could not be deserialized correctly.
-
-        :raises cryptography.exceptions.UnsupportedAlgorithm: If the data is
-            encrypted with an unsupported algorithm.
-
-
 .. class:: EllipticCurveBackend
 
     .. versionadded:: 0.5
@@ -623,3 +577,48 @@ A specific ``backend`` may provide one or more of these interfaces.
         :returns: An instance of a
             :class:`~cryptography.hazmat.primitives.interfaces.EllipticCurvePublicKey`
             provider.
+
+.. class:: TraditionalOpenSSLSerializationBackend
+
+    .. versionadded:: 0.3
+
+    A backend with methods for working with OpenSSL's "traditional" PKCS #1
+    style key serialization.
+
+    .. method:: load_openssl_pem_private_key(data, password)
+
+        :param bytes data: PEM data to deserialize.
+
+        :param bytes password: The password to use if this data is encrypted.
+            Should be None if the data is not encrypted.
+
+        :return: A new instance of the appropriate private key or public key
+            that the serialized data contains.
+
+        :raises ValueError: If the data could not be deserialized correctly.
+
+        :raises cryptography.exceptions.UnsupportedAlgorithm: If the data is
+            encrypted with an unsupported algorithm.
+
+
+.. class:: PKCS8SerializationBackend
+
+    .. versionadded:: 0.5
+
+    A backend with methods for working with PKCS #8 key serialization.
+
+    .. method:: load_pkcs8_pem_private_key(data, password)
+
+        :param bytes data: PEM data to deserialize.
+
+        :param bytes password: The password to use if this data is encrypted.
+            Should be None if the data is not encrypted.
+
+        :return: A new instance of the appropriate private key or public key
+            that the serialized data contains.
+
+        :raises ValueError: If the data could not be deserialized correctly.
+
+        :raises cryptography.exceptions.UnsupportedAlgorithm: If the data is
+            encrypted with an unsupported algorithm.
+
diff --git a/docs/hazmat/backends/multibackend.rst b/docs/hazmat/backends/multibackend.rst
index 119b13ae..0aae04a7 100644
--- a/docs/hazmat/backends/multibackend.rst
+++ b/docs/hazmat/backends/multibackend.rst
@@ -12,7 +12,24 @@ MultiBackend
     This class allows you to combine multiple backends into a single backend
     that offers the combined features of all of its constituents.
 
-    .. code-block:: pycon
+    .. testsetup::
+
+        from cryptography import utils
+        from cryptography.exceptions import UnsupportedAlgorithm, _Reasons
+        from cryptography.hazmat.backends.interfaces import HashBackend
+        from cryptography.hazmat.backends.openssl.backend import backend as backend2
+
+        @utils.register_interface(HashBackend)
+        class DummyHashBackend(object):
+            def hash_supported(self, algorithm):
+                return False
+
+            def create_hash_ctx(self, algorithm):
+                raise UnsupportedAlgorithm("", _Reasons.UNSUPPORTED_HASH)
+
+        backend1 = DummyHashBackend()
+
+    .. doctest::
 
         >>> from cryptography.hazmat.backends.multibackend import MultiBackend
         >>> from cryptography.hazmat.primitives import hashes
diff --git a/docs/hazmat/primitives/asymmetric/dsa.rst b/docs/hazmat/primitives/asymmetric/dsa.rst
index 55f36b51..e411931b 100644
--- a/docs/hazmat/primitives/asymmetric/dsa.rst
+++ b/docs/hazmat/primitives/asymmetric/dsa.rst
@@ -119,6 +119,16 @@ Numbers
 
         The generator.
 
+    .. method:: parameters(backend)
+
+        :param backend: A
+            :class:`~cryptography.hazmat.backends.interfaces.DSABackend`
+            provider.
+
+        :returns: A new instance of a
+            :class:`~cryptography.hazmat.primitives.interfaces.DSAParameters`
+            provider.
+
 .. class:: DSAPublicNumbers(y, parameter_numbers)
 
     .. versionadded:: 0.5
@@ -138,6 +148,16 @@ Numbers
         The :class:`~cryptography.hazmat.primitives.dsa.DSAParameterNumbers`
         associated with the public key.
 
+    .. method:: public_key(backend)
+
+        :param backend: A
+            :class:`~cryptography.hazmat.backends.interfaces.DSABackend`
+            provider.
+
+        :returns: A new instance of a
+            :class:`~cryptography.hazmat.primitives.interfaces.DSAPublicKey`
+            provider.
+
 .. class:: DSAPrivateNumbers(x, public_numbers)
 
     .. versionadded:: 0.5
@@ -162,6 +182,16 @@ Numbers
         The :class:`~cryptography.hazmat.primitives.dsa.DSAPublicNumbers`
         associated with the private key.
 
+    .. method:: private_key(backend)
+
+        :param backend: A
+            :class:`~cryptography.hazmat.backends.interfaces.DSABackend`
+            provider.
+
+        :returns: A new instance of a
+            :class:`~cryptography.hazmat.primitives.interfaces.DSAPrivateKey`
+            provider.
+
 Deprecated Concrete Classes
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
diff --git a/docs/hazmat/primitives/asymmetric/rsa.rst b/docs/hazmat/primitives/asymmetric/rsa.rst
index 7250066a..a9637523 100644
--- a/docs/hazmat/primitives/asymmetric/rsa.rst
+++ b/docs/hazmat/primitives/asymmetric/rsa.rst
@@ -153,6 +153,15 @@ is unavailable.
 
         The public exponent.
 
+    .. method:: public_key(backend)
+
+        :param backend: A
+            :class:`~cryptography.hazmat.backends.interfaces.RSABackend`
+            provider.
+
+        :returns: A new instance of a
+            :class:`~cryptography.hazmat.primitives.interfaces.RSAPublicKey`
+            provider.
 
 .. class:: RSAPrivateNumbers(p, q, d, dmp1, dmq1, iqmp, public_numbers)
 
@@ -213,6 +222,16 @@ is unavailable.
         A `Chinese remainder theorem`_ coefficient used to speed up RSA
         operations. Calculated as: q\ :sup:`-1` mod p
 
+    .. method:: private_key(backend)
+
+        :param backend: A new instance of a
+            :class:`~cryptography.hazmat.backends.interfaces.RSABackend`
+            provider.
+
+        :returns: A
+            :class:`~cryptography.hazmat.primitives.interfaces.RSAPrivateKey`
+            provider.
+
 Handling partial RSA private keys
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
diff --git a/docs/hazmat/primitives/asymmetric/serialization.rst b/docs/hazmat/primitives/asymmetric/serialization.rst
index 874fce83..5438c249 100644
--- a/docs/hazmat/primitives/asymmetric/serialization.rst
+++ b/docs/hazmat/primitives/asymmetric/serialization.rst
@@ -5,6 +5,33 @@ Key Serialization
 
 .. currentmodule:: cryptography.hazmat.primitives.serialization
 
+.. testsetup::
+
+    pem_data = b"""
+    -----BEGIN RSA PRIVATE KEY-----
+    MIICXgIBAAKBgQDn09PV9KPE7Q+N5K5UtNLT1DLl8z/pKM2pP5tXqWx2OsEw00lC
+    kDHdHESwzS050s/8rtkERKKyusCzCm9+vC1pQzUlmtibfF4PQAQc1pJL6KHqlidg
+    Hw49atYmnC25CaeXt65pAYXoIacOZ8k5X7FW3Eagex8nG0iMw4ObOtg6CwIDAQAB
+    AoGBAL31l/4YYN1rNrSZLrQgGyUSGsbLxJHEKolFon95R3O1fzoH117gkstQb4TE
+    Cwv3jw/JIfBaYUq8tku/AE9D2Jx51x7kYaCuQIMTavKIgkXKfxTQCQDjSEfkvXMW
+    4WOIj5sYdSCNbzLbaeFsWG32bSsBTy/sSheDIlCEFnqDuqwBAkEA+wYfJEMDf5nS
+    VCQd9VKGM4HVeTWBioaWBFCflFdhc1Vb65dsNDp8iIMZgAHC2LEX5dMUmgqXk7AT
+    lwFlIeW4CwJBAOxsSfuIVMuPKyx1xQ6ebpC7zeVxIOdswcM8ain91MSGDdKZw6pF
+    ioFh3kUbKHw4yqqHbdRmUDAJ1mcgGJQOxgECQQCmQaGylKfmhWymyd0FtIip6J4I
+    z4ViyEznwrZOu6kRiEF/QiUqWmpMx/fFrmTsvC5Fy43jkIxgBsiSxRvEXa+NAkB+
+    5m0bhwTEslchKSGZhC6inzuYAQ4BSh4C1mXBnk5bIf0/Ymtk9KiwY8CzZS1o5+7Y
+    c5LfI/+8mTss5UxsBDYBAkEA6NqhcsNWndIJZiWUU4u+RjFUQXqH8WCyJmEDCNxs
+    7SGRS1DTUGX4Y70m9dQpguy6Zg+gpHC+o+ERZR06uEQr+w==
+    -----END RSA PRIVATE KEY-----
+    """.strip()
+    message = b""
+
+    def sign_with_rsa_key(key, message):
+        return b""
+
+    def sign_with_dsa_key(key, message):
+        return b""
+
 There are several common schemes for serializing asymmetric private and public
 keys to bytes. They generally support encryption of private keys and additional
 key metadata.
@@ -14,26 +41,31 @@ and will return an instance of the appropriate type. You should check that
 the returned key matches the type your application expects when using these
 methods.
 
-    .. code-block:: pycon
+    .. doctest::
 
-        >>> key = load_pkcs8_private_key(pem_data, None, backend)
-        >>> if isinstance(key, rsa.RSAPrivateKey):
-        >>>     signature = sign_with_rsa_key(key, message)
-        >>> elif isinstance(key, dsa.DSAPrivateKey):
-        >>>     signature = sign_with_dsa_key(key, message)
-        >>> else:
-        >>>     raise TypeError
+        >>> from cryptography.hazmat.backends import default_backend
+        >>> from cryptography.hazmat.primitives import interfaces
+        >>> from cryptography.hazmat.primitives.serialization import load_pem_pkcs8_private_key
+        >>> key = load_pem_pkcs8_private_key(pem_data, password=None, backend=default_backend())
+        >>> if isinstance(key, interfaces.RSAPrivateKey):
+        ...     signature = sign_with_rsa_key(key, message)
+        ... elif isinstance(key, interfaces.DSAPrivateKey):
+        ...     signature = sign_with_dsa_key(key, message)
+        ... else:
+        ...     raise TypeError
 
 
 PKCS #8 Format
 ~~~~~~~~~~~~~~
 
-PKCS #8 is a serialization format originally standardized by RSA and
-currently maintained by the IETF in :rfc:`5208`. It supports password based
-encryption and additional key metadata attributes.
+PKCS #8 is a serialization format originally standardized by RSA and currently
+maintained by the IETF in :rfc:`5208` and :rfc:`5958`. It supports password
+based encryption and additional key metadata attributes. These keys are
+recognizable because they all begin with ``-----BEGIN PRIVATE KEY-----`` or
+with ``-----BEGIN ENCRYPTED PRIVATE KEY-----`` if they have a password.
 
 
-.. function:: load_pkcs8_private_key(data, password, backend)
+.. function:: load_pem_pkcs8_private_key(data, password, backend)
 
     .. versionadded:: 0.5
 
@@ -44,6 +76,7 @@ encryption and additional key metadata attributes.
 
     :param bytes password: The password to use to decrypt the data. Should
         be ``None`` if the private key is not encrypted.
+
     :param backend: A
         :class:`~cryptography.hazmat.backends.interfaces.PKCS8SerializationBackend`
         provider.
@@ -65,11 +98,11 @@ encryption and additional key metadata attributes.
 Traditional OpenSSL Format
 ~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-The "traditional" PKCS #1 based serialization format used by OpenSSL.
-It supports password based symmetric key encryption. Commonly found in
-OpenSSL based TLS applications. It is usually found in PEM format with a
-header that mentions the type of the serialized key. e.g.
-``-----BEGIN RSA PRIVATE KEY-----``.
+The "traditional" PKCS #1 based serialization format used by OpenSSL. It
+supports password based symmetric key encryption. Commonly found in OpenSSL
+based TLS applications. It is usually found in PEM format with a header that
+mentions the type of the serialized key. e.g. ``-----BEGIN RSA PRIVATE
+KEY-----`` or ``-----BEGIN DSA PRIVATE KEY-----``.
 
 .. function:: load_pem_traditional_openssl_private_key(data, password, backend)
 
@@ -82,6 +115,7 @@ header that mentions the type of the serialized key. e.g.
 
     :param bytes password: The password to use to decrypt the data. Should
         be ``None`` if the private key is not encrypted.
+
     :param backend: A
         :class:`~cryptography.hazmat.backends.interfaces.TraditionalOpenSSLSerializationBackend`
         provider.
@@ -98,41 +132,3 @@ header that mentions the type of the serialized key. e.g.
     :raises UnsupportedAlgorithm: If the serialized key is of a type that
         is not supported by the backend or if the key is encrypted with a
         symmetric cipher that is not supported by the backend.
-
-
-RSA Numbers
-~~~~~~~~~~~
-
-.. function:: load_rsa_private_numbers(numbers, backend)
-
-    .. versionadded:: 0.5
-
-    Create a private key instance using the given backend and numbers.
-
-    :param numbers: An instance of
-        :class:`~cryptography.hazmat.primitives.asymmetric.rsa.RSAPrivateNumbers`.
-
-    :param backend: A
-        :class:`~cryptography.hazmat.backends.interfaces.RSABackend` provider.
-
-    :returns: A new instance of a private key.
-
-    :raises UnsupportedAlgorithm: If the given backend does not support loading
-        numbers.
-
-.. function:: load_rsa_public_numbers(numbers, backend)
-
-    .. versionadded:: 0.5
-
-    Create a public key instance using the given backend and numbers.
-
-    :param numbers: An instance of
-        :class:`~cryptography.hazmat.primitives.asymmetric.rsa.RSAPublicNumbers`.
-
-    :param backend: A
-        :class:`~cryptography.hazmat.backends.interfaces.RSABackend` provider.
-
-    :returns: A new instance of a public key.
-
-    :raises UnsupportedAlgorithm: If the given backend does not support loading
-        numbers.
diff --git a/docs/hazmat/primitives/mac/cmac.rst b/docs/hazmat/primitives/mac/cmac.rst
index 498b8b1e..1ba1b3fa 100644
--- a/docs/hazmat/primitives/mac/cmac.rst
+++ b/docs/hazmat/primitives/mac/cmac.rst
@@ -45,8 +45,10 @@ A subset of CMAC with the AES-128 algorithm is described in :rfc:`4493`.
     To check that a given signature is correct use the :meth:`verify` method.
     You will receive an exception if the signature is wrong:
 
-    .. code-block:: pycon
+    .. doctest::
 
+        >>> c = cmac.CMAC(algorithms.AES(key), backend=default_backend())
+        >>> c.update(b"message to authenticate")
         >>> c.verify(b"an incorrect signature")
         Traceback (most recent call last):
         ...
diff --git a/docs/hazmat/primitives/mac/hmac.rst b/docs/hazmat/primitives/mac/hmac.rst
index d56927b9..9ce49c8d 100644
--- a/docs/hazmat/primitives/mac/hmac.rst
+++ b/docs/hazmat/primitives/mac/hmac.rst
@@ -45,8 +45,10 @@ of a message.
     To check that a given signature is correct use the :meth:`verify` method.
     You will receive an exception if the signature is wrong:
 
-    .. code-block:: pycon
+    .. doctest::
 
+        >>> h = hmac.HMAC(key, hashes.SHA256(), backend=default_backend())
+        >>> h.update(b"message to hash")
         >>> h.verify(b"an incorrect signature")
         Traceback (most recent call last):
         ...
diff --git a/docs/installation.rst b/docs/installation.rst
index 339d8b76..6b8bb219 100644
--- a/docs/installation.rst
+++ b/docs/installation.rst
@@ -13,7 +13,7 @@ Supported platforms
 Currently we test ``cryptography`` on Python 2.6, 2.7, 3.2, 3.3, 3.4 and PyPy
 on these operating systems.
 
-* x86-64 CentOS 6.4 and CentOS 5.x
+* x86-64 CentOS 7.x, 6.4 and CentOS 5.x
 * x86-64 FreeBSD 9.2 and FreeBSD 10
 * OS X 10.9 Mavericks, 10.8 Mountain Lion, and 10.7 Lion
 * x86-64 Ubuntu 12.04 LTS
@@ -29,7 +29,7 @@ OpenSSL releases:
 * ``OpenSSL 1.0.0-fips`` (``RHEL/CentOS 6.4``)
 * ``OpenSSL 1.0.1``
 * ``OpenSSL 1.0.1e-freebsd``
-* ``OpenSSL 1.0.1g``
+* ``OpenSSL 1.0.1h``
 * ``OpenSSL 1.0.2 beta``
 
 On Windows
diff --git a/docs/random-numbers.rst b/docs/random-numbers.rst
index 12969d1c..68a72cf7 100644
--- a/docs/random-numbers.rst
+++ b/docs/random-numbers.rst
@@ -13,10 +13,9 @@ provided random number generator`_, which is available as ``os.urandom()``. For
 example, if you need 16 bytes of random data for an initialization vector, you
 can obtain them with:
 
-.. code-block:: pycon
+.. doctest::
 
     >>> import os
-    >>> os.urandom(16)
-    '...'
+    >>> iv = os.urandom(16)
 
 .. _`always use your operating system's provided random number generator`: http://sockpuppet.org/blog/2014/02/25/safely-generate-random-numbers/