Base Classes for Key Exchange Schemes

This module contains base classes for key exchange schemes. The classes defined in this module should not be initialized directly. It is the responsibility of child classes to implement specific key exchange schemes.

A key exchange protocol establishes a shared secret value between two parties, Alice and Bob. Either party is able to initiate the key exchange, in the sense that either party can compute the shared secret using only their own private key and the other party’s public key.

AUTHORS:

• Brian Heckel (2025-11-26): initial version

• Vincent Macri (2025-12-18): add named_parameter_set method

class sage.crypto.public_key.key_exchange.key_exchange_base.CommutativeKeyExchangeBase

Bases: KeyExchangeBase

A base class for key exchange schemes such as Diffie-Hellman where Alice and Bob perform the same computations for generating public/secret keys and the shared secret key.

Implementers of this class only need to implement the abstract methods defined in CommutativeKeyExchangeBase and do not need to implement method defined in KeyExchangeBase. This class is for convenience to reduce code duplication when implementing key exchange schemes where Alice and Bob perform the same calculations.

abstractmethod compute_shared_secret(secret_key, public_key)

Generate the computed shared secret.

INPUT:

• secret_key – A secret key that has been chosen beforehand

• public_key – A public key that has been sent to this party through

  an insecure channel

OUTPUT:

A shared secret key between the two parties

abstractmethod public_key(secret_key)

Generate a public key for the secret key that you have chosen.

INPUT:

• secret_key – A secret key that has been chosen beforehand

abstractmethod secret_key()

Generate a secret key for the key exchange.

class sage.crypto.public_key.key_exchange.key_exchange_base.KeyExchangeBase

Bases: SageObject

A base class for key exchange schemes.

Implementers of this class must implement all abstract methods defined in KeyExchangeBase().

If all alice methods are the same as bob methods, then the CommutativeKeyExchangeBase might be easier to implement.

abstractmethod alice_compute_shared_secret(alice_secret_key, bob_public_key)

Compute Alice’s shared secret.

INPUT:

• alice_secret_key – Alice’s secret key that is kept secret from all parties

• bob_public_key – Bob’s public key that has been sent to Alice

OUTPUT:

A secret key that is shared between Alice and Bob

alice_key_pair()

Generate a valid (secret key, public key) key pair for Alice.

OUTPUT:

A 2-tuple (secret_key, public_key) which is Alice’s secret and public keys

abstractmethod alice_public_key(alice_secret_key)

Generate a valid public key for Alice.

INPUT:

• alice_secret_key – Alice’s secret key that will be used to generate

  the public key

OUTPUT:

A valid public key that will be sent to Bob

abstractmethod alice_secret_key()

Generate a valid secret key for Alice.

abstractmethod bob_compute_shared_secret(bob_secret_key, alice_public_key)

Compute Bob’s shared secret.

INPUT:

• bob_secret_key – Bob’s secret key that is kept secret from all parties

• alice_public_key – Alice’s public key that has been sent to Bob

OUTPUT:

The secret key that is shared between Alice and Bob

bob_key_pair()

Generate a valid (secret key, public key) key pair for Bob.

OUTPUT:

A 2-tuple (secret_key, public_key) which is Bob’s secret and public keys

abstractmethod bob_public_key(bob_secret_key)

Generate a valid public key for Bob.

INPUT:

• bob_secret_key – Bob’s secret key that will be used to generate

  the public key

OUTPUT:

A valid public key that will be sent to Alice

abstractmethod bob_secret_key()

Generate a valid secret key for Bob.

do_key_exchange()

Do a full key exchange and returns all public keys, secret keys, and the computed shared secret between Alice and Bob. Raises an AssertException if Alice and Bob do not compute the same shared secret.

OUTPUT:

A 5-tuple (alice_secret_key, alice_public_key, bob_secret_key, bob_public_key, shared_secret)

classmethod named_parameter_set(name)

Convenience method to easily construct particular instances of a key exchange scheme for actual parameter sets that are used in practice and have names. Implementations may also wish to implement a parameter set named ‘toy’ of a size that is just large enough to be non-trivial but is nowhere near cryptographic size. Implementations may also wish to set a custom name on the key exchange instance before returning it.

Sage library implementations of key exchange schemes should define a ‘toy’ implementation and use it for most tests to reduce testing time.

abstractmethod parameters()

A tuple of the public parameters of the key exchange.

parameters() should a tuple of useful attributes of the instance which are sufficient to define the parameter set of the key exchange scheme that the instance represents. For some implementations this may simply be the parameters passed to __init__ when the object was constructed. For some implementations we may wish to return additional information for convenience. For example, a key exchange scheme that works over an elliptic curve over a finite field may wish to return the characteristic of the finite field in addition to the elliptic curve, even though the finite field can be accessed via methods on elliptic curve objects.

The default implementations of _eq_ and __hash__ for KeyExchangeBase are implementing using parameters(). Hence two key exchange instances a and b compare as equal if and only if a.parameters() == b.parameters(). Similarly, a key exchange instance a is hashable if and only if a.parameters() is hashable. This is a reasonable default that should work for most key exchange schemes, but user classes can override the _eq_ and __hash__ methods if this is not desirable.

OUTPUT:

A tuple of public parameters used for the key exchange