## ¿Por qué PQC para Kafka?

Los algoritmos clásicos de establecimiento de claves (RSA, ECDH) son vulnerables
a futuros ordenadores cuánticos. Si las claves de cifrado por registro se
establecen mediante un KEM clásico, un adversario cuántico podría recuperar esas
claves a partir de las encapsulaciones almacenadas junto con el texto cifrado en
el broker.

Este plugin utiliza ML-KEM (FIPS 203) para la encapsulación de claves resistente a
la computación cuántica, garantizando que los datos en reposo en el broker de
Kafka no puedan ser descifrados ni siquiera por un adversario con un ordenador
cuántico criptográficamente relevante.

**Nota:** Este filtro protege **los datos en reposo en el broker**, no el
canal TLS en tránsito. Consulta [THREAT_MODEL.md](https://github.com/oscerd/kroxylicious-pqc-filter/blob/HEAD/THREAT_MODEL.md) para un
análisis completo de qué está y qué no está protegido.

| Standard | Algoritmo | Propósito en este plugin |
|----------|-----------|------------------------|
| FIPS 203 | ML-KEM (Kyber) | Encapsulación de claves - establece de forma segura una clave AES por mensaje |
| N/A | AES-256-GCM | Cifrado autenticado simétrico de la carga útil del registro |
| N/A | X25519 ECDH | Acuerdo de claves clásico para defensa en profundidad en modo híbrido |

## Características

- **Cifrado/descifrado transparente** - no requiere cambios en el lado del cliente
- **ML-KEM-512, ML-KEM-768 (predeterminado), ML-KEM-1024** conjuntos de parámetros
- **Modo híbrido** (predeterminado) - combina ML-KEM + X25519 ECDH de modo que ambos deben ser rotos
- **Cifrado por registro** - cada registro obtiene una nueva encapsulación KEM + IV aleatorio
- **Filtrado por tema** - los patrones regex seleccionan qué temas cifrar
- **Detección de manipulación** - el cifrado autenticado AES-GCM rechaza el texto cifrado modificado
- **Seguridad semántica** - textos planos idénticos producen textos cifrados diferentes (IND-CCA2)
- **Autogeneración de claves** - genera y guarda claves ML-KEM en el primer arranque si no existen
- **Cabecera `x-pqc-encrypted`** - marca los registros cifrados para que los componentes posteriores lo sepan
- **Proveedores de claves conectables** - la SPI `KeyProvider` admite sistema de archivos (predeterminado) y backends de HashiCorp Vault

## Requisitos previos

| Requisito | Versión |
|-------------|---------|
| JDK | 17+ (se recomienda 21+) |
| Maven | 3.8+ |
| Kroxylicious | 0.19.0 |
| Apache Kafka | 3.9.x |

## Inicio rápido

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

Esto agrupa `spring-vault-core` y el `VaultKeyProvider` en el JAR.

### 2. Generar claves 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/

Alternativamente, omita las rutas de clave en la configuración y el filtro generará
claves automáticamente en el primer arranque.

### 3. Configurar Kroxylicious

Añade el filtro a tu configuración 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

Cuando uses Docker, establécelo en el entorno de tu contenedor:```yaml
environment:
  KROXYLICIOUS_CLASSPATH: /opt/kroxylicious/plugins/*

### Conjuntos de parámetros ML-KEM

| Algoritmo | Nivel de seguridad | Clave pública | Clave privada | Sobrecarga de texto cifrado | Caso de uso |
|-----------|---------------|------------|-------------|--------------------:|----------|
| ML-KEM-512 | 128-bit | 822 B | 1,730 B | ~854 B | Ligero, IoT |
| ML-KEM-768 | 192-bit | 1,206 B | 2,498 B | ~1,174 B | **Recomendado por defecto** |
| ML-KEM-1024 | 256-bit | 1,590 B | 3,266 B | ~1,654 B | Datos clasificados / de larga duración |

### Modos de cifrado

**Solo PQC** (`hybridMode: false`):
Utiliza exclusivamente ML-KEM. La clave AES-256 se deriva del secreto compartido ML-KEM
mediante `SHA-256(0x01 || "kroxylicious-pqc-v1" || secret)`.

**Híbrido** (`hybridMode: true`, por defecto):
Combina ML-KEM + X25519. La clave AES-256 se deriva de ambos secretos mediante
`SHA-256(0x02 || "kroxylicious-pqc-hybrid-v1" || pqcSecret || x25519Secret)`.
Esto garantiza la seguridad incluso si uno de los algoritmos resulta comprometido.

## Formato de sobre cifrado

Cada valor de registro cifrado se sustituye por un sobre binario:```
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 |        |                 |
+--------+-----------+--------------------+---------+--------+-----------------+

### Flujo de datos

#### Qué se almacena en Vault

Vault KV v2 almacena el par de claves ML-KEM en `secret/<secretPath>` (p. ej., `secret/kroxylicious/pqc`):

| Campo | Contenido | Formato |
|-------|-----------|---------|
| `publicKey` | Clave pública ML-KEM (utilizada para encapsulación) | X.509 DER codificado en Base64 |
| `privateKey` | Clave privada ML-KEM (utilizada para desencapsulación) | PKCS#8 DER codificado en Base64 |

Cada versión del secreto de Vault actúa como un identificador de clave, lo que permite la rotación de claves. Las versiones nuevas
cifran registros nuevos; las versiones antiguas aún pueden descifrar los registros cifrados con ellas.

#### Flujo de inicio```
┌─────────────────────────────────────────────────────────────────────┐
│                           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)
                    ┌───────────────────────────────────────────┐

#### Flujo de fetch (descifrado)```
                                  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)

### Clases clave

**`PqcRecordEncryptionFilterFactory`** implementa `FilterFactory<PqcEncryptionConfig, SharedPqcContext>`.
Anotada con `@Plugin(configType = PqcEncryptionConfig.class)`.
Registrada mediante `META-INF/services/io.kroxylicious.proxy.filter.FilterFactory`.
Se llama una vez al inicio (`initialize`) y una vez por conexión de cliente (`createFilter`).

**`PqcRecordEncryptionFilter`** implementa `ProduceRequestFilter` y `FetchResponseFilter`.
Intercepta `onProduceRequest` para cifrar y `onFetchResponse` para descifrar.
Una instancia por conexión; no se necesita sincronización (modelo de hilos de Kroxylicious).

**`PqcCryptoEngine`** realiza todas las operaciones criptográficas.
Sin estado, excepto por el material de claves y `SecureRandom`.
`encrypt()` devuelve un sobre autodescriptivo; `decrypt()` lo analiza.
Registra los proveedores de Bouncy Castle (`BC`, `BCPQC`) en un inicializador estático.

**`PqcKeyManager`** resuelve un `KeyProvider` mediante `ServiceLoader`, haciendo coincidir por
`keyProviderType`. Delega todas las operaciones de clave al proveedor resuelto.

**`KeyProvider`** es la interfaz SPI para backends de almacenamiento de claves conectables.
Las implementaciones se descubren mediante `META-INF/services`. Proveedores integrados:
`FileSystemKeyProvider` (predeterminado) y `VaultKeyProvider` (con `-Pvault`).

**`PqcEncryptionConfig`** es un POJO anotado con Jackson.
Se deserializa desde el bloque `config:` del YAML del proxy Kroxylicious.
Admite `keyProviderType` y `keyProviderConfig` para la selección del backend.

## Compilación y pruebas```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