x25519.h — X25519 Diffie-Hellman

Elliptic-curve algorithms are a newer construction preferred over RSA for key exchange. Their security rests on the elliptic curve discrete logarithm problem (ECDLP): given a public point Q = k·G on the curve (where G is the well-known base point and k is a private scalar), recovering k is computationally infeasible. Unlike integer factorization, no known sub-exponential algorithm exists for ECDLP on well-chosen curves, which is why a 256-bit ECDHE key provides roughly the same strength as a 2048-bit RSA key with significantly faster math. TLS 1.3 removes RSA key exchange entirely, requiring elliptic-curve Diffie-Hellman instead.

X25519 is an elliptic-curve Diffie-Hellman function over Curve25519, a Montgomery curve (By² = x³ + Ax² + x). Both X25519 and P-256 are mandatory-to-implement in TLS 1.3; X25519 was chosen as the primary algorithm here because the Montgomery ladder — the scalar multiplication algorithm Montgomery curves use — runs in constant time and is amenable to the kind of tight assembly optimization this platform requires. P-256 is not yet implemented, but is planned.

Private keys are automatically clamped per RFC 7748 — no pre-clamping needed.

Note

X25519 is notably slow on the eZ80. Use the yield_fn callback to keep your UI responsive during the computation.

Key Operations

bool tls_x25519_secret(uint8_t shared_secret[32], const uint8_t my_private[32], const uint8_t their_public[32], void (*yield_fn)(void*), void *yield_data)

Compute an X25519 shared secret from a private scalar and a peer’s public key (scalar multiplication).

Parameters:
  • shared_secret – Output shared secret (32 bytes, little-endian).

  • my_private – Our private scalar (32 bytes; clamped internally).

  • their_public – Peer’s public key u-coordinate (32 bytes).

  • yield_fn – Optional callback invoked periodically during computation. Pass NULL if not needed.

  • yield_data – Context pointer passed to yield_fn. Pass NULL if not needed.

Returns:

true on success, false on low-order point input (RFC 7748 §6 check).

bool tls_x25519_publickey(uint8_t public_key[32], const uint8_t private_key[32], void (*yield_fn)(void*), void *yield_data)

Derive an X25519 public key from a private scalar (multiply by the Curve25519 base point).

Parameters:
  • public_key – Output public key u-coordinate (32 bytes).

  • private_key – Input private scalar (32 bytes; clamped internally).

  • yield_fn – Optional yield callback. Pass NULL if not needed.

  • yield_data – Context pointer for yield_fn. Pass NULL if not needed.

Returns:

true on success, false on error.

Examples

uint8_t my_private[32];    /* 32-byte private scalar */
uint8_t their_public[32];  /* peer's public key (u-coordinate) */
uint8_t shared_secret[32];
uint8_t my_public[32];

tls_x25519_publickey(my_public, my_private, NULL, NULL);
tls_x25519_secret(shared_secret, my_private, their_public, NULL, NULL);