Danger

This is a “Hazardous Materials” module. You should ONLY use it if you’re 100% absolutely sure that you know what you’re doing because this module is full of land mines, dragons, and dinosaurs with laser guns.

# Diffie-Hellman key exchange

Note

For security and performance reasons we suggest using `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.

## Exchange Algorithm

For most applications the `shared_key` should be passed to a key 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.

    >>> 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)
    >>> # 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',
    ... ).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',
    ... ).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 `generate_private_key()` for each `exchange()` when performing an DHE key exchange. An example of the ephemeral form:

    >>> 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)
    >>> # 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)
    >>> # Perform key derivation.
    >>> derived_key = HKDF(
    ...     algorithm=hashes.SHA256(),
    ...     length=32,
    ...     salt=None,
    ...     info=b'handshake data',
    ... ).derive(shared_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)
    >>> derived_key_2 = HKDF(
    ...     algorithm=hashes.SHA256(),
    ...     length=32,
    ...     salt=None,
    ...     info=b'handshake data',
    ... ).derive(shared_key_2)

To assemble a `DHParameters` and a `DHPublicKey` from primitive integers, you must first create the `DHParameterNumbers` and `DHPublicNumbers` objects. For example, if p, g, and y are `int` objects received from a peer:

    pn = dh.DHParameterNumbers(p, g)
    parameters = pn.parameters()
    peer_public_numbers = dh.DHPublicNumbers(y, pn)
    peer_public_key = peer_public_numbers.public_key()

## Group parameters

cryptography.hazmat.primitives.asymmetric.dh.generate_parameters(generator, key_size)

  Added in version 1.7.

  Generate a new DH parameter group.

  Parameters:

    - generator – The `int` to use as a generator. Must be 2 or 5.

    - key_size – The bit length of the prime modulus to generate.

  Returns:

    DH parameters as a new instance of `DHParameters`.

  Raises:

    ValueError – If `key_size` is not at least 512.

class cryptography.hazmat.primitives.asymmetric.dh.DHParameters

  Added in version 1.7.

  generate_private_key()

    Generate a DH private key. This method can be used to generate many new private keys from a single set of parameters.

    Returns:

      An instance of `DHPrivateKey`.

  parameter_numbers()

    Return the numbers that make up this set of parameters.

    Returns:

      A `DHParameterNumbers`.

  parameter_bytes(encoding, format)

    Added in version 2.0.

    Allows serialization of the parameters to bytes. Encoding ( `PEM` or `DER`) and format ( `PKCS3`) are chosen to define the exact serialization.

    Parameters:

      - encoding – A value from the `Encoding` enum.

      - format – A value from the `ParameterFormat` enum. At the moment only `PKCS3` is supported.

    Return bytes:

      Serialized parameters.

## Key interfaces

class cryptography.hazmat.primitives.asymmetric.dh.DHPrivateKey

  Added in version 1.7.

  key_size

    The bit length of the prime modulus.

  public_key()

    Return the public key associated with this private key.

    Returns:

      A `DHPublicKey`.

  parameters()

    Return the parameters associated with this private key.

    Returns:

      A `DHParameters`.

  exchange(peer_public_key)

    Added in version 1.7.

    Parameters:

      peer_public_key (DHPublicKey) – The public key for the peer.

    Return bytes:

      The agreed key. The bytes are ordered in ‘big’ endian.

  private_numbers()

    Return the numbers that make up this private key.

    Returns:

      A `DHPrivateNumbers`.

  private_bytes(encoding, format, encryption_algorithm)

    Added in version 1.8.

    Allows serialization of the key to bytes. Encoding ( `PEM` or `DER`), format ( `PKCS8`) and encryption algorithm (such as `BestAvailableEncryption` or `NoEncryption`) are chosen to define the exact serialization.

    Parameters:

      - encoding – A value from the `Encoding` enum.

      - format – A value from the `PrivateFormat` enum.

      - encryption_algorithm – An instance of an object conforming to the `KeySerializationEncryption` interface.

    Return bytes:

      Serialized key.

class cryptography.hazmat.primitives.asymmetric.dh.DHPublicKey

  Added in version 1.7.

  key_size

    The bit length of the prime modulus.

  parameters()

    Return the parameters associated with this private key.

    Returns:

      A `DHParameters`.

  public_numbers()

    Return the numbers that make up this public key.

    Returns:

      A `DHPublicNumbers`.

  public_bytes(encoding, format)

    Added in version 1.8.

    Allows serialization of the key to bytes. Encoding ( `PEM` or `DER`) and format ( `SubjectPublicKeyInfo`) are chosen to define the exact serialization.

    Parameters:

      - encoding – A value from the `Encoding` enum.

      - format – A value from the `PublicFormat` enum.

    Return bytes:

      Serialized key.

## Numbers

class cryptography.hazmat.primitives.asymmetric.dh.DHParameterNumbers(p, g, q=None)

  Added in version 0.8.

  The collection of integers that define a Diffie-Hellman group.

  p
    Type:

      int

    The prime modulus value.

  g
    Type:

      int

    The generator value. Must be 2 or greater.

  q

    Added in version 1.8.

    Type:

      int

    p subgroup order value.

  parameters()

    Added in version 1.7.

    Returns:

      A new instance of `DHParameters`.

    Raises:

      ValueError – If the parameters are invalid.

class cryptography.hazmat.primitives.asymmetric.dh.DHPrivateNumbers(x, public_numbers)

  Added in version 0.8.

  The collection of integers that make up a Diffie-Hellman private key.

  public_numbers
    Type:

      `DHPublicNumbers`

    The `DHPublicNumbers` which makes up the DH public key associated with this DH private key.

  x
    Type:

      int

    The private value.

  private_key()

    Added in version 1.7.

    Returns:

      A new instance of `DHPrivateKey`.

class cryptography.hazmat.primitives.asymmetric.dh.DHPublicNumbers(y, parameter_numbers)

  Added in version 0.8.

  The collection of integers that make up a Diffie-Hellman public key.

  > parameter_numbers
  >   Type:

  >     `DHParameterNumbers`

  >   The parameters for this DH group.

  y
    Type:

      int

    The public value.

  public_key()

    Added in version 1.7.

    Returns:

      A new instance of `DHPublicKey`.