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 \(\GF{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 \(\GF{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

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.

Python

>>> from sage.all import *
>>> DH = key_exchange.DiffieHellman(Integer(13), Integer(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.

Sage Live

DH = key_exchange.DiffieHellman(13, 2)

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

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

Python

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

Sage Live

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

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

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

Python

>>> from sage.all import *
>>> DH = key_exchange.DiffieHellman(Integer(17), Integer(3))
>>> DH.compute_shared_secret(Integer(13), Integer(11))
4

Sage Live

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

field()

Return the field this DiffieHellman instance is working over.

EXAMPLES:

Sage

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

Python

>>> from sage.all import *
>>> DH = key_exchange.DiffieHellman(Integer(5), Integer(2))
>>> DH.field()
Finite Field of size 5

Sage Live

DH = key_exchange.DiffieHellman(5, 2)
DH.field()

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

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

Python

>>> from sage.all import *
>>> DH = key_exchange.DiffieHellman(Integer(13), Integer(2))
>>> DH.generate_public_key(Integer(4))
3

Sage Live

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

generate_secret_key()

Generate a random Diffie-Hellman secret key.

generator()

Return the generator g for this DiffieHellman instance.

EXAMPLES:

Sage

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

Python

>>> from sage.all import *
>>> DH = key_exchange.DiffieHellman(Integer(7), Integer(3))
>>> DH.generator()
3

Sage Live

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

parameters()

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

EXAMPLES:

Sage

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

Python

>>> from sage.all import *
>>> DH = key_exchange.DiffieHellman(Integer(7), Integer(3))
>>> DH.parameters()
(7, 3)

Sage Live

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

prime()

Return the prime p for this DiffieHellman instance.

EXAMPLES:

Sage

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

Python

>>> from sage.all import *
>>> DH = key_exchange.DiffieHellman(Integer(7), Integer(3))
>>> DH.prime()
7

Sage Live

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

subgroup_size()

Calculates the size of the subgroup of \(\GF{p}\) generated by self.generator().

EXAMPLES:

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

Sage

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

Python

>>> from sage.all import *
>>> DH = key_exchange.DiffieHellman(Integer(47), Integer(2))
>>> DH.subgroup_size()
23

Sage Live

DH = key_exchange.DiffieHellman(47, 2)
DH.subgroup_size()

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

Sage

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

Python

>>> from sage.all import *
>>> DH = key_exchange.DiffieHellman(Integer(47), Integer(5))
>>> DH.subgroup_size()
46

Sage Live

DH = key_exchange.DiffieHellman(47, 5)
DH.subgroup_size()

Make live