diff options
| -rw-r--r-- | docs/hazmat/primitives/asymmetric/dh.rst | 23 | ||||
| -rw-r--r-- | docs/hazmat/primitives/asymmetric/ec.rst | 12 |
2 files changed, 32 insertions, 3 deletions
diff --git a/docs/hazmat/primitives/asymmetric/dh.rst b/docs/hazmat/primitives/asymmetric/dh.rst index 58ff663d..f4cae1c3 100644 --- a/docs/hazmat/primitives/asymmetric/dh.rst +++ b/docs/hazmat/primitives/asymmetric/dh.rst @@ -5,6 +5,11 @@ Diffie-Hellman key exchange .. 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 @@ derivation function. >>> 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 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. |