make the same doc changes to DH as we did for ECDH (#4631)
diff --git a/docs/hazmat/primitives/asymmetric/dh.rst b/docs/hazmat/primitives/asymmetric/dh.rst
index 04da3e4..edfe614 100644
--- a/docs/hazmat/primitives/asymmetric/dh.rst
+++ b/docs/hazmat/primitives/asymmetric/dh.rst
@@ -23,6 +23,56 @@
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.
+
+.. code-block:: pycon
+
+ >>> from cryptography.hazmat.backends import default_backend
+ >>> from cryptography.hazmat.primitives import hashes
+ >>> from cryptography.hazmat.primitives.asymmetric import dh
+ >>> from cryptography.hazmat.primitives.kdf.hkdf import HKDF
+ >>> # Generate some parameters. These can be reused.
+ >>> parameters = dh.generate_parameters(generator=2, key_size=2048,
+ ... backend=default_backend())
+ >>> # Generate a private key for use in the exchange.
+ >>> server_private_key = parameters.generate_private_key()
+ >>> # In a real handshake the peer is a remote client. For this
+ >>> # example we'll generate another local private key though. Note that in
+ >>> # a DH handshake both peers must agree on a common set of parameters.
+ >>> peer_private_key = parameters.generate_private_key()
+ >>> shared_key = server_private_key.exchange(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(
+ ... server_private_key.public_key()
+ ... )
+ >>> 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
+
+DHE (or EDH), the ephemeral form of this exchange, is **strongly
+preferred** over simple DH and provides `forward secrecy`_ when used. You must
+generate a new private key using :func:`~DHParameters.generate_private_key` for
+each :meth:`~DHPrivateKey.exchange` when performing an DHE key exchange. An
+example of the ephemeral form:
+
.. code-block:: pycon
>>> from cryptography.hazmat.backends import default_backend
@@ -61,12 +111,6 @@
... backend=default_backend()
... ).derive(shared_key_2)
-DHE (or EDH), the ephemeral form of this exchange, is **strongly
-preferred** over simple DH and provides `forward secrecy`_ when used. You must
-generate a new private key using :func:`~DHParameters.generate_private_key` for
-each :meth:`~DHPrivateKey.exchange` when performing an DHE key exchange. This
-is demonstrated in the previous example.
-
To assemble a :class:`~DHParameters` and a :class:`~DHPublicKey` from
primitive integers, you must first create the
:class:`~DHParameterNumbers` and :class:`~DHPublicNumbers` objects. For