diff options
Diffstat (limited to 'docs')
| -rw-r--r-- | docs/development/test-vectors.rst | 8 | ||||
| -rw-r--r-- | docs/hazmat/backends/interfaces.rst | 8 | ||||
| -rw-r--r-- | docs/hazmat/primitives/asymmetric/dh.rst | 163 | ||||
| -rw-r--r-- | docs/spelling_wordlist.txt | 1 |
4 files changed, 135 insertions, 45 deletions
diff --git a/docs/development/test-vectors.rst b/docs/development/test-vectors.rst index 49c5ac23..fb72240d 100644 --- a/docs/development/test-vectors.rst +++ b/docs/development/test-vectors.rst @@ -91,6 +91,13 @@ Key exchange * ``vectors/cryptography_vectors/asymmetric/DH/RFC5114.txt`` contains Diffie-Hellman examples from appendix A.1, A.2 and A.3 of :rfc:`5114`. +* ``vectors/cryptography_vectors/asymmetric/DH/vec.txt`` contains + Diffie-Hellman examples from `botan`_. + +* ``vectors/cryptography_vectors/asymmetric/DH/bad_exchange.txt`` contains + Diffie-Hellman vector pairs that were generated using OpenSSL + DH_generate_parameters_ex and DH_generate_key. + X.509 ~~~~~ @@ -463,3 +470,4 @@ header format (substituting the correct information): .. _`Russian CA`: https://e-trust.gosuslugi.ru/MainCA .. _`test/evptests.txt`: https://github.com/openssl/openssl/blob/2d0b44126763f989a4cbffbffe9d0c7518158bb7/test/evptests.txt .. _`unknown signature OID`: https://bugzilla.mozilla.org/show_bug.cgi?id=405966 +.. _`botan`: https://github.com/randombit/botan/blob/57789bdfc55061002b2727d0b32587612829a37c/src/tests/data/pubkey/dh.vec diff --git a/docs/hazmat/backends/interfaces.rst b/docs/hazmat/backends/interfaces.rst index 42e07d39..87fc6ab7 100644 --- a/docs/hazmat/backends/interfaces.rst +++ b/docs/hazmat/backends/interfaces.rst @@ -600,7 +600,9 @@ A specific ``backend`` may provide one or more of these interfaces. A backend with methods for doing Diffie-Hellman key exchange. - .. method:: generate_dh_parameters(key_size) + .. method:: generate_dh_parameters(generator, key_size) + + :param int generator: The generator to use. Often 2 or 5. :param int key_size: The bit length of the prime modulus to generate. @@ -617,7 +619,9 @@ A specific ``backend`` may provide one or more of these interfaces. :return: A new instance of :class:`~cryptography.hazmat.primitives.asymmetric.dh.DHPrivateKey`. - .. method:: generate_dh_private_key_and_parameters(self, key_size) + .. method:: generate_dh_private_key_and_parameters(generator, key_size) + + :param int generator: The generator to use. Often 2 or 5. :param int key_size: The bit length of the prime modulus to generate. 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 diff --git a/docs/spelling_wordlist.txt b/docs/spelling_wordlist.txt index 5efbbdcd..186b7eeb 100644 --- a/docs/spelling_wordlist.txt +++ b/docs/spelling_wordlist.txt @@ -32,6 +32,7 @@ Django Docstrings El Encodings +endian Fernet fernet FIPS |