From c6c25c21496858271fbc4c89fb102074fd3d5f60 Mon Sep 17 00:00:00 2001
From: Paul Kehrer <paul.l.kehrer@gmail.com>
Date: Mon, 14 Jan 2019 21:50:17 -0600
Subject: Serialization x25519 (#4688)

* modify x25519 serialization to match x448

supports raw and pkcs8 encoding on private_bytes
supports raw and subjectpublickeyinfo on public_bytes

deprecates zero argument call to public_bytes

* add docs

* this is public now

* don't need that

* review feedback
---
 docs/hazmat/primitives/asymmetric/x25519.rst | 88 ++++++++++++++++++++++++++--
 1 file changed, 84 insertions(+), 4 deletions(-)

(limited to 'docs')

diff --git a/docs/hazmat/primitives/asymmetric/x25519.rst b/docs/hazmat/primitives/asymmetric/x25519.rst
index 67ed28092..ea01fbaa0 100644
--- a/docs/hazmat/primitives/asymmetric/x25519.rst
+++ b/docs/hazmat/primitives/asymmetric/x25519.rst
@@ -66,6 +66,29 @@ Key interfaces
 
         :returns: :class:`X25519PrivateKey`
 
+    .. classmethod:: from_private_bytes(data)
+
+        .. versionadded:: 2.5
+
+        A class method for loading an X25519 key encoded as
+        :attr:`~cryptography.hazmat.primitives.serialization.Encoding.Raw`.
+
+        :param bytes data: 32 byte private key.
+
+        :returns: :class:`X25519PrivateKey`
+
+        .. doctest::
+
+            >>> from cryptography.hazmat.primitives import serialization
+            >>> from cryptography.hazmat.primitives.asymmetric import x25519
+            >>> private_key = x25519.X25519PrivateKey.generate()
+            >>> private_bytes = private_key.private_bytes(
+            ...     encoding=serialization.Encoding.Raw,
+            ...     format=serialization.PrivateFormat.Raw,
+            ...     encryption_algorithm=serialization.NoEncryption()
+            ... )
+            >>> loaded_private_key = x25519.X25519PrivateKey.from_private_bytes(private_bytes)
+
     .. method:: public_key()
 
         :returns: :class:`X25519PublicKey`
@@ -77,6 +100,38 @@ Key interfaces
 
         :returns bytes: A shared key.
 
+    .. method:: private_bytes(encoding, format, encryption_algorithm)
+
+        .. versionadded:: 2.5
+
+        Allows serialization of the key to bytes. Encoding (
+        :attr:`~cryptography.hazmat.primitives.serialization.Encoding.PEM`,
+        :attr:`~cryptography.hazmat.primitives.serialization.Encoding.DER`, or
+        :attr:`~cryptography.hazmat.primitives.serialization.Encoding.Raw`) and
+        format (
+        :attr:`~cryptography.hazmat.primitives.serialization.PrivateFormat.PKCS8`
+        or
+        :attr:`~cryptography.hazmat.primitives.serialization.PrivateFormat.Raw`
+        ) 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.PrivateFormat`
+            enum. If the ``encoding`` is
+            :attr:`~cryptography.hazmat.primitives.serialization.Encoding.Raw`
+            then ``format`` must be
+            :attr:`~cryptography.hazmat.primitives.serialization.PrivateFormat.Raw`
+            , otherwise it must be
+            :attr:`~cryptography.hazmat.primitives.serialization.PrivateFormat.PKCS8`.
+
+        :param encryption_algorithm: An instance of an object conforming to the
+            :class:`~cryptography.hazmat.primitives.serialization.KeySerializationEncryption`
+            interface.
+
+        :return bytes: Serialized key.
+
 .. class:: X25519PublicKey
 
     .. versionadded:: 2.0
@@ -92,12 +147,37 @@ Key interfaces
             >>> from cryptography.hazmat.primitives.asymmetric import x25519
             >>> private_key = x25519.X25519PrivateKey.generate()
             >>> public_key = private_key.public_key()
-            >>> public_bytes = public_key.public_bytes()
+            >>> public_bytes = public_key.public_bytes(
+            ...     encoding=serialization.Encoding.Raw,
+            ...     format=serialization.PublicFormat.Raw
+            ... )
             >>> loaded_public_key = x25519.X25519PublicKey.from_public_bytes(public_bytes)
 
-    .. method:: public_bytes()
-
-        :returns bytes: The raw bytes of the public key.
+    .. method:: public_bytes(encoding, format)
+
+        Allows serialization of the key to bytes. Encoding (
+        :attr:`~cryptography.hazmat.primitives.serialization.Encoding.PEM`,
+        :attr:`~cryptography.hazmat.primitives.serialization.Encoding.DER`, or
+        :attr:`~cryptography.hazmat.primitives.serialization.Encoding.Raw`) and
+        format (
+        :attr:`~cryptography.hazmat.primitives.serialization.PublicFormat.SubjectPublicKeyInfo`
+        or
+        :attr:`~cryptography.hazmat.primitives.serialization.PublicFormat.Raw`
+        ) 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. If the ``encoding`` is
+            :attr:`~cryptography.hazmat.primitives.serialization.Encoding.Raw`
+            then ``format`` must be
+            :attr:`~cryptography.hazmat.primitives.serialization.PublicFormat.Raw`
+            , otherwise it must be
+            :attr:`~cryptography.hazmat.primitives.serialization.PublicFormat.SubjectPublicKeyInfo`.
+
+        :returns bytes: The public key bytes.
 
 
 .. _`Diffie-Hellman key exchange`: https://en.wikipedia.org/wiki/Diffie%E2%80%93Hellman_key_exchange
-- 
cgit v1.2.3