====== std.crypto.pqc.pqc ======

''std.crypto.pqc.pqc'' ist die **einheitliche High-Level-API** für alle Post-Quantum-Kryptografie in Lyx. Sie abstrahiert über ML-KEM (FIPS 203), ML-DSA (FIPS 204), SLH-DSA (FIPS 205) und Hybrid-KEM — alle Algorithmen werden über denselben Handle-basierten Workflow bedient.

**Empfehlung:** Für neue Anwendungen immer diese Unit verwenden statt die Low-Level-Units direkt.

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

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

----

===== Algorithmus-Konstanten =====

^ Konstante ^ Wert ^ Algorithmus ^ Typ ^
| ''PQC_ALG_MLKEM_512'' | 1 | ML-KEM-512 (FIPS 203) | KEM |
| ''PQC_ALG_MLKEM_768'' | 2 | ML-KEM-768 (FIPS 203) — **Standardwahl KEM** | KEM |
| ''PQC_ALG_MLKEM_1024'' | 3 | ML-KEM-1024 (FIPS 203) | KEM |
| ''PQC_ALG_MLDSA_44'' | 4 | ML-DSA-44 (FIPS 204) | DSA |
| ''PQC_ALG_MLDSA_65'' | 5 | ML-DSA-65 (FIPS 204) — **Standardwahl DSA** | DSA |
| ''PQC_ALG_MLDSA_87'' | 6 | ML-DSA-87 (FIPS 204) | DSA |
| ''PQC_ALG_SLHDSA_128S'' | 7 | SLH-DSA-SHA2-128s (FIPS 205) | DSA |
| ''PQC_ALG_SLHDSA_256S'' | 8 | SLH-DSA-SHA2-256s (FIPS 205) | DSA |
| ''PQC_ALG_HYBRID_768'' | 9 | Hybrid-KEM X25519+ML-KEM-768 | KEM |
| ''PQC_ALG_SLHDSA_MINI'' | 10 | Mini-Params (n=16, h=4) — **nur für Tests** | DSA |

Weitere Größenkonstanten: ''PQC_SS_LEN = 32'' (Shared-Secret-Länge), ''PQC_KP_SIZE = 40'' (Handle-Größe).

----

===== Seed-Größen für PQCKeyGenFromSeed =====

^ Algorithmus ^ Seed-Größe ^
| ML-KEM-512/768/1024 | 64 Bytes (d[32] + z[32]) |
| ML-DSA-44/65/87 | 32 Bytes (ξ) |
| SLH-DSA-128s | 48 Bytes (skseed[16] + skprf[16] + pkseed[16]) |
| SLH-DSA-256s | 96 Bytes (skseed[32] + skprf[32] + pkseed[32]) |
| Hybrid-768 | 64 Bytes (seed_x25519[32] + seed_mlkem[32]) |

----

===== Funktionen =====

**Schlüsselerzeugung:**

^ Funktion ^ Beschreibung ^
| ''PQCKeyGen(alg): int64'' | Erzeugt Schlüsselpaar mit internem CSPRNG-Seed. Gibt Handle zurück. |
| ''PQCKeyGenFromSeed(alg, seed): int64'' | Deterministisch aus seed (PQCSeedSize(alg) Bytes). Gibt Handle zurück, oder 0 bei unbekanntem Algorithmus. |
| ''PQCFreeKeyPair(kp)'' | Gibt Handle und alle zugehörigen Puffer frei. |

**Größenabfragen:**

^ Funktion ^ Beschreibung ^
| ''PQCPublicKeyLen(alg): int64'' | PK-Größe in Bytes für Algorithmus alg. |
| ''PQCSecretKeyLen(alg): int64'' | SK-Größe in Bytes. |
| ''PQCCTLen(alg): int64'' | Ciphertext-Größe (nur KEM-Algorithmen). |
| ''PQCSigLen(alg): int64'' | Maximale Signaturlänge (nur DSA-Algorithmen). |
| ''PQCSeedSize(alg): int64'' | Seed-Größe für PQCKeyGenFromSeed. |

**Handle-Zugriff:**

^ Funktion ^ Beschreibung ^
| ''PQCGetAlgorithm(kp): int64'' | Liest Algorithmus-ID aus Handle. |
| ''PQCGetPublicKey(kp): int64'' | Zeiger auf PK-Puffer. |
| ''PQCGetPublicKeyLen(kp): int64'' | PK-Länge aus Handle. |
| ''PQCGetSecretKey(kp): int64'' | Zeiger auf SK-Puffer. |
| ''PQCGetSecretKeyLen(kp): int64'' | SK-Länge aus Handle. |

**KEM-Operationen:**

^ Funktion ^ Beschreibung ^
| ''PQCEncapsulate(kp, ctOut, ssOut): int64'' | Erzeugt CT und SS (32 Bytes) mit internem CSPRNG. ctOut: PQCCTLen(alg) Bytes. Gibt 0 bei Erfolg, -1 wenn kein KEM. |
| ''PQCDecapsulate(kp, ct, ssOut): int64'' | Rekonstruiert SS aus CT. ssOut: PQC_SS_LEN Bytes. Gibt 0 bei Erfolg, -1 wenn kein KEM. |

**DSA-Operationen:**

^ Funktion ^ Beschreibung ^
| ''PQCSign(kp, msg, msgLen, sigOut): int64'' | Signiert msg. sigOut: PQCSigLen(alg) Bytes. Gibt tatsächliche Signaturlänge, oder 0 bei Fehler / falscher Algorithmus. |
| ''PQCVerify(kp, msg, msgLen, sig, sigLen): int64'' | Verifiziert Signatur. Gibt 1 bei gültig, 0 bei ungültig. |

**Import / Export:**

^ Funktion ^ Beschreibung ^
| ''PQCExportPublicKey(kp, out): int64'' | Kopiert PK in out. Gibt pkLen zurück. |
| ''PQCExportSecretKey(kp, out): int64'' | Kopiert SK in out. Gibt skLen zurück. |
| ''PQCImportPublicKey(alg, data, len): int64'' | Erstellt Handle mit nur dem PK (kein SK). Für Encapsulate / Verify mit fremdem Key. Gibt Handle oder 0. |

----

===== Verwendungsbeispiele =====

**KEM — Shared Secret aushandeln (ML-KEM-768):**

<code lyx>
import std.crypto.pqc.pqc;
import std.alloc;

fn main(): int64 {
  // Empfänger erzeugt Schlüsselpaar
  var kp: int64 := PQCKeyGen(PQC_ALG_MLKEM_768);

  // Sender kapselt Shared Secret ein (nur PK nötig)
  var ct_len: int64 := PQCCTLen(PQC_ALG_MLKEM_768);
  var ct: int64 := alloc(ct_len);
  var ss_enc: int64 := alloc(PQC_SS_LEN);
  PQCEncapsulate(kp, ct, ss_enc);

  // Empfänger rekonstruiert Shared Secret
  var ss_dec: int64 := alloc(PQC_SS_LEN);
  PQCDecapsulate(kp, ct, ss_dec);
  // ss_enc == ss_dec

  free(ct, ct_len); free(ss_enc, PQC_SS_LEN); free(ss_dec, PQC_SS_LEN);
  PQCFreeKeyPair(kp);
  return 0;
}
</code>

**DSA — Signieren und Verifizieren (ML-DSA-65):**

<code lyx>
import std.crypto.pqc.pqc;
import std.alloc;

fn main(): int64 {
  var kp: int64 := PQCKeyGen(PQC_ALG_MLDSA_65);

  var msg: pchar := "Zu signieren"c;
  var m_len: int64 := 12;
  var sig_max: int64 := PQCSigLen(PQC_ALG_MLDSA_65);
  var sig: int64 := alloc(sig_max);
  var sig_len: int64 := PQCSign(kp, msg as int64, m_len, sig);

  var ok: int64 := PQCVerify(kp, msg as int64, m_len, sig, sig_len);
  // ok == 1 wenn gültig

  free(sig, sig_max);
  PQCFreeKeyPair(kp);
  return 0;
}
</code>

----

===== Algorithmusauswahl =====

^ Aufgabe ^ Empfohlener Algorithmus ^
| Schlüsselaustausch (Standard) | ''PQC_ALG_MLKEM_768'' |
| Schlüsselaustausch (Hybrid, maximale Sicherheit) | ''PQC_ALG_HYBRID_768'' |
| Digitale Signatur (Standard) | ''PQC_ALG_MLDSA_65'' |
| Digitale Signatur (kleiner Public Key, konservative Annahmen) | ''PQC_ALG_SLHDSA_128S'' |
| Digitale Signatur (maximale Sicherheit) | ''PQC_ALG_MLDSA_87'' |

Letzte Aktualisierung: 2026-06-08