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

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.

>>> 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)

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.

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(default_backend())
peer_public_numbers = dh.DHPublicNumbers(y, pn)
peer_public_key = peer_public_numbers.public_key(default_backend())

See also the DHBackend API for additional functionality.

Group parameters

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

New in version 0.9.

Generate a new DH parameter group for use with backend.

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.
  • backend – A DHBackend instance.
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

New in version 0.9.

generate_private_key()

New in version 0.9.

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.
class cryptography.hazmat.primitives.asymmetric.dh.DHParametersWithSerialization

New in version 0.9.

Inherits from DHParameters.

parameter_numbers()

Return the numbers that make up this set of parameters.

Returns:A DHParameterNumbers.

Key interfaces

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

New in version 0.9.

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.
class cryptography.hazmat.primitives.asymmetric.dh.DHPrivateKeyWithSerialization

New in version 0.9.

Inherits from DHPrivateKey.

private_numbers()

Return the numbers that make up this private key.

Returns:A DHPrivateNumbers.
exchange(peer_public_key)

New in version 1.7.

Parameters:peer_public_key (DHPublicKeyWithSerialization) – The public key for the peer.
Return bytes:The agreed key. The bytes are ordered in ‘big’ endian.
class cryptography.hazmat.primitives.asymmetric.dh.DHPublicKey

New in version 0.9.

key_size

The bit length of the prime modulus.

parameters()

Return the parameters associated with this private key.

Returns:A DHParameters.
class cryptography.hazmat.primitives.asymmetric.dh.DHPublicKeyWithSerialization

New in version 0.9.

Inherits from DHPublicKey.

public_numbers()

Return the numbers that make up this public key.

Returns:A DHPublicNumbers.

Numbers

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

New 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 5.

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

New 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.

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

New 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.