====== std.crypto.x25519 ======

X25519 Diffie-Hellman Schlüsselaustausch auf Curve25519 (RFC 7748). Implementiert die Montgomery-Leiter in constant-time — kein Timing-Side-Channel auf geheimen Skalaren. Grundlage für [[lyx_-_programmiersprache:units:crypto:pqc:hybrid|std.crypto.pqc.hybrid]] (X25519 + ML-KEM-768).

<code lyx>
import std.crypto.x25519;
</code>

→ [[lyx_-_programmiersprache:units:crypto|std.crypto]] · [[lyx_-_programmiersprache:units|Standard Library]]

----

===== Konstanten =====

^ Konstante ^ Wert ^ Bedeutung ^
| ''X25519_PK'' | 32 | Public-Key-Länge in Bytes |
| ''X25519_SK'' | 32 | Private-Key-Länge in Bytes |
| ''X25519_SS'' | 32 | Shared-Secret-Länge in Bytes |

----

===== Funktionen =====

^ Funktion ^ Beschreibung ^
| ''X25519KeyGen(seed, pk, sk)'' | Leitet pk (32B) und sk (32B) aus einem 32-Byte-Seed ab. sk = seed (nach Clamp), pk = X25519(sk, 9) |
| ''X25519SharedSecret(sk, pk, ss)'' | Berechnet ss = X25519(sk, pk) — ECDH-Shared-Secret aus eigenem sk und dem Public-Key der Gegenseite |
| ''X25519(out, k, u)'' | Low-Level: Skalarmultiplikation auf Curve25519. k = 32-Byte-Skalar, u = 32-Byte-u-Koordinate |

Puffer-Anforderungen: alle Puffer exakt 32 Bytes.

----

===== Verwendungsbeispiel =====

**ECDH-Schlüsselaustausch (zwei Parteien):**

<code lyx>
import std.crypto.x25519;
import std.crypto.rand;
import std.alloc;

fn main(): int64 {
  // Alice: Schlüsselpaar erzeugen
  var alice_seed: int64 := alloc(32);
  var alice_pk:   int64 := alloc(X25519_PK);
  var alice_sk:   int64 := alloc(X25519_SK);
  RandBytesExact(alice_seed, 32);
  X25519KeyGen(alice_seed, alice_pk, alice_sk);

  // Bob: Schlüsselpaar erzeugen
  var bob_seed: int64 := alloc(32);
  var bob_pk:   int64 := alloc(X25519_PK);
  var bob_sk:   int64 := alloc(X25519_SK);
  RandBytesExact(bob_seed, 32);
  X25519KeyGen(bob_seed, bob_pk, bob_sk);

  // Alice berechnet Shared Secret mit Bobs Public Key:
  var alice_ss: int64 := alloc(X25519_SS);
  X25519SharedSecret(alice_sk, bob_pk, alice_ss);

  // Bob berechnet Shared Secret mit Alices Public Key:
  var bob_ss: int64 := alloc(X25519_SS);
  X25519SharedSecret(bob_sk, alice_pk, bob_ss);

  // alice_ss == bob_ss (identische 32 Bytes)

  free(alice_seed, 32); free(alice_pk, 32); free(alice_sk, 32); free(alice_ss, 32);
  free(bob_seed, 32);   free(bob_pk, 32);   free(bob_sk, 32);   free(bob_ss, 32);
  return 0;
}
</code>

----

===== Mathematischer Hintergrund =====

  Feld: GF(2²⁵⁵ − 19),  p = 2²⁵⁵ − 19
  Darstellung: 10 int64-Limbs, alternierend 26/25 Bit
  Skalarmultiplikation: Montgomery-Leiter (RFC 7748 §5)

**Clamp-Prozedur** (wird von X25519KeyGen automatisch angewendet):
  sk[0]  &= 248   (Bits 0–2 = 0)
  sk[31] &= 127   (Bit 255 = 0)
  sk[31] |= 64    (Bit 254 = 1)

Constant-Time-Garantie: Die Montgomery-Leiter führt bei jedem Bit eine CTSelect-Operation durch — kein Branch auf geheimem Skalar.

----

===== Sicherheitshinweise =====

  * ''seed'' muss kryptographisch sicher sein → ''RandBytesExact'' aus ''std.crypto.rand''
  * Shared Secret nach Verwendung löschen → ''dadqZeroize'' oder ''SecureZero'' aus ''std.crypto.ct''
  * X25519 allein ist kein authentifizierter Schlüsselaustausch — für PQC-sichere KEM → [[lyx_-_programmiersprache:units:crypto:pqc:hybrid|std.crypto.pqc.hybrid]]

Letzte Aktualisierung: 2026-06-08