Diffie-Hellman Key Exchange

Diffie–Hellman is a key exchange protocol that allows two parties to securely derive a shared secret over an insecure channel. The security relies on the difficulty of computing discrete logarithms in a finite group. DH is commonly used to establish symmetric session keys in protocols like TLS.

class pycrypt.asymmetric.DHParameters(p, g, q=None)[source]

Bases: object

Represents Diffie–Hellman (DH) group parameters.

This class is aliased under the name DH for easier access.

This class defines the mathematical parameters used for the Diffie–Hellman key exchange: the large prime modulus p, the generator g, and optionally the subgroup order q. These parameters define the finite cyclic group in which all DH operations occur.

Example

>>> params = DHParameters.generate_parameters(key_size=2048)
>>> priv = params.generate_private_key()
>>> pub = priv.public_key()

Parameters:

p (int)
g (int)
q (int | None)

p: int: The large prime modulus.

g: int: The generator of the subgroup.

q: int | None: Optional subgroup order, if known.

classmethod generate_parameters(key_size=2048)[source]

Generate standardized Diffie–Hellman parameters.

Uses predefined MODP groups from pycrypt.asymmetric.dh.groups.

Parameters:: key_size (Literal[2048, 3072, 4096, 6144, 8192], optional) – The bit size of the DH group to use. Defaults to 2048.
Returns:: The generated DH parameter set.
Return type:: DHParameters
Raises:: ValueError – If key_size is not one of the supported group sizes.

generate_private_key(bits=None)[source]

Generate a private key for this parameter set.

Parameters:: bits (int | None, optional) – Bit length of the private key. If None, a secure default based on the parameter size is used.
Returns:: The generated private key instance.
Return type:: DHPrivateKey

class pycrypt.asymmetric.DHPrivateKey(x, params)[source]

Bases: object

Represents a Diffie–Hellman private key and key exchange operations.

Parameters:

x (int)
params (DHParameters)

public_key()[source]

Compute the public key corresponding to this private key.

Returns:: The derived public key.
Return type:: DHPublicKey

exchange(peer_public, *, info=b'', length=32, salt=None)[source]

Perform a key exchange with a peer and derive a shared secret.

Uses HKDF as a key derivation function on the raw shared secret.

Parameters:

peer_public (DHPublicKey) – The peer’s public key.
info (bytes, optional) – Context/application-specific data for HKDF.
length (int, optional) – Desired length of the derived key in bytes.
salt (bytes | None, optional) – Optional salt for HKDF.

Returns:

The derived shared secret.

Return type:

bytes

zeroize()[source]

Attempt to securely erase the private scalar from memory.

Return type:: None

export_key()[source]

Exports the DH private key in PEM format.

Returns:: The PEM-encoded DH private key.
Return type:: str

classmethod import_key(pem)[source]

Imports a DH private key from a PEM-formatted string.

Parameters:: pem (str) – The PEM-encoded DH private key.
Returns:: A DHPrivateKey instance initialized with the imported key.
Return type:: DHPrivateKey
Raises:: ValueError – If the PEM cannot be parsed as a valid DH private key.

class pycrypt.asymmetric.DHPublicKey(y, params)[source]

Bases: object

Represents a Diffie–Hellman public key.

Parameters:

y (int)
params (DHParameters)

y: int: The computed public key value.

params: DHParameters: The DH parameter set used to generate this key.

to_bytes()[source]

Serialize the public key to bytes.

Returns:: The big-endian representation of the public key value.
Return type:: bytes

classmethod from_bytes(b, params)[source]

Deserialize a public key from bytes.

Parameters:

b (bytes) – The byte sequence representing the public key.
params (DHParameters) – The DH parameter set associated with this key.

Returns:

The reconstructed public key object.

Return type:

DHPublicKey

export_key()[source]

Exports the DH public key in PEM format.

Returns:: The PEM-encoded DH public key.
Return type:: str

classmethod import_key(pem)[source]

Imports a DH public key from a PEM-formatted string.

Parameters:: pem (str) – The PEM-encoded DH public key.
Returns:: A DHPublicKey instance initialized with the imported key.
Return type:: DHPublicKey
Raises:: ValueError – If the PEM cannot be parsed as a valid DH public key.