## Pourquoi la PQC pour Kafka ?

Les algorithmes classiques d'établissement de clés (RSA, ECDH) sont vulnérables aux futurs ordinateurs quantiques. Si les clés de chiffrement par enregistrement sont établies à l'aide d'un KEM classique, un adversaire quantique pourrait récupérer ces clés à partir des encapsulations stockées aux côtés du texte chiffré sur le broker.

Ce plugin utilise ML-KEM (FIPS 203) pour l'encapsulation de clés résistante aux ordinateurs quantiques, garantissant que les données au repos sur le broker Kafka ne peuvent pas être déchiffrées même par un adversaire disposant d'un ordinateur quantique cryptographiquement pertinent.

**Remarque :** Ce filtre protège **les données au repos sur le broker**, et non le canal TLS en transit. Voir [THREAT_MODEL.md](https://github.com/oscerd/kroxylicious-pqc-filter/blob/HEAD/THREAT_MODEL.md) pour une analyse complète de ce qui est protégé et de ce qui ne l'est pas.

| Norme | Algorithme | Rôle dans ce plugin |
|----------|-----------|------------------------|
| FIPS 203 | ML-KEM (Kyber) | Encapsulation de clés - établit de manière sécurisée une clé AES par message |
| N/A | AES-256-GCM | Chiffrement authentifié symétrique de la charge utile de l'enregistrement |
| N/A | X25519 ECDH | Accord de clés classique pour la défense en profondeur du mode hybride |

## Fonctionnalités

- **Chiffrement/déchiffrement transparent** - aucune modification côté client requise
- **ML-KEM-512, ML-KEM-768 (défaut), ML-KEM-1024** ensembles de paramètres
- **Mode hybride** (défaut) - combine ML-KEM + X25519 ECDH de sorte que les deux doivent être cassés
- **Chiffrement par enregistrement** - chaque enregistrement reçoit une nouvelle encapsulation KEM + un IV aléatoire
- **Filtrage des topics** - les motifs regex sélectionnent les topics à chiffrer
- **Détection de falsification** - le chiffrement authentifié AES-GCM rejette tout texte chiffré modifié
- **Sécurité sémantique** - des textes clairs identiques produisent des textes chiffrés différents (IND-CCA2)
- **Génération automatique de clés** - génère et enregistre les clés ML-KEM au premier démarrage si elles sont absentes
- **En-tête `x-pqc-encrypted`** - marque les enregistrements chiffrés pour les composants en aval
- **Fournisseurs de clés enfichables** - le SPI `KeyProvider` prend en charge les backends filesystem (défaut) et HashiCorp Vault

## Prérequis

| Prérequis | Version |
|-------------|---------|
| JDK | 17+ (21+ recommandé) |
| Maven | 3.8+ |
| Kroxylicious | 0.19.0 |
| Apache Kafka | 3.9.x |

## Démarrage rapide

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

Ceci regroupe `spring-vault-core` et le `VaultKeyProvider` dans le JAR.

### 2. Générer des clés 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/

Alternativement, omettez les chemins des clés dans la configuration et le filtre générera
automatiquement les clés au premier démarrage.

### 3. Configurer Kroxylicious

Ajoutez le filtre à votre configuration YAML du 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

Lorsque vous utilisez Docker, définissez-le dans votre environnement de conteneur:```yaml
environment:
  KROXYLICIOUS_CLASSPATH: /opt/kroxylicious/plugins/*

### Ensembles de paramètres ML-KEM

| Algorithme | Niveau de sécurité | Clé publique | Clé privée | Surcharge du texte chiffré | Cas d'utilisation |
|-----------|---------------|------------|-------------|--------------------:|----------|
| ML-KEM-512 | 128 bits | 822 o | 1 730 o | ~854 o | Léger, IoT |
| ML-KEM-768 | 192 bits | 1 206 o | 2 498 o | ~1 174 o | **Valeur par défaut recommandée** |
| ML-KEM-1024 | 256 bits | 1 590 o | 3 266 o | ~1 654 o | Données classifiées / à long terme |

### Modes de chiffrement

**PQC uniquement** (`hybridMode: false`) :
Utilise exclusivement ML-KEM. La clé AES-256 est dérivée du secret partagé ML-KEM
via `SHA-256(0x01 || "kroxylicious-pqc-v1" || secret)`.

**Hybride** (`hybridMode: true`, par défaut) :
Combine ML-KEM + X25519. La clé AES-256 est dérivée des deux secrets via
`SHA-256(0x02 || "kroxylicious-pqc-hybrid-v1" || pqcSecret || x25519Secret)`.
Cela garantit la sécurité même si l'un des algorithmes est compromis.

## Format d'enveloppe chiffrée

Chaque valeur d'enregistrement chiffrée est remplacée par une enveloppe binaire :```
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 |        |                 |
+--------+-----------+--------------------+---------+--------+-----------------+

### Flux de données

#### Qu'est-ce qui est stocké dans Vault

Vault KV v2 stocke la paire de clés ML-KEM dans `secret/<secretPath>` (par exemple, `secret/kroxylicious/pqc`) :

| Champ | Contenu | Format |
|-------|---------|--------|
| `publicKey` | Clé publique ML-KEM (utilisée pour l'encapsulation) | X.509 DER encodée en Base64 |
| `privateKey` | Clé privée ML-KEM (utilisée pour la décapsulation) | PKCS#8 DER encodée en Base64 |

Chaque version du secret Vault agit comme un identifiant de clé, permettant la rotation des clés. Les nouvelles versions
chiffrent de nouveaux enregistrements ; les anciennes versions peuvent toujours déchiffrer les enregistrements chiffrés avec elles.

#### Flux de démarrage```
┌─────────────────────────────────────────────────────────────────────┐
│                           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)
                    ┌───────────────────────────────────────────┐

#### Flux de récupération (déchiffrement)```
                                  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)

### Classes clés

**`PqcRecordEncryptionFilterFactory`** implémente `FilterFactory<PqcEncryptionConfig, SharedPqcContext>`.
Annotée avec `@Plugin(configType = PqcEncryptionConfig.class)`.
Enregistrée via `META-INF/services/io.kroxylicious.proxy.filter.FilterFactory`.
Appelée une fois au démarrage (`initialize`) et une fois par connexion client (`createFilter`).

**`PqcRecordEncryptionFilter`** implémente `ProduceRequestFilter` et `FetchResponseFilter`.
Intercepte `onProduceRequest` pour chiffrer et `onFetchResponse` pour déchiffrer.
Une instance par connexion ; aucune synchronisation nécessaire (modèle de threads de Kroxylicious).

**`PqcCryptoEngine`** effectue toutes les opérations cryptographiques.
Sans état, à l'exception du matériel de clé et de `SecureRandom`.
`encrypt()` renvoie une enveloppe auto-descriptive ; `decrypt()` l'analyse.
Enregistre les fournisseurs Bouncy Castle (`BC`, `BCPQC`) dans un initialiseur statique.

**`PqcKeyManager`** résout un `KeyProvider` via `ServiceLoader`, en fonction de
`keyProviderType`. Délègue toutes les opérations de clé au fournisseur résolu.

**`KeyProvider`** est l'interface SPI pour les backends de stockage de clés enfichables.
Les implémentations sont découvertes via `META-INF/services`. Fournisseurs intégrés :
`FileSystemKeyProvider` (par défaut) et `VaultKeyProvider` (avec `-Pvault`).

**`PqcEncryptionConfig`** est un POJO annoté par Jackson.
Désérialisé à partir du bloc `config:` dans le YAML du proxy Kroxylicious.
Prend en charge `keyProviderType` et `keyProviderConfig` pour la sélection du backend.

## Compilation et tests```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