## Perché PQC per Kafka?

Gli algoritmi classici di stabilimento delle chiavi (RSA, ECDH) sono vulnerabili ai
futuri computer quantistici. Se le chiavi di cifratura per singolo record vengono stabilite utilizzando un
KEM classico, un avversario quantistico potrebbe recuperare quelle chiavi dalle
incapsulazioni memorizzate insieme al ciphertext sul broker.

Questo plugin utilizza ML-KEM (FIPS 203) per l'incapsulamento delle chiavi resistente ai computer quantistici,
garantendo che i dati a riposo sul broker Kafka non possano essere decifrati nemmeno da
un avversario dotato di un computer quantistico crittograficamente rilevante.

**Nota:** Questo filtro protegge **i dati a riposo sul broker**, non il canale TLS
in transito. Vedere [THREAT_MODEL.md](https://github.com/oscerd/kroxylicious-pqc-filter/blob/HEAD/THREAT_MODEL.md) per un'analisi
completa di ciò che viene difeso e ciò che non lo è.

| Standard | Algoritmo | Scopo in questo plugin |
|----------|-----------|------------------------|
| FIPS 203 | ML-KEM (Kyber) | Incapsulamento delle chiavi - stabilisce in modo sicuro una chiave AES per messaggio |
| N/D | AES-256-GCM | Cifratura autenticata simmetrica del payload del record |
| N/D | X25519 ECDH | Accordo di chiave classico per difesa in profondità in modalità ibrida |

## Caratteristiche

- **Cifratura/decifratura trasparente** - nessuna modifica lato client richiesta
- **Set di parametri ML-KEM-512, ML-KEM-768 (predefinito), ML-KEM-1024**
- **Modalità ibrida** (predefinita) - combina ML-KEM + X25519 ECDH così che entrambi debbano essere compromessi
- **Cifratura per singolo record** - ogni record ottiene una nuova incapsulazione KEM + IV casuale
- **Filtro per argomento** - pattern regex selezionano quali argomenti cifrare
- **Rilevamento manomissioni** - la cifratura autenticata AES-GCM rifiuta ciphertext modificati
- **Sicurezza semantica** - plaintext identici producono ciphertext diversi (IND-CCA2)
- **Generazione automatica delle chiavi** - genera e salva le chiavi ML-KEM al primo avvio se assenti
- **Header `x-pqc-encrypted`** - contrassegna i record cifrati per la consapevolezza a valle
- **Provider di chiavi componibili** - la SPI `KeyProvider` supporta backend filesystem (predefinito) e HashiCorp Vault

## Prerequisiti

| Requisito | Versione |
|-------------|---------|
| JDK | 17+ (21+ consigliato) |
| Maven | 3.8+ |
| Kroxylicious | 0.19.0 |
| Apache Kafka | 3.9.x |

## Avvio rapido

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

Questo include `spring-vault-core` e `VaultKeyProvider` nel JAR.

### 2. Genera le chiavi ML-KEM```bash
java -cp target/kroxylicious-pqc-filter-1.0.0-SNAPSHOT.jar \
  io.kroxylicious.filter.pqc.PqcKeyGeneratorCli \
  ML_KEM_768 \
  /etc/kroxylicious/pqc/

In alternativa, ometti i percorsi delle chiavi nella configurazione e il filtro genererà le chiavi automaticamente al primo avvio.

### 3. Configura Kroxylicious

Aggiungi il filtro alla configurazione YAML del proxy Kroxylicious:```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

Quando usi Docker, impostalo nell'ambiente del container:```yaml
environment:
  KROXYLICIOUS_CLASSPATH: /opt/kroxylicious/plugins/*

### Set di parametri ML-KEM

| Algorithm | Security Level | Public Key | Private Key | Ciphertext Overhead | Use Case |
|-----------|---------------|------------|-------------|--------------------:|----------|
| ML-KEM-512 | 128-bit | 822 B | 1,730 B | ~854 B | Leggero, IoT |
| ML-KEM-768 | 192-bit | 1,206 B | 2,498 B | ~1,174 B | **Default consigliato** |
| ML-KEM-1024 | 256-bit | 1,590 B | 3,266 B | ~1,654 B | Dati classificati / di lunga durata |

### Modalità di cifratura

**Solo PQC** (`hybridMode: false`):
Utilizza esclusivamente ML-KEM. La chiave AES-256 viene derivata dal segreto condiviso ML-KEM
tramite `SHA-256(0x01 || "kroxylicious-pqc-v1" || secret)`.

**Ibrido** (`hybridMode: true`, predefinito):
Combina ML-KEM + X25519. La chiave AES-256 viene derivata da entrambi i segreti tramite
`SHA-256(0x02 || "kroxylicious-pqc-hybrid-v1" || pqcSecret || x25519Secret)`.
Ciò garantisce la sicurezza anche se un algoritmo viene compromesso.

## Formato della busta cifrata

Ogni valore di record cifrato viene sostituito con una busta binaria:```
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 |        |                 |
+--------+-----------+--------------------+---------+--------+-----------------+

### Data Flow

#### What is stored in Vault

Vault KV v2 holds the ML-KEM key pair at `secret/<secretPath>` (e.g., `secret/kroxylicious/pqc`):

| Field | Content | Format |
|-------|---------|--------|
| `publicKey` | ML-KEM public key (used for encapsulation) | Base64-encoded X.509 DER |
| `privateKey` | ML-KEM private key (used for decapsulation) | Base64-encoded PKCS#8 DER |

Each Vault secret version acts as a key ID, enabling key rotation. New versions
encrypt new records; old versions can still decrypt records encrypted with them.

#### Startup flow```
┌─────────────────────────────────────────────────────────────────────┐
│                           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)
                    ┌───────────────────────────────────────────┐

#### Flusso di recupero (decrittazione)```
                                  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)

### Classi chiave

**`PqcRecordEncryptionFilterFactory`** implementa `FilterFactory<PqcEncryptionConfig, SharedPqcContext>`.
È annotata con `@Plugin(configType = PqcEncryptionConfig.class)`.
Registrata tramite `META-INF/services/io.kroxylicious.proxy.filter.FilterFactory`.
Viene chiamata una volta all'avvio (`initialize`) e una volta per connessione client (`createFilter`).

**`PqcRecordEncryptionFilter`** implementa `ProduceRequestFilter` e `FetchResponseFilter`.
Intercetta `onProduceRequest` per cifrare e `onFetchResponse` per decifrare.
 Una istanza per connessione; non è necessaria alcuna sincronizzazione (modello di thread di Kroxylicious).

**`PqcCryptoEngine`** esegue tutte le operazioni crittografiche.
Senza stato, ad eccezione del materiale delle chiavi e di `SecureRandom`.
`encrypt()` restituisce un involucro auto-descrittivo; `decrypt()` lo analizza.
Registra i provider Bouncy Castle (`BC`, `BCPQC`) in un inizializzatore statico.

**`PqcKeyManager`** risolve un `KeyProvider` tramite `ServiceLoader`, effettuando la corrispondenza in base a
`keyProviderType`. Delega tutte le operazioni sulle chiavi al provider risolto.

**`KeyProvider`** è l'interfaccia SPI per backend di archiviazione delle chiavi componibili.
Le implementazioni vengono scoperte tramite `META-INF/services`. Provider integrati:
`FileSystemKeyProvider` (predefinito) e `VaultKeyProvider` (con `-Pvault`).

**`PqcEncryptionConfig`** è un POJO annotato con Jackson.
Deserializzato dal blocco `config:` nello YAML del proxy Kroxylicious.
Supporta `keyProviderType` e `keyProviderConfig` per la selezione del backend.

## Compilazione e Test```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