## Warum PQC für Kafka?

Klassische Schlüsselvereinbarungsalgorithmen (RSA, ECDH) sind anfällig für zukünftige
Quantencomputer. Wenn Verschlüsselungsschlüssel pro Datensatz mithilfe eines
klassischen KEM etabliert werden, könnte ein Quantengegner diese Schlüssel aus den
Verkapselungen wiederherstellen, die neben dem Chiffrat auf dem Broker gespeichert sind.

Dieses Plugin verwendet ML-KEM (FIPS 203) zur quantenresistenten Schlüsselverkapselung,
sodass Daten im Ruhezustand auf dem Kafka-Broker selbst von einem
Gegner mit einem kryptografisch relevanten Quantencomputer nicht entschlüsselt werden können.

**Hinweis:** Dieser Filter schützt **Daten im Ruhezustand auf dem Broker**, nicht den TLS-
Kanal während der Übertragung. Siehe [THREAT_MODEL.md](https://github.com/oscerd/kroxylicious-pqc-filter/blob/HEAD/THREAT_MODEL.md) für eine vollständige
Analyse dessen, was verteidigt wird und was nicht.

| Standard | Algorithmus | Zweck in diesem Plugin |
|----------|-----------|------------------------|
| FIPS 203 | ML-KEM (Kyber) | Schlüsselverkapselung - etabliert sicher einen AES-Schlüssel pro Nachricht |
| N/A | AES-256-GCM | Symmetrische authentifizierte Verschlüsselung der Datensatz-Nutzlast |
| N/A | X25519 ECDH | Klassische Schlüsselvereinbarung für den Hybrid-Modus mit Verteidigung in der Tiefe |

## Funktionen

- **Transparente Ver-/Entschlüsselung** - keine clientseitigen Änderungen erforderlich
- **Parametersätze ML-KEM-512, ML-KEM-768 (Standard), ML-KEM-1024**
- **Hybrid-Modus** (Standard) - kombiniert ML-KEM + X25519 ECDH, sodass beide gebrochen werden müssen
- **Verschlüsselung pro Datensatz** - jeder Datensatz erhält eine frische KEM-Verkapselung + zufälligen IV
- **Topic-Filterung** - Regex-Muster wählen aus, welche Topics verschlüsselt werden
- **Manipulationserkennung** - die authentifizierte AES-GCM-Verschlüsselung weist verändertes Chiffrat zurück
- **Semantische Sicherheit** - identische Klartexte erzeugen unterschiedliche Chiffrate (IND-CCA2)
- **Automatische Schlüsselerzeugung** - erzeugt und speichert ML-KEM-Schlüssel beim ersten Start, falls nicht vorhanden
- **`x-pqc-encrypted`-Header** - kennzeichnet verschlüsselte Datensätze für nachgelagerte Komponenten
- **Plugbare Schlüsselanbieter** - das `KeyProvider`-SPI unterstützt Dateisystem- (Standard) und HashiCorp-Vault-Backends

## Voraussetzungen

| Anforderung | Version |
|-------------|---------|
| JDK | 17+ (21+ empfohlen) |
| Maven | 3.8+ |
| Kroxylicious | 0.19.0 |
| Apache Kafka | 3.9.x |

## Schnellstart

### 1. Plugin bauen```bash
git clone <this-repo>
cd kroxylicious-pqc-filter
mvn clean package -DskipTests

Dies bündelt `spring-vault-core` und den `VaultKeyProvider` in das JAR.

### 2. ML-KEM-Schlüssel generieren```bash
java -cp target/kroxylicious-pqc-filter-1.0.0-SNAPSHOT.jar \
  io.kroxylicious.filter.pqc.PqcKeyGeneratorCli \
  ML_KEM_768 \
  /etc/kroxylicious/pqc/

Alternativ können Sie die Schlüsselpfade in der Konfiguration weglassen, und der Filter generiert die Schlüssel beim ersten Start automatisch.

### 3. Kroxylicious konfigurieren

Fügen Sie den Filter zu Ihrer Kroxylicious-Proxy-YAML-Konfiguration hinzu:```yaml
filterDefinitions:
  - name: pqc-encryption
    type: PqcRecordEncryptionFilterFactory
    config:
      kemAlgorithm: ML_KEM_768
      hybridMode: true
      publicKeyPath: /etc/kroxylicious/pqc/pqc-public.der
      privateKeyPath: /etc/kroxylicious/pqc/pqc-private.der
      topicPatterns:
        - "sensitive-.*"
        - "pii-.*"

defaultFilters:
  - pqc-encryption

Wenn Sie Docker verwenden, setzen Sie es in Ihrer Container-Umgebung:```yaml
environment:
  KROXYLICIOUS_CLASSPATH: /opt/kroxylicious/plugins/*

### ML-KEM-Parametersätze

| Algorithmus | Sicherheitsstufe | Öffentlicher Schlüssel | Privater Schlüssel | Chiffrat-Overhead | Anwendungsfall |
|-----------|---------------|------------|-------------|--------------------:|----------|
| ML-KEM-512 | 128-Bit | 822 B | 1,730 B | ~854 B | Leichtgewichtig, IoT |
| ML-KEM-768 | 192-Bit | 1,206 B | 2,498 B | ~1,174 B | **Empfohlene Standardoption** |
| ML-KEM-1024 | 256-Bit | 1,590 B | 3,266 B | ~1,654 B | Klassifizierte / langlebige Daten |

### Verschlüsselungsmodi

**Nur-PQC** (`hybridMode: false`):
Verwendet ausschließlich ML-KEM. Der AES-256-Schlüssel wird aus dem gemeinsamen ML-KEM-Geheimnis abgeleitet über `SHA-256(0x01 || "kroxylicious-pqc-v1" || secret)`.

**Hybrid** (`hybridMode: true`, Standard):
Kombiniert ML-KEM + X25519. Der AES-256-Schlüssel wird aus beiden Geheimnissen abgeleitet über `SHA-256(0x02 || "kroxylicious-pqc-hybrid-v1" || pqcSecret || x25519Secret)`.
Dadurch ist die Sicherheit auch dann gewährleistet, wenn ein Algorithmus gebrochen wird.

## Format des verschlüsselten Umschlags

Jeder verschlüsselte Record-Wert wird durch einen binären Umschlag ersetzt:```
PQC-only (version 0x01):
+--------+-----------+--------------------+--------+---------------------------+
| 1 byte | 2 bytes   | N bytes            | 12 B   | remaining                 |
| 0x01   | encap len | ML-KEM encapsulat. | AES IV | AES-GCM ciphertext + tag  |
+--------+-----------+--------------------+--------+---------------------------+

Hybrid (version 0x02):
+--------+-----------+--------------------+---------+--------+-----------------+
| 1 byte | 2 bytes   | N bytes            | 32 B    | 12 B   | remaining       |
| 0x02   | encap len | ML-KEM encapsulat. | X25519  | AES IV | AES-GCM ct+tag |
|        |           |                    | eph pub |        |                 |
+--------+-----------+--------------------+---------+--------+-----------------+

### Datenfluss

#### Was im Vault gespeichert wird

Vault KV v2 speichert das ML-KEM-Schlüsselpaar unter `secret/<secretPath>` (z. B. `secret/kroxylicious/pqc`):

| Feld | Inhalt | Format |
|-------|---------|--------|
| `publicKey` | ML-KEM öffentlicher Schlüssel (für die Verkapselung) | Base64-kodiertes X.509-DER |
| `privateKey` | ML-KEM privater Schlüssel (für die Entkapselung) | Base64-kodiertes PKCS#8-DER |

Jede Vault-Secret-Version fungiert als Schlüssel-ID und ermöglicht so die Schlüsselrotation. Neue Versionen verschlüsseln neue Datensätze; alte Versionen können weiterhin Datensätze entschlüsseln, die mit ihnen verschlüsselt wurden.

#### Ablauf beim Start```
┌─────────────────────────────────────────────────────────────────────┐
│                           STARTUP                                   │
│                                                                     │
│  1. Vault starts (dev mode, port 8200)                              │
│         │                                                           │
│  2. vault-init container:                                           │
│         │  • Reads pre-generated ML-KEM DER key files from disk     │
│         │  • Base64-encodes them                                    │
│         │  • POST /v1/secret/data/kroxylicious/pqc                  │
│         │  • Stores publicKey + privateKey in Vault KV v2           │
│         │  • Exits                                                  │
│         │                                                           │
│  3. Kafka starts (KRaft mode, port 9092)                            │
│         │                                                           │
│  4. Kroxylicious starts (port 9192):                                │
│         │                                                           │
│         │  FilterFactory.initialize()                                │
│         │    → PqcKeyManager resolves VaultKeyProvider               │
│         │      via ServiceLoader (matches keyProviderType: "vault")  │
│         │    → VaultKeyProvider.configure()                          │
│         │      connects to Vault (token/approle/kubernetes auth)     │
│         │    → Fetches ML-KEM key pair from Vault KV v2              │
│         │      (GET /v1/secret/data/kroxylicious/pqc)                │
│         │    → Decodes: base64 → DER bytes → Java Key objects        │
│         │    → PqcCryptoEngine initialized with key pair             │
│         ▼                                                           │
│       Proxy ready — Vault is NOT contacted again per-message         │
└─────────────────────────────────────────────────────────────────────┘

                     Kroxylicious (:9192)
                    ┌───────────────────────────────────────────┐

#### Fetch-Ablauf (Entschlüsselung)```
                                  Kafka Broker (:9092)
                                  returns encrypted blob
                                         │
                                         ▼
                        ┌────────────────┴──────────────────────────┐
                        │ PqcRecordEncryptionFilter                 │
                        │   .onFetchResponse()                      │
                        │                                           │
                        │ For each record with x-pqc-encrypted:     │
                        │   1. Parse envelope → extract encap +     │
                        │      ciphertext                           │
                        │   2. ML-KEM decapsulate (private key)     │
                        │      → recover shared secret              │
                        │   3. SHA-256(shared secret) → AES-256 key │
                        │   4. AES-GCM decrypt → plaintext          │
                        │   5. Remove x-pqc-encrypted header        │
Consumer <──plaintext── │                                           │
                        └───────────────────────────────────────────┘
                         Kroxylicious (:9192)

### Wichtige Klassen

**`PqcRecordEncryptionFilterFactory`** implementiert `FilterFactory<PqcEncryptionConfig, SharedPqcContext>`.
Annotiert mit `@Plugin(configType = PqcEncryptionConfig.class)`.
Registriert über `META-INF/services/io.kroxylicious.proxy.filter.FilterFactory`.
Wird einmal beim Start (`initialize`) und einmal pro Client-Verbindung (`createFilter`) aufgerufen.

**`PqcRecordEncryptionFilter`** implementiert `ProduceRequestFilter` und `FetchResponseFilter`.
Fängt `onProduceRequest` ab, um zu verschlüsseln, und `onFetchResponse`, um zu entschlüsseln.
Eine Instanz pro Verbindung; keine Synchronisierung erforderlich (Kroxylicious-Threadmodell).

**`PqcCryptoEngine`** führt alle kryptografischen Operationen aus.
Zustandslos, abgesehen von Schlüsselmaterial und `SecureRandom`.
`encrypt()` gibt einen selbstbeschreibenden Umschlag zurück; `decrypt()` parst ihn.
Registriert Bouncy-Castle-Provider (`BC`, `BCPQC`) in einem statischen Initialisierer.

**`PqcKeyManager`** löst einen `KeyProvider` über `ServiceLoader` auf, wobei nach
`keyProviderType` abgeglichen wird. Delegiert alle Schlüsseloperationen an den aufgelösten Provider.

**`KeyProvider`** ist die SPI-Schnittstelle für austauschbare Schlüsselspeicher-Backends.
Implementierungen werden über `META-INF/services` ermittelt. Integrierte Provider:
`FileSystemKeyProvider` (Standard) und `VaultKeyProvider` (mit `-Pvault`).

**`PqcEncryptionConfig`** ist ein Jackson-annotiertes POJO.
Wird aus dem `config:`-Block in der Kroxylicious-Proxy-YAML deserialisiert.
Unterstützt `keyProviderType` und `keyProviderConfig` für die Backend-Auswahl.

## Erstellen und Testen```bash
# Compile
mvn compile

# Run unit tests (38 core tests)
mvn test

# Package (creates shaded JAR with Bouncy Castle bundled)
mvn package

# Build with Vault support (55 tests: 38 core + 17 vault)
mvn package -Pvault

# Install to local Maven repository
mvn install