Merge pull request #1326 from alex/pem-serialization-backend

Start moving everything to the new API

1 files changed, 44 insertions, 2 deletions

diff --git a/docs/hazmat/primitives/asymmetric/serialization.rst b/docs/hazmat/primitives/asymmetric/serialization.rst
index 5438c249..84b69fdc 100644
--- a/docs/hazmat/primitives/asymmetric/serialization.rst
+++ b/docs/hazmat/primitives/asymmetric/serialization.rst
@@ -45,8 +45,8 @@ methods.
 
         >>> 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())
+        >>> from cryptography.hazmat.primitives.serialization import load_pem_private_key
+        >>> key = load_pem_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):
@@ -54,6 +54,44 @@ methods.
         ... else:
         ...     raise TypeError
 
+PEM
+~~~
+
+PEM is an encapsulation format, meaning keys in it can actually be any of
+several different key types. However these are all self-identifying, so you
+don't need to worry about this detail. PEM keys are recognizable because they
+all begin with ``-----BEGIN {format}-----`` and end with ``-----END
+{format}-----``.
+
+.. function:: load_pem_private_key(data, password, backend):
+
+    .. versionadded:: 0.6
+
+    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.
+
 
 PKCS #8 Format
 ~~~~~~~~~~~~~~
@@ -72,6 +110,8 @@ with ``-----BEGIN ENCRYPTED PRIVATE KEY-----`` if they have a password.
     Deserialize a private key from PEM encoded data to one of the supported
     asymmetric private key types.
 
+    This has been deprecated in favor of :func:`load_pem_private_key`.
+
     :param bytes data: The PEM encoded key data.
 
     :param bytes password: The password to use to decrypt the data. Should
@@ -111,6 +151,8 @@ KEY-----`` or ``-----BEGIN DSA PRIVATE KEY-----``.
     Deserialize a private key from PEM encoded data to one of the supported
     asymmetric private key types.
 
+    This has been deprecated in favor of :func:`load_pem_private_key`.
+
     :param bytes data: The PEM encoded key data.
 
     :param bytes password: The password to use to decrypt the data. Should