diff options
Diffstat (limited to 'docs/hazmat/primitives/asymmetric')
| -rw-r--r-- | docs/hazmat/primitives/asymmetric/dh.rst | 163 |
1 files changed, 120 insertions, 43 deletions
diff --git a/docs/hazmat/primitives/asymmetric/dh.rst b/docs/hazmat/primitives/asymmetric/dh.rst index 8cb68280..463df90a 100644 --- a/docs/hazmat/primitives/asymmetric/dh.rst +++ b/docs/hazmat/primitives/asymmetric/dh.rst @@ -6,69 +6,70 @@ Diffie-Hellman key exchange .. currentmodule:: cryptography.hazmat.primitives.asymmetric.dh -Numbers -~~~~~~~ - -.. class:: DHPrivateNumbers(x, public_numbers) - - .. versionadded:: 0.8 - - The collection of integers that make up a Diffie-Hellman private key. - - .. attribute:: public_numbers - - :type: :class:`~cryptography.hazmat.primitives.asymmetric.dh.DHPublicNumbers` - - The :class:`DHPublicNumbers` which makes up the DH public - key associated with this DH private key. - - .. attribute:: x - - :type: int - - The private value. +`Diffie-Hellman key exchange`_ (D–H) is a method that allows two parties +to jointly agree on a shared secret using an insecure channel. -.. class:: DHPublicNumbers(y, parameter_numbers) - - .. versionadded:: 0.8 +Exchange Algorithm +~~~~~~~~~~~~~~~~~~ - The collection of integers that make up a Diffie-Hellman public key. +For most applications the ``shared_key`` should be passed to a key +derivation function. - .. attribute:: parameter_numbers - - :type: :class:`~cryptography.hazmat.primitives.asymmetric.dh.DHParameterNumbers` +.. code-block:: pycon - The parameters for this DH group. + >>> from cryptography.hazmat.backends import default_backend + >>> from cryptography.hazmat.primitives.asymmetric import dh + >>> parameters = dh.generate_parameters(generator=2, key_size=2048, + ... backend=default_backend()) + >>> private_key = parameters.generate_private_key() + >>> peer_public_key = parameters.generate_private_key().public_key() + >>> shared_key = private_key.exchange(peer_public_key) - .. attribute:: y +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:`~DHPrivateKeyWithSerialization.exchange` when performing an DHE key +exchange. - :type: int +To assemble a :class:`~DHParameters` and a :class:`~DHPublicKey` from +primitive integers, you must first create the +:class:`~DHParameterNumbers` and :class:`~DHPublicNumbers` objects. For +example if **p**, **g**, and **y** are :class:`int` objects received from a +peer:: - The public value. + pn = dh.DHParameterNumbers(p, g) + parameters = pn.parameters(default_backend()) + peer_public_numbers = dh.DHPublicNumbers(y, pn) + peer_public_key = peer_public_numbers.public_key(default_backend()) -.. class:: DHParameterNumbers(p, g) +See also the :class:`~cryptography.hazmat.backends.interfaces.DHBackend` +API for additional functionality. - .. versionadded:: 0.8 +Group parameters +~~~~~~~~~~~~~~~~ - The collection of integers that define a Diffie-Hellman group. +.. function:: generate_parameters(generator, key_size, backend) - .. attribute:: p + .. versionadded:: 0.9 - :type: int + Generate a new DH parameter group for use with ``backend``. - The prime modulus value. + :param generator: The :class:`int` to use as a generator. Must be + 2 or 5. - .. attribute:: g + :param key_size: The bit length of the prime modulus to generate. - :type: int + :param backend: A + :class:`~cryptography.hazmat.backends.interfaces.DHBackend` + instance. - The generator value. + :returns: DH parameters as a new instance of + :class:`~cryptography.hazmat.primitives.asymmetric.dh.DHParameters`. + :raises ValueError: If ``key_size`` is not at least 512. -Key interfaces -~~~~~~~~~~~~~~ .. class:: DHParameters @@ -99,6 +100,9 @@ Key interfaces :return: A :class:`~cryptography.hazmat.primitives.asymmetric.dh.DHParameterNumbers`. +Key interfaces +~~~~~~~~~~~~~~ + .. class:: DHPrivateKey .. versionadded:: 0.9 @@ -132,6 +136,15 @@ Key interfaces :return: A :class:`~cryptography.hazmat.primitives.asymmetric.dh.DHPrivateNumbers`. + .. method:: exchange(peer_public_key) + + .. versionadded:: 1.7 + + :param DHPublicKeyWithSerialization peer_public_key: The public key for the + peer. + + :return bytes: The agreed key. The bytes are ordered in 'big' endian. + .. class:: DHPublicKey @@ -159,3 +172,67 @@ Key interfaces Return the numbers that make up this public key. :return: A :class:`~cryptography.hazmat.primitives.asymmetric.dh.DHPublicNumbers`. + + +Numbers +~~~~~~~ + +.. class:: DHParameterNumbers(p, g) + + .. versionadded:: 0.8 + + The collection of integers that define a Diffie-Hellman group. + + .. attribute:: p + + :type: int + + The prime modulus value. + + .. attribute:: g + + :type: int + + The generator value. Must be 2 or 5. + +.. class:: DHPrivateNumbers(x, public_numbers) + + .. versionadded:: 0.8 + + The collection of integers that make up a Diffie-Hellman private key. + + .. attribute:: public_numbers + + :type: :class:`~cryptography.hazmat.primitives.asymmetric.dh.DHPublicNumbers` + + The :class:`DHPublicNumbers` which makes up the DH public + key associated with this DH private key. + + .. attribute:: x + + :type: int + + The private value. + + +.. class:: DHPublicNumbers(y, parameter_numbers) + + .. versionadded:: 0.8 + + The collection of integers that make up a Diffie-Hellman public key. + + .. attribute:: parameter_numbers + + :type: :class:`~cryptography.hazmat.primitives.asymmetric.dh.DHParameterNumbers` + + The parameters for this DH group. + + .. attribute:: y + + :type: int + + The public value. + + +.. _`Diffie-Hellman key exchange`: https://en.wikipedia.org/wiki/Diffie%E2%80%93Hellman_key_exchange +.. _`forward secrecy`: https://en.wikipedia.org/wiki/Forward_secrecy |