change ECDH documentation to show both classical ECDH and ECDHE (#4530)

1 files changed, 52 insertions, 6 deletions

diff --git a/docs/hazmat/primitives/asymmetric/ec.rst b/docs/hazmat/primitives/asymmetric/ec.rst
index 8d03a093..e36a5a14 100644
--- a/docs/hazmat/primitives/asymmetric/ec.rst
+++ b/docs/hazmat/primitives/asymmetric/ec.rst
@@ -238,6 +238,58 @@ Elliptic Curve Key Exchange algorithm
     key, derivation of multiple keys, and destroys any structure that may be
     present.
 
+    .. warning::
+
+        This example does not give `forward secrecy`_ and is only provided as a
+        demonstration of the basic Diffie-Hellman construction. For real world
+        applications always use the ephemeral form described after this example.
+
+    .. doctest::
+
+        >>> from cryptography.hazmat.backends import default_backend
+        >>> from cryptography.hazmat.primitives import hashes
+        >>> from cryptography.hazmat.primitives.asymmetric import ec
+        >>> from cryptography.hazmat.primitives.kdf.hkdf import HKDF
+        >>> # Generate a private key for use in the exchange.
+        >>> server_private_key = ec.generate_private_key(
+        ...     ec.SECP384R1(), default_backend()
+        ... )
+        >>> # In a real handshake the peer is a remote client. For this
+        >>> # example we'll generate another local private key though.
+        >>> peer_private_key = ec.generate_private_key(
+        ...     ec.SECP384R1(), default_backend()
+        ... )
+        >>> shared_key = server_private_key.exchange(
+        ...     ec.ECDH(), peer_private_key.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)
+        >>> # And now we can demonstrate that the handshake performed in the
+        >>> # opposite direction gives the same final value
+        >>> same_shared_key = peer_private_key.exchange(
+        ...     ec.ECDH(), server_private_key.public_key())
+        >>> # Perform key derivation.
+        >>> same_derived_key = HKDF(
+        ...     algorithm=hashes.SHA256(),
+        ...     length=32,
+        ...     salt=None,
+        ...     info=b'handshake data',
+        ...     backend=default_backend()
+        ... ).derive(same_shared_key)
+        >>> derived_key == same_derived_key
+        True
+
+    ECDHE (or EECDH), the ephemeral form of this exchange, is **strongly
+    preferred** over simple ECDH and provides `forward secrecy`_ when used.
+    You must generate a new private key using :func:`generate_private_key` for
+    each :meth:`~EllipticCurvePrivateKey.exchange` when performing an ECDHE key
+    exchange. An example of the ephemeral form:
+
     .. doctest::
 
         >>> from cryptography.hazmat.backends import default_backend
@@ -279,12 +331,6 @@ Elliptic Curve Key Exchange algorithm
         ...     backend=default_backend()
         ... ).derive(shared_key_2)
 
-    ECDHE (or EECDH), the ephemeral form of this exchange, is **strongly
-    preferred** over simple ECDH and provides `forward secrecy`_ when used.
-    You must generate a new private key using :func:`generate_private_key` for
-    each :meth:`~EllipticCurvePrivateKey.exchange` when performing an ECDHE key
-    exchange.
-
 Elliptic Curves
 ---------------