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
diff --git a/docs/hazmat/primitives/asymmetric/dh.rst b/docs/hazmat/primitives/asymmetric/dh.rst
index 58ff663..f4cae1c 100644
--- a/docs/hazmat/primitives/asymmetric/dh.rst
+++ b/docs/hazmat/primitives/asymmetric/dh.rst
@@ -5,6 +5,11 @@
.. currentmodule:: cryptography.hazmat.primitives.asymmetric.dh
+.. note::
+ For security and performance reasons we suggest using
+ :class:`~cryptography.hazmat.primitives.asymmetric.ec.ECDH` instead of DH
+ where possible.
+
`Diffie-Hellman key exchange`_ (D–H) is a method that allows two parties
to jointly agree on a shared secret using an insecure channel.
@@ -20,16 +25,28 @@
>>> from cryptography.hazmat.backends import default_backend
>>> from cryptography.hazmat.primitives.asymmetric import dh
+ >>> # 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.
>>> private_key = parameters.generate_private_key()
+ >>> # 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. Note that in a DH handshake both peers
+ >>> # must agree on a common set of parameters.
>>> peer_public_key = parameters.generate_private_key().public_key()
>>> shared_key = private_key.exchange(peer_public_key)
+ >>> # For the next handshake we MUST generate another private key, but
+ >>> # we can reuse the parameters.
+ >>> private_key_2 = parameters.generate_private_key()
+ >>> peer_public_key_2 = parameters.generate_private_key().public_key()
+ >>> shared_key_2 = private_key_2.exchange(peer_public_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.
+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
diff --git a/docs/hazmat/primitives/asymmetric/ec.rst b/docs/hazmat/primitives/asymmetric/ec.rst
index 46f2f5a..5514617 100644
--- a/docs/hazmat/primitives/asymmetric/ec.rst
+++ b/docs/hazmat/primitives/asymmetric/ec.rst
@@ -210,13 +210,25 @@
>>> 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.