change ECDH documentation to show both classical ECDH and ECDHE (#4530)
diff --git a/docs/hazmat/primitives/asymmetric/ec.rst b/docs/hazmat/primitives/asymmetric/ec.rst
index 8d03a09..e36a5a1 100644
--- a/docs/hazmat/primitives/asymmetric/ec.rst
+++ b/docs/hazmat/primitives/asymmetric/ec.rst
@@ -238,6 +238,58 @@
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 @@
... 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
---------------