From 3f157e00f4fe3a86da17a1de8e2222705147728f Mon Sep 17 00:00:00 2001
From: Paul Kehrer <paul.l.kehrer@gmail.com>
Date: Sat, 28 Feb 2015 11:31:06 -0600
Subject: support RSA public key serialization

---
 docs/hazmat/primitives/asymmetric/rsa.rst          | 55 +++++++++++++++++++++-
 .../hazmat/primitives/asymmetric/serialization.rst | 19 ++++++++
 2 files changed, 73 insertions(+), 1 deletion(-)

(limited to 'docs/hazmat/primitives/asymmetric')

diff --git a/docs/hazmat/primitives/asymmetric/rsa.rst b/docs/hazmat/primitives/asymmetric/rsa.rst
index a8d7bfc0..e7033100 100644
--- a/docs/hazmat/primitives/asymmetric/rsa.rst
+++ b/docs/hazmat/primitives/asymmetric/rsa.rst
@@ -83,7 +83,7 @@ There is also support for :func:`loading public keys in the SSH format
 Key serialization
 ~~~~~~~~~~~~~~~~~
 
-If you have a key that you've loaded or generated which implements the
+If you have a private key that you've loaded or generated which implements the
 :class:`~cryptography.hazmat.primitives.asymmetric.rsa.RSAPrivateKeyWithSerialization`
 interface you can use
 :meth:`~cryptography.hazmat.primitives.asymmetric.rsa.RSAPrivateKeyWithSerialization.private_bytes`
@@ -113,6 +113,23 @@ It is also possible to serialize without encryption using
     >>> pem.splitlines()[0]
     '-----BEGIN RSA PRIVATE KEY-----'
 
+Similarly, if your public key implements
+:class:`~cryptography.hazmat.primitives.asymmetric.rsa.RSAPublicKeyWithSerialization`
+interface you can use
+:meth:`~cryptography.hazmat.primitives.asymmetric.rsa.RSAPublicKeyWithSerialization.public_bytes`
+to serialize the key.
+
+.. doctest::
+
+    >>> from cryptography.hazmat.primitives import serialization
+    >>> public_key = private_key.public_key()
+    >>> pem = public_key.public_bytes(
+    ...    encoding=serialization.Encoding.PEM,
+    ...    format=serialization.PublicFormat.SubjectPublicKeyInfo
+    ... )
+    >>> pem.splitlines()[0]
+    '-----BEGIN PUBLIC KEY-----'
+
 Signing
 ~~~~~~~
 
@@ -626,6 +643,42 @@ Key interfaces
             instance.
 
 
+.. class:: RSAPublicKeyWithSerialization
+
+    .. versionadded:: 0.8
+
+    Extends :class:`RSAPublicKey`.
+
+    .. method:: public_numbers()
+
+        Create a
+        :class:`~cryptography.hazmat.primitives.asymmetric.rsa.RSAPublicNumbers`
+        object.
+
+        :returns: An
+            :class:`~cryptography.hazmat.primitives.asymmetric.rsa.RSAPublicNumbers`
+            instance.
+
+    .. method:: public_bytes(encoding, format)
+
+        Allows serialization of the key to bytes. Encoding (
+        :attr:`~cryptography.hazmat.primitives.serialization.Encoding.PEM` or
+        :attr:`~cryptography.hazmat.primitives.serialization.Encoding.DER`) and
+        format (
+        :attr:`~cryptography.hazmat.primitives.serialization.PublicFormat.SubjectPublicKeyInfo`
+        or
+        :attr:`~cryptography.hazmat.primitives.serialization.PublicFormat.PKCS1`)
+        are chosen to define the exact serialization.
+
+        :param encoding: A value from the
+            :class:`~cryptography.hazmat.primitives.serialization.Encoding` enum.
+
+        :param format: A value from the
+            :class:`~cryptography.hazmat.primitives.serialization.PublicFormat` enum.
+
+        :return bytes: Serialized key.
+
+
 .. _`RSA`: https://en.wikipedia.org/wiki/RSA_(cryptosystem)
 .. _`public-key`: https://en.wikipedia.org/wiki/Public-key_cryptography
 .. _`specific mathematical properties`: https://en.wikipedia.org/wiki/RSA_(cryptosystem)#Key_generation
diff --git a/docs/hazmat/primitives/asymmetric/serialization.rst b/docs/hazmat/primitives/asymmetric/serialization.rst
index 4a2aedc9..dd532b51 100644
--- a/docs/hazmat/primitives/asymmetric/serialization.rst
+++ b/docs/hazmat/primitives/asymmetric/serialization.rst
@@ -309,6 +309,25 @@ Serialization Formats
         encryption. Choose this unless you have explicit legacy compatibility
         requirements.
 
+.. class:: PublicFormat
+
+    .. versionadded:: 0.8
+
+    An enumeration for public key formats. Used with the ``public_bytes``
+    method available on
+    :class:`~cryptography.hazmat.primitives.asymmetric.rsa.RSAPublicKeyWithSerialization`.
+
+    .. attribute:: SubjectPublicKeyInfo
+
+        This is the typical public key format. It consists of an algorithm
+        identifier and the public key as a bit string. Choose this unless
+        you have specific needs.
+
+    .. attribute:: PKCS1
+
+        Just the public key elements (without the algorithm identifier). This
+        format is occasionally used by various systems.
+
 Serialization Encodings
 ~~~~~~~~~~~~~~~~~~~~~~~
 
-- 
cgit v1.2.3