ed25519 support (#4114)

* ed25519 support

* review feedback

2 files changed, 160 insertions, 0 deletions

diff --git a/docs/hazmat/primitives/asymmetric/ed25519.rst b/docs/hazmat/primitives/asymmetric/ed25519.rst
new file mode 100644
index 00000000..8893fbbd
--- /dev/null
+++ b/docs/hazmat/primitives/asymmetric/ed25519.rst
@@ -0,0 +1,159 @@
+.. hazmat::
+
+Ed25519 signing
+===============
+
+.. currentmodule:: cryptography.hazmat.primitives.asymmetric.ed25519
+
+
+Ed25519 is an elliptic curve signing algorithm using `EdDSA`_ and
+`Curve25519`_. If you do not have legacy interoperability concerns then you
+should strongly consider using this signature algorithm.
+
+
+Signing & Verification
+~~~~~~~~~~~~~~~~~~~~~~
+
+.. doctest::
+
+    >>> from cryptography.hazmat.primitives.asymmetric.ed25519 import Ed25519PrivateKey
+    >>> private_key = Ed25519PrivateKey.generate()
+    >>> signature = private_key.sign(b"my authenticated message")
+    >>> public_key = private_key.public_key()
+    >>> # Raises InvalidSignature if verification fails
+    >>> public_key.verify(signature, b"my authenticated message")
+
+Key interfaces
+~~~~~~~~~~~~~~
+
+.. class:: Ed25519PrivateKey
+
+    .. versionadded:: 2.6
+
+    .. classmethod:: generate()
+
+        Generate an Ed25519 private key.
+
+        :returns: :class:`Ed25519PrivateKey`
+
+    .. classmethod:: from_private_bytes(data)
+
+        :param data: 32 byte private key.
+        :type data: :term:`bytes-like`
+
+        :returns: :class:`Ed25519PrivateKey`
+
+        .. doctest::
+
+            >>> from cryptography.hazmat.primitives import serialization
+            >>> from cryptography.hazmat.primitives.asymmetric import ed25519
+            >>> private_key = ed25519.Ed25519PrivateKey.generate()
+            >>> private_bytes = private_key.private_bytes(
+            ...     encoding=serialization.Encoding.Raw,
+            ...     format=serialization.PrivateFormat.Raw,
+            ...     encryption_algorithm=serialization.NoEncryption()
+            ... )
+            >>> loaded_private_key = ed25519.Ed25519PrivateKey.from_private_bytes(private_bytes)
+
+
+    .. method:: public_key()
+
+        :returns: :class:`Ed25519PublicKey`
+
+    .. method:: sign(data)
+
+        :param bytes data: The data to sign.
+
+        :returns bytes: The 64 byte signature.
+
+    .. method:: private_bytes(encoding, format, encryption_algorithm)
+
+        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:: Ed25519PublicKey
+
+    .. versionadded:: 2.6
+
+    .. classmethod:: from_public_bytes(data)
+
+        :param bytes data: 32 byte public key.
+
+        :returns: :class:`Ed25519PublicKey`
+
+        .. doctest::
+
+            >>> from cryptography.hazmat.primitives import serialization
+            >>> from cryptography.hazmat.primitives.asymmetric import ed25519
+            >>> private_key = ed25519.Ed25519PrivateKey.generate()
+            >>> public_key = private_key.public_key()
+            >>> public_bytes = public_key.public_bytes(
+            ...     encoding=serialization.Encoding.Raw,
+            ...     format=serialization.PublicFormat.Raw
+            ... )
+            >>> loaded_public_key = ed25519.Ed25519PublicKey.from_public_bytes(public_bytes)
+
+    .. 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.
+
+    .. method:: verify(signature, data)
+
+        :param bytes signature: The signature to verify.
+
+        :param bytes data: The data to verify.
+
+        :raises cryptography.exceptions.InvalidSignature: Raised when the
+            signature cannot be verified.
+
+
+
+.. _`EdDSA`: https://en.wikipedia.org/wiki/EdDSA
+.. _`Curve25519`: https://en.wikipedia.org/wiki/Curve25519
diff --git a/docs/hazmat/primitives/asymmetric/index.rst b/docs/hazmat/primitives/asymmetric/index.rst
index 1561c59f..5e5bdb9a 100644
--- a/docs/hazmat/primitives/asymmetric/index.rst
+++ b/docs/hazmat/primitives/asymmetric/index.rst
@@ -23,6 +23,7 @@ private key is able to decrypt it.
 .. toctree::
     :maxdepth: 1
 
+    ed25519
     x25519
     x448
     ec