X448 support (#4580)

* x448 support

This work was originally authored by derwolfe

* update docs to have a more useful derived key length

* error if key is not a valid length in from_public_bytes

* one more

* switch to using evp_pkey_keygen_gc for x448 keygen

* review feedback

* switch to using evp_pkey_derive

* nit fix

2 files changed, 105 insertions, 0 deletions

diff --git a/docs/hazmat/primitives/asymmetric/index.rst b/docs/hazmat/primitives/asymmetric/index.rst
index 173faa9e..1561c59f 100644
--- a/docs/hazmat/primitives/asymmetric/index.rst
+++ b/docs/hazmat/primitives/asymmetric/index.rst
@@ -24,6 +24,7 @@ private key is able to decrypt it.
     :maxdepth: 1
 
     x25519
+    x448
     ec
     rsa
     dh
diff --git a/docs/hazmat/primitives/asymmetric/x448.rst b/docs/hazmat/primitives/asymmetric/x448.rst
new file mode 100644
index 00000000..057b7b50
--- /dev/null
+++ b/docs/hazmat/primitives/asymmetric/x448.rst
@@ -0,0 +1,104 @@
+.. hazmat::
+
+X448 key exchange
+===================
+
+.. currentmodule:: cryptography.hazmat.primitives.asymmetric.x448
+
+
+X448 is an elliptic curve `Diffie-Hellman key exchange`_ using `Curve448`_.
+It allows two parties to jointly agree on a shared secret using an insecure
+channel.
+
+
+Exchange Algorithm
+~~~~~~~~~~~~~~~~~~
+
+For most applications the ``shared_key`` should be passed to a key
+derivation function. This allows mixing of additional information into the
+key, derivation of multiple keys, and destroys any structure that may be
+present.
+
+.. doctest::
+
+    >>> from cryptography.hazmat.backends import default_backend
+    >>> from cryptography.hazmat.primitives import hashes
+    >>> from cryptography.hazmat.primitives.asymmetric.x448 import X448PrivateKey
+    >>> from cryptography.hazmat.primitives.kdf.hkdf import HKDF
+    >>> # Generate a private key for use in the exchange.
+    >>> private_key = X448PrivateKey.generate()
+    >>> # In a real handshake the peer_public_key will be received from the
+    >>> # other party. For this example we'll generate another private key and
+    >>> # get a public key from that. Note that in a DH handshake both peers
+    >>> # must agree on a common set of parameters.
+    >>> peer_public_key = X448PrivateKey.generate().public_key()
+    >>> shared_key = private_key.exchange(peer_public_key)
+    >>> # Perform key derivation.
+    >>> derived_key = HKDF(
+    ...     algorithm=hashes.SHA256(),
+    ...     length=32,
+    ...     salt=None,
+    ...     info=b'handshake data',
+    ...     backend=default_backend()
+    ... ).derive(shared_key)
+    >>> # For the next handshake we MUST generate another private key.
+    >>> private_key_2 = X448PrivateKey.generate()
+    >>> peer_public_key_2 = X448PrivateKey.generate().public_key()
+    >>> shared_key_2 = private_key_2.exchange(peer_public_key_2)
+    >>> derived_key_2 = HKDF(
+    ...     algorithm=hashes.SHA256(),
+    ...     length=32,
+    ...     salt=None,
+    ...     info=b'handshake data',
+    ...     backend=default_backend()
+    ... ).derive(shared_key_2)
+
+Key interfaces
+~~~~~~~~~~~~~~
+
+.. class:: X448PrivateKey
+
+    .. versionadded:: 2.5
+
+    .. classmethod:: generate()
+
+        Generate an X448 private key.
+
+        :returns: :class:`X448PrivateKey`
+
+    .. method:: public_key()
+
+        :returns: :class:`X448PublicKey`
+
+    .. method:: exchange(peer_public_key)
+
+        :param X448PublicKey peer_public_key: The public key for the
+            peer.
+
+        :returns bytes: A shared key.
+
+.. class:: X448PublicKey
+
+    .. versionadded:: 2.5
+
+    .. classmethod:: from_public_bytes(data)
+
+        :param bytes data: 56 byte public key.
+
+        :returns: :class:`X448PublicKey`
+
+        .. doctest::
+
+            >>> from cryptography.hazmat.primitives.asymmetric import x448
+            >>> private_key = x448.X448PrivateKey.generate()
+            >>> public_key = private_key.public_key()
+            >>> public_bytes = public_key.public_bytes()
+            >>> loaded_public_key = x448.X448PublicKey.from_public_bytes(public_bytes)
+
+    .. method:: public_bytes()
+
+        :returns bytes: The raw bytes of the public key.
+
+
+.. _`Diffie-Hellman key exchange`: https://en.wikipedia.org/wiki/Diffie%E2%80%93Hellman_key_exchange
+.. _`Curve448`: https://en.wikipedia.org/wiki/Curve448