2 files changed, 72 insertions, 0 deletions
diff --git a/docs/hazmat/backends/interfaces.rst b/docs/hazmat/backends/interfaces.rst
index ff389cb5..78a35cd9 100644
--- a/docs/hazmat/backends/interfaces.rst
+++ b/docs/hazmat/backends/interfaces.rst
@@ -263,6 +263,26 @@ A specific ``backend`` may provide one or more of these interfaces.
         :returns: ``True`` if the specified ``algorithm`` is supported by this
             backend, otherwise ``False``.
 
+    .. method:: rsa_padding_supported(padding)
+
+        Check if the specified ``padding`` is supported by the backend.
+
+        :param padding: An instance of an
+            :class:`~cryptography.hazmat.primitives.interfaces.AsymmetricPadding`
+            provider.
+
+        :returns: ``True`` if the specified ``padding`` is supported by this
+            backend, otherwise ``False``.
+
+    .. method:: generate_rsa_parameters_supported(public_exponent, key_size)
+
+        Check if the specified parameters are supported for key generation by
+        the backend.
+
+        :param int public_exponent: The public exponent.
+
+        :param int key_size: The bit length of the generated modulus.
+
     .. method:: decrypt_rsa(private_key, ciphertext, padding)
 
         :param private_key: An instance of an
diff --git a/docs/hazmat/primitives/asymmetric/serialization.rst b/docs/hazmat/primitives/asymmetric/serialization.rst
index 8d32ae58..2b3eb511 100644
--- a/docs/hazmat/primitives/asymmetric/serialization.rst
+++ b/docs/hazmat/primitives/asymmetric/serialization.rst
@@ -9,6 +9,58 @@ 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.
 
+Many serialization formats support multiple different types of asymmetric keys
+and will return an 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
+
+        >>> 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
+
+
+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.
+
+
+.. function:: load_pkcs8_private_key(data, password, backend)
+
+    .. versionadded:: 0.5
+
+    Deserialize a private key from PEM encoded data to one of the supported
+    asymmetric private key types.
+
+    :param bytes data: The PEM encoded key data.
+
+    :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.
+
+    :returns: A new instance of a private key.
+
+    :raises ValueError: If the PEM data could not be decrypted or if its
+        structure could not be decoded successfully.
+
+    :raises TypeError: If a ``password`` was given and the private key was
+        not encrypted. Or if the key was encrypted but no
+        password was supplied.
+
+    :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.
+
 
 Traditional OpenSSL Format
 ~~~~~~~~~~~~~~~~~~~~~~~~~~