Diffie-Hellman Key Exchange Scheme

This module contains a toy implementation of the Diffie-Hellman key exchange scheme.

AUTHORS:

• Vincent Macri (2024-07-30): initial version

class sage.crypto.key_exchange.diffie_hellman.DiffieHellman(p: Integer, g: Integer | IntegerMod_abstract, proof: bool = True)

Bases: KeyExchangeScheme

Create an instance of the Diffie-Hellman key exchange scheme using the given prime p and base g.

INPUT:

• p – prime integer defining the field ${\mathbf{F}}_p$ that the key exchanges will be performed over, must be at least 5

• g – base for the key exchange, (coerceable to) an element of ${\mathbf{F}}_p$ from $2$ to $p-2$

• proof – (default: True) whether to require a proof that p is prime. If False, a probabilistic test can be used for checking that p is prime. This should be set to False when using large (cryptographic size) primes, otherwise checking primality will take too long.

Warning

This is a toy implementation for educational use only! Do not use this implementation, or any cryptographic features of Sage, in any setting where security is needed!

REFERENCES:

For more information, see Section 8.1 of [PP2010].

EXAMPLES:

sage: DH = key_exchange.DiffieHellman(13, 2)
doctest:...: FutureWarning: This class/method/function is marked as experimental. It, its functionality or its interface might change without a formal deprecation.
See https://github.com/sagemath/sage/issues/37305 for details.

This is an example of a full key exchange using a cryptographically large prime. This is the prime from the 8192-bit MODP group in RFC 3526 (see [KK2003]):

sage: p = 2^8192 - 2^8128 - 1 + 2^64 * (round(2^8062 * pi) + 4743158)
sage: DH = key_exchange.DiffieHellman(p, 2, proof=False)
sage: alice_sk = DH.generate_secret_key()
sage: alice_pk = DH.generate_public_key(alice_sk)
sage: bob_sk = DH.generate_secret_key()
sage: bob_pk = DH.generate_public_key(bob_sk)
sage: alice_shared_secret = DH.compute_shared_secret(bob_pk, alice_sk)
sage: bob_shared_secret = DH.compute_shared_secret(alice_pk, bob_sk)
sage: alice_shared_secret == bob_shared_secret
True

compute_shared_secret(pk, sk)

Compute the shared secret using the given public key and secret keys.

INPUT:

• pk – public key

• sk – secret key

EXAMPLES:

sage: DH = key_exchange.DiffieHellman(17, 3)
sage: DH.compute_shared_secret(13, 11)
4

field()

Return the field this DiffieHellman instance is working over.

EXAMPLES:

sage: DH = key_exchange.DiffieHellman(5, 2)
sage: DH.field()
Finite Field of size 5

generate_public_key(secret_key)

Generate a Diffie-Hellman public key using the given secret key.

INPUT:

• secret_key – the secret key to generate the public key with

EXAMPLES:

sage: DH = key_exchange.DiffieHellman(13, 2)
sage: DH.generate_public_key(4)
3

generate_secret_key()

Generate a random Diffie-Hellman secret key.

generator()

Return the generator g for this DiffieHellman instance.

EXAMPLES:

sage: DH = key_exchange.DiffieHellman(7, 3)
sage: DH.generator()
3

parameters()

Get the parameters (p, g) for this DiffieHellman instance.

EXAMPLES:

sage: DH = key_exchange.DiffieHellman(7, 3)
sage: DH.parameters()
(7, 3)

prime()

Return the prime p for this DiffieHellman instance.

EXAMPLES:

sage: DH = key_exchange.DiffieHellman(7, 3)
sage: DH.prime()
7

subgroup_size()

Calculates the size of the subgroup of ${\mathbf{F}}_p$ generated by self.generator().

EXAMPLES:

This is an example of a DiffieHellman instance where the subgroup size is $(p-1)/2$:

sage: DH = key_exchange.DiffieHellman(47, 2)
sage: DH.subgroup_size()
23

This is an example of a DiffieHellman instance where the subgroup size is $p-1$:

sage: DH = key_exchange.DiffieHellman(47, 5)
sage: DH.subgroup_size()
46