Filtro de cifrado de registros PQC de Kroxylicious

Un complemento de filtro de Kroxylicious que proporciona cifrado transparente a nivel de registro Post-Cuántico (PQC) para Apache Kafka mediante encapsulación de claves ML-KEM (FIPS 203) con cifrado simétrico AES-256-GCM.

Los productores y consumidores de Kafka requieren cero cambios de código. El proxy de Kroxylicious intercepta el tráfico y cifra en Produce / descifra en Fetch automáticamente.``` Producer ──plaintext──> Kroxylicious ──encrypted──> Kafka Broker Consumer <──plaintext── Kroxylicious <──encrypted── Kafka Broker

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

El JAR sombreado en target/kroxylicious-pqc-filter-1.0.0-SNAPSHOT.jar incluye Bouncy Castle, por lo que se puede incorporar a Kroxylicious sin dependencias adicionales.

Para incluir soporte del proveedor de claves de HashiCorp Vault, compila con el perfil vault:```bash mvn clean package -Pvault -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/

I need to translate content, but the input is empty.``` 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

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

4. Despliegue

Coloque el JAR en un directorio accesible para Kroxylicious y agréguelo al classpath mediante la variable de entorno KROXYLICIOUS_CLASSPATH:```bash export KROXYLICIOUS_CLASSPATH="/opt/kroxylicious/plugins/*"

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

Luego inicie el proxy. Los productores y consumidores se conectan al puerto del proxy en lugar de hacerlo directamente al broker.

Referencia de configuración

Propiedad	Tipo	Requerido	Predeterminado	Descripción
kemAlgorithm	enum	No	ML_KEM_768	Conjunto de parámetros ML-KEM. Uno de ML_KEM_512, ML_KEM_768, ML_KEM_1024.
hybridMode	boolean	No	true	Combina ML-KEM con X25519 ECDH para defensa en profundidad.
publicKeyPath	string	Solo sistema de archivos	-	Ruta en el sistema de archivos a la clave pública ML-KEM (codificada en X.509 DER).
privateKeyPath	string	Solo sistema de archivos	-	Ruta en el sistema de archivos a la clave privada ML-KEM (codificada en PKCS#8 DER).
topicPatterns	list<string>	No	[".*"]	Patrones regex de Java. Solo los registros en temas que coinciden se cifran/descifran.
keyProviderType	string	No	filesystem	Backend de almacenamiento de claves. Uno de filesystem, vault.
keyProviderConfig	map<string, string>	Solo Vault	{}	Configuración específica del backend (consulte la sección de Vault a continuación).

Proveedores de claves

Filesystem (keyProviderType: filesystem, predeterminado): Carga claves ML-KEM desde archivos DER en disco. Si los archivos no existen, genera un nuevo par de claves y los guarda. Requiere publicKeyPath y privateKeyPath.

HashiCorp Vault (keyProviderType: vault, requiere compilación con -Pvault): Obtiene claves ML-KEM de un motor de secretos Vault KV v2. Las claves se almacenan como DER codificadas en base64 en los campos publicKey y privateKey. Las versiones de secretos de Vault se asignan a IDs de clave para admitir la rotación de claves.

Propiedades de keyProviderConfig de Vault:

Propiedad	Requerido	Predeterminado	Descripción
vaultAddress	Sí	Env. VAULT_ADDR	URL del servidor Vault (p. ej., http://vault:8200)
vaultToken	Para autenticación token	Env. VAULT_TOKEN	Token de autenticación de Vault
secretPath	Sí	--	Ruta dentro del motor de secretos (p. ej., kroxylicious/pqc)
secretEngine	No	secret	Nombre de montaje del motor de secretos KV v2
authMethod	No	token	Método de autenticación: token, approle o kubernetes
roleId	Para approle	--	ID de rol de AppRole
secretId	Para approle	--	ID de secreto de AppRole
kubeRole	Para kubernetes	--	Nombre del rol de autenticación de Kubernetes
kubeTokenPath	No	/var/run/secrets/.../token	Ruta del archivo de token de la cuenta de servicio