make the same doc changes to DH as we did for ECDH (#4631)

1 files changed, 50 insertions, 6 deletions

diff --git a/docs/hazmat/primitives/asymmetric/dh.rst b/docs/hazmat/primitives/asymmetric/dh.rst
index 04da3e40..edfe6143 100644
--- a/docs/hazmat/primitives/asymmetric/dh.rst
+++ b/docs/hazmat/primitives/asymmetric/dh.rst
@@ -23,6 +23,56 @@ derivation function. This allows mixing of additional information into the
 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 @@ present.
     ...     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