Modify DH/ECDH examples to be explicit for DHE/ECDHE (#3622)

* Modify DH/ECDH examples to be explicit for DHE/ECDHE

Also add note to DH docs that you should probably use ECDH

* give a reason

1 files changed, 12 insertions, 0 deletions

diff --git a/docs/hazmat/primitives/asymmetric/ec.rst b/docs/hazmat/primitives/asymmetric/ec.rst
index 46f2f5ac..55146175 100644
--- a/docs/hazmat/primitives/asymmetric/ec.rst
+++ b/docs/hazmat/primitives/asymmetric/ec.rst
@@ -210,13 +210,25 @@ Elliptic Curve Key Exchange algorithm
 
         >>> from cryptography.hazmat.backends import default_backend
         >>> from cryptography.hazmat.primitives.asymmetric import ec
+        >>> # Generate a private key for use in the exchange.
         >>> private_key = ec.generate_private_key(
         ...     ec.SECP384R1(), default_backend()
         ... )
+        >>> # 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.
         >>> peer_public_key = ec.generate_private_key(
         ...     ec.SECP384R1(), default_backend()
         ... ).public_key()
         >>> shared_key = private_key.exchange(ec.ECDH(), peer_public_key)
+        >>> # For the next handshake we MUST generate another private key.
+        >>> private_key_2 = ec.generate_private_key(
+        ...     ec.SECP384R1(), default_backend()
+        ... )
+        >>> peer_public_key_2 = ec.generate_private_key(
+        ...     ec.SECP384R1(), default_backend()
+        ... ).public_key()
+        >>> shared_key_2 = private_key_2.exchange(ec.ECDH(), peer_public_key_2)
 
     ECDHE (or EECDH), the ephemeral form of this exchange, is **strongly
     preferred** over simple ECDH and provides `forward secrecy`_ when used.