Merge branch 'master' into reorder_libs

3 files changed, 100 insertions, 55 deletions

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.