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.