Protocols

@dataclass(frozen=True)
class DiffieHellman:
    """Elliptic Curve Diffie-Hellman key exchange.

    Protocol:
        1. Alice computes her public key: H_A = d_A · G
        2. Bob computes his public key:   H_B = d_B · G
        3. Shared secret: S = d_A · H_B = d_B · H_A = d_A · d_B · G

    Security relies on the Elliptic Curve Discrete Logarithm Problem
    (ECDLP): given G and Q = d·G, it is computationally infeasible to
    recover the private scalar *d*.

    Attributes:
        private_key: The private scalar (integer).
        curve_name:  Name of the curve (e.g. ``"secp256k1"``).
    """

    private_key: int
    curve_name: str = "secp256k1"

    # ----- derived properties -----

    @property
    def _G(self) -> Point:
        return get_generator(self.curve_name)

    @property
    def public_key(self) -> Point:
        """Compute the public key: ``private_key * G``."""
        return self.private_key * self._G

    # ----- protocol -----

    def compute_shared_secret(self, other_public_key: Point) -> Point:
        """Compute the shared secret from another party's public key.

        Args:
            other_public_key: The other party's public key point.

        Returns:
            The shared secret point ``private_key * other_public_key``.
        """
        return self.private_key * other_public_key

@dataclass(frozen=True)
class MasseyOmura:
    """Massey-Omura three-pass protocol.

    Three-pass message exchange without shared keys:

        C1 = e_A · M           (Alice encrypts)
        C2 = e_B · C1          (Bob encrypts)
        C3 = e_A⁻¹ · C2        (Alice removes her encryption)
        M  = e_B⁻¹ · C3        (Bob recovers the message)

    The protocol works because scalar multiplication on elliptic curves
    is commutative: e_A · (e_B · M) = e_B · (e_A · M).

    Requirement: gcd(private_key, n) = 1 so that the modular inverse
    e⁻¹ mod n exists.

    Attributes:
        private_key: The private scalar (integer), must be coprime with n.
        curve_name:  Name of the curve (e.g. ``"secp521r1"``).
    """

    private_key: int
    curve_name: str = "secp521r1"

    # ----- derived properties -----

    @property
    def _curve(self):
        return get_curve(self.curve_name)

    @property
    def _inverse_key(self) -> int:
        """Modular inverse of the private key mod n."""
        return pow(self.private_key, -1, self._curve.n)

    # ----- protocol -----

    def encrypt(self, point: Point) -> Point:
        """Encrypt (multiply) a point with the private key.

        Args:
            point: A curve point (message or partially encrypted).

        Returns:
            ``private_key * point``
        """
        return self.private_key * point

    def decrypt(self, point: Point) -> Point:
        """Decrypt (multiply) a point with the inverse of the private key.

        Args:
            point: A curve point to decrypt.

        Returns:
            ``private_key⁻¹ * point``
        """
        return self._inverse_key * point