Support for traditional OpenSSL and PKCS8 RSA private key serialization

2 files changed, 131 insertions, 1 deletions

diff --git a/docs/hazmat/primitives/asymmetric/rsa.rst b/docs/hazmat/primitives/asymmetric/rsa.rst
index fd97d75b..66bb37c9 100644
--- a/docs/hazmat/primitives/asymmetric/rsa.rst
+++ b/docs/hazmat/primitives/asymmetric/rsa.rst
@@ -80,6 +80,37 @@ password. If the key is encrypted we can pass a ``bytes`` object as the
 There is also support for :func:`loading public keys in the SSH format
 <cryptography.hazmat.primitives.serialization.load_ssh_public_key>`.
 
+Key serialization
+~~~~~~~~~~~~~~~~~
+
+If you have a previously loaded or generated key that has the
+:class:`~cryptography.hazmat.primitives.asymmetric.rsa.RSAPrivateKeyWithSerialization`
+interface you can use
+:meth:`~cryptography.hazmat.primitives.asymmetric.rsa.RSAPrivateKeyWithSerialization.dump`
+to serialize the key.
+
+.. doctest::
+
+    >>> from cryptography.hazmat.primitives import serialization
+    >>> pem = private_key.dump(
+    ...    serialization.PKCS8(serialization.Encoding.PEM),
+    ...    serialization.BestAvailable(b'passwordgoeshere')
+    ... )
+    >>> pem.splitlines()[0]
+    '-----BEGIN ENCRYPTED PRIVATE KEY-----'
+
+It is also possible to serialize without encryption using
+:class:`~cryptography.hazmat.primitives.serialization.NoEncryption`.
+
+.. doctest::
+
+    >>> pem = private_key.dump(
+    ...    serialization.TraditionalOpenSSL(serialization.Encoding.PEM),
+    ...    serialization.NoEncryption()
+    ... )
+    >>> pem.splitlines()[0]
+    '-----BEGIN RSA PRIVATE KEY-----'
+
 Signing
 ~~~~~~~
 
@@ -485,6 +516,37 @@ Key interfaces
             instance.
 
 
+.. class:: RSAPrivateKeyWithSerialization
+
+    .. versionadded:: 0.8
+
+    Extends :class:`RSAPrivateKey`.
+
+    .. method:: private_numbers()
+
+        Create a
+        :class:`~cryptography.hazmat.primitives.asymmetric.rsa.RSAPrivateNumbers`
+        object.
+
+        :returns: An
+            :class:`~cryptography.hazmat.primitives.asymmetric.rsa.RSAPrivateNumbers`
+            instance.
+
+    .. method:: dump(serializer, encryption_type)
+
+        Dump the key to PEM encoded bytes using the serializer provided.
+
+        :param serializer: An instance of
+            :class:`~cryptography.hazmat.primitives.serialization.TraditionalOpenSSL`
+            or :class:`~cryptography.hazmat.primitives.serialization.PKCS8`
+
+        :param encryption_type: An instance of an object conforming to the
+            :class:`~cryptography.hazmat.primitives.serialization.KeySerializationEncryption`
+            interface.
+
+        :return bytes: Serialized key.
+
+
 .. class:: RSAPublicKey
 
     .. versionadded:: 0.2
diff --git a/docs/hazmat/primitives/asymmetric/serialization.rst b/docs/hazmat/primitives/asymmetric/serialization.rst
index 87f3c0b0..68eaf021 100644
--- a/docs/hazmat/primitives/asymmetric/serialization.rst
+++ b/docs/hazmat/primitives/asymmetric/serialization.rst
@@ -3,7 +3,7 @@
 Key Serialization
 =================
 
-.. currentmodule:: cryptography.hazmat.primitives.serialization
+.. module:: cryptography.hazmat.primitives.serialization
 
 .. testsetup::
 
@@ -282,3 +282,71 @@ DSA keys look almost identical but begin with ``ssh-dss`` rather than
 
     :raises cryptography.exceptions.UnsupportedAlgorithm: If the serialized
         key is of a type that is not supported.
+
+Serializers
+~~~~~~~~~~~
+
+Instances of these classes can be passed to methods like
+:meth:`~cryptography.hazmat.primitives.asymmetric.rsa.RSAPrivateKeyWithSerialization.dump`.
+
+.. class:: PKCS8(encoding)
+
+    .. versionadded:: 0.8
+
+    A serializer for the PKCS #8 format.
+
+    :param encoding: A value from the
+        :class:`~cryptography.hazmat.primitives.serialization.Encoding` enum.
+
+.. class:: TraditionalOpenSSL(encoding)
+
+    .. versionadded:: 0.8
+
+    A serializer for the traditional OpenSSL (sometimes known as PKCS #1)
+    format.
+
+    :param encoding: A value from the
+        :class:`~cryptography.hazmat.primitives.serialization.Encoding` enum.
+
+
+Serialization Encryption Types
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+.. class:: KeySerializationEncryption
+
+    Objects with this interface are usable as encryption types with methods
+    like
+    :meth:`~cryptography.hazmat.primitives.asymmetric.rsa.RSAPrivateKeyWithSerialization.dump`.
+    All other classes in this section represent the available choices for
+    encryption and have this interface.
+
+.. class:: BestAvailable
+
+    Encrypt using the best available encryption for a given key's backend.
+    This is a curated encryption choice and the algorithm may change over
+    time.
+
+    :param bytes password: The password to use for encryption.
+
+.. class:: NoEncryption
+
+    Do not encrypt.
+
+
+Utility Classes
+~~~~~~~~~~~~~~~
+
+.. class:: Encoding
+
+    .. versionadded:: 0.8
+
+    An enumeration for encoding types. Used by :class:`PKCS8` and
+    :class:`TraditionalOpenSSL`.
+
+    .. attribute:: PEM
+
+        For PEM format. This is a base64 format with delimiters.
+
+    .. attribute:: DER
+
+        For DER format. This is a binary format.