Kroxylicious Filtro di Crittografia dei Record PQC

Un plugin filtro per Kroxylicious che fornisce una trasparente crittografia a livello di record con Crittografia Post-Quantum (PQC) per Apache Kafka utilizzando ML-KEM (FIPS 203) key encapsulation con crittografia simmetrica AES-256-GCM.

I produttori e i consumatori Kafka richiedono zero modifiche al codice. Il proxy Kroxylicious intercetta il traffico e crittografa in Produce / decrittografa in Fetch automaticamente.``` Producer ──plaintext──> Kroxylicious ──encrypted──> Kafka Broker Consumer <──plaintext── Kroxylicious <──encrypted── Kafka Broker

## 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/main/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

Il JAR shaded in target/kroxylicious-pqc-filter-1.0.0-SNAPSHOT.jar include Bouncy Castle così può essere inserito in Kroxylicious senza dipendenze extra.

Per includere il supporto per il key provider HashiCorp Vault, compila con il profilo vault:```bash mvn clean package -Pvault -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/

I'm unable to produce a translation because no source text was included in this request. The INPUT: section is empty, so there is no content to translate.``` Generating ML-KEM-768 key pair... Public key: /etc/kroxylicious/pqc/pqc-public.der Size: 1206 bytes Format: X.509 Private key: /etc/kroxylicious/pqc/pqc-private.der Size: 2498 bytes Format: PKCS#8

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

4. Distribuzione

Posiziona il JAR in una directory accessibile a Kroxylicious e aggiungilo al classpath tramite la variabile d'ambiente KROXYLICIOUS_CLASSPATH:```bash export KROXYLICIOUS_CLASSPATH="/opt/kroxylicious/plugins/*"

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

Then start the proxy. Producers and consumers connect to the proxy port instead of the broker directly.

Configuration Reference

Property	Type	Required	Default	Description
kemAlgorithm	enum	No	ML_KEM_768	ML-KEM parameter set. One of ML_KEM_512, ML_KEM_768, ML_KEM_1024.
hybridMode	boolean	No	true	Combine ML-KEM with X25519 ECDH for defense-in-depth.
publicKeyPath	string	Filesystem only	-	Filesystem path to the ML-KEM public key (X.509 DER encoded).
privateKeyPath	string	Filesystem only	-	Filesystem path to the ML-KEM private key (PKCS#8 DER encoded).
topicPatterns	list<string>	No	[".*"]	Java regex patterns. Only records in matching topics are encrypted/decrypted.
keyProviderType	string	No	filesystem	Key storage backend. One of filesystem, vault.
keyProviderConfig	map<string, string>	Vault only	{}	Backend-specific configuration (see Vault section below).

Key Providers

Filesystem (keyProviderType: filesystem, default): Loads ML-KEM keys from DER files on disk. If the files do not exist, generates a fresh key pair and saves them. Requires publicKeyPath and privateKeyPath.

HashiCorp Vault (keyProviderType: vault, requires -Pvault build): Fetches ML-KEM keys from a Vault KV v2 secrets engine. Keys are stored as base64-encoded DER in publicKey and privateKey fields. Vault secret versions map to key IDs for key rotation support.

Vault keyProviderConfig properties:

Property	Required	Default	Description
vaultAddress	Yes	VAULT_ADDR env	Vault server URL (e.g., http://vault:8200)
vaultToken	For token auth	VAULT_TOKEN env	Vault authentication token
secretPath	Yes	--	Path within the secrets engine (e.g., kroxylicious/pqc)
secretEngine	No	secret	KV v2 secrets engine mount name
authMethod	No	token	Auth method: token, approle, or kubernetes
roleId	For approle	--	AppRole role ID
secretId	For approle	--	AppRole secret ID
kubeRole	For kubernetes	--	Kubernetes auth role name
kubeTokenPath	No	/var/run/secrets/.../token	Service account token file path

Example Vault configuration:```yaml filterDefinitions:

• name: pqc-encryption type: PqcRecordEncryptionFilterFactory config: kemAlgorithm: ML_KEM_768 hybridMode: false keyProviderType: vault keyProviderConfig: vaultAddress: http://vault:8200 vaultToken: my-token secretPath: kroxylicious/pqc topicPatterns: - "sensitive-.*"

### Set di parametri ML-KEM