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.
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.
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
>>> # Generate some parameters. These can be reused.
>>> parameters = dh.generate_parameters(generator=2, key_size=2048,
... backend=default_backend())
>>> # 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)
>>> # 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)
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. This is demonstrated in the previous example.
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.
New in version 0.9.
Generate a new DH parameter group for use with backend.
Parameters: |
|
---|---|
Returns: | DH parameters as a new instance of DHParameters. |
Raises ValueError: | |
If key_size is not at least 512. |
New in version 0.9.
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. |
---|
New in version 0.9.
Inherits from DHParameters.
Return the numbers that make up this set of parameters.
Returns: | A DHParameterNumbers. |
---|
New in version 0.9.
The bit length of the prime modulus.
Return the public key associated with this private key.
Returns: | A DHPublicKey. |
---|
Return the parameters associated with this private key.
Returns: | A DHParameters. |
---|
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. |
New in version 0.9.
Inherits from DHPrivateKey.
Return the numbers that make up this private key.
Returns: | A DHPrivateNumbers. |
---|
New 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: |
|
---|---|
Return bytes: | Serialized key. |
New in version 0.9.
The bit length of the prime modulus.
Return the parameters associated with this private key.
Returns: | A DHParameters. |
---|
New in version 0.9.
Inherits from DHPublicKey.
Return the numbers that make up this public key.
Returns: | A DHPublicNumbers. |
---|
New 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: |
|
---|---|
Return bytes: | Serialized key. |
New in version 0.8.
The collection of integers that define a Diffie-Hellman group.
Type: | int |
---|
The prime modulus value.
Type: | int |
---|
The generator value. Must be 2 or 5 (Unless q is given).
New in version 1.8.
Type: | int |
---|
p subgroup order value.
New in version 0.8.
The collection of integers that make up a Diffie-Hellman private key.
Type: | DHPublicNumbers |
---|
The DHPublicNumbers which makes up the DH public key associated with this DH private key.
Type: | int |
---|
The private value.
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.
Type: | int |
---|
The public value.