Kroxylicious PQC Record Encryption Filter

Um plugin de filtro Kroxylicious que fornece criptografia transparente em nível de registro de Pós-Quantum (PQC) para Apache Kafka usando encapsulamento de chave ML-KEM (FIPS 203) com criptografia simétrica AES-256-GCM.

Produtores e consumidores Kafka não exigem nenhuma alteração de código. O proxy Kroxylicious intercepta o tráfego e criptografa no Produce / descriptografa no Fetch automaticamente.``` Producer ──plaintext──> Kroxylicious ──encrypted──> Kafka Broker Consumer <──plaintext── Kroxylicious <──encrypted── Kafka Broker

## Por que PQC para Kafka?

Algoritmos clássicos de estabelecimento de chaves (RSA, ECDH) são vulneráveis a futuros computadores quânticos. Se as chaves de criptografia por registro forem estabelecidas usando um KEM clássico, um adversário quântico poderia recuperar essas chaves das encapsulações armazenadas junto ao texto cifrado no broker.

Este plugin usa ML-KEM (FIPS 203) para encapsulamento de chaves resistente a quântica, garantindo que dados em repouso no broker Kafka não possam ser descriptografados mesmo por um adversário com um computador quântico criptograficamente relevante.

**Nota:** Este filtro protege **dados em repouso no broker**, não o canal TLS em trânsito. Consulte [THREAT_MODEL.md](https://github.com/oscerd/kroxylicious-pqc-filter/blob/main/THREAT_MODEL.md) para uma análise completa do que é e não é defendido.

| Padrão | Algoritmo | Propósito neste plugin |
|----------|-----------|------------------------|
| FIPS 203 | ML-KEM (Kyber) | Encapsulamento de chaves - estabelece com segurança uma chave AES por mensagem |
| N/A | AES-256-GCM | Criptografia autenticada simétrica do payload do registro |
| N/A | X25519 ECDH | Acordo de chaves clássico para defesa em profundidade em modo híbrido |

## Funcionalidades

- **Criptografia/descriptografia transparente** - nenhuma alteração no lado do cliente é necessária
- **ML-KEM-512, ML-KEM-768 (padrão), ML-KEM-1024** conjuntos de parâmetros
- **Modo híbrido** (padrão) - combina ML-KEM + X25519 ECDH para que ambos precisem ser quebrados
- **Criptografia por registro** - cada registro recebe uma nova encapsulação KEM + IV aleatório
- **Filtragem de tópicos** - padrões regex selecionam quais tópicos criptografar
- **Detecção de violação** - criptografia autenticada AES-GCM rejeita texto cifrado modificado
- **Segurança semântica** - textos simples idênticos produzem textos cifrados diferentes (IND-CCA2)
- **Geração automática de chaves** - gera e salva chaves ML-KEM na primeira inicialização se ausentes
- **Cabeçalho `x-pqc-encrypted`** - marca registros criptografados para conscientização downstream
- **Provedores de chaves plugáveis** - `KeyProvider` SPI suporta backends de sistema de arquivos (padrão) e HashiCorp Vault

## Pré-requisitos

| Requisito | Versão |
|-------------|---------|
| JDK | 17+ (21+ recomendado) |
| Maven | 3.8+ |
| Kroxylicious | 0.19.0 |
| Apache Kafka | 3.9.x |

## Início Rápido

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

O JAR shaded em target/kroxylicious-pqc-filter-1.0.0-SNAPSHOT.jar agrupa o Bouncy Castle para que possa ser inserido no Kroxylicious sem dependências extras.

Para incluir suporte ao provedor de chaves HashiCorp Vault, compile com o perfil vault:```bash mvn clean package -Pvault -DskipTests

Isso agrupa `spring-vault-core` e o `VaultKeyProvider` no JAR.

### 2. Gerar chaves 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/

Saída:``` 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 os caminhos das chaves na configuração e o filtro gerará
chaves automaticamente na primeira inicialização.

### 3. Configurar o Kroxylicious

Adicione o filtro à sua configuração YAML do 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. Implantar

Coloque o JAR em um diretório acessível ao Kroxylicious e adicione-o ao classpath através da variável de ambiente KROXYLICIOUS_CLASSPATH:```bash export KROXYLICIOUS_CLASSPATH="/opt/kroxylicious/plugins/*"

Ao usar Docker, defina-o no ambiente do seu container:```yaml
environment:
  KROXYLICIOUS_CLASSPATH: /opt/kroxylicious/plugins/*

Em seguida, inicie o proxy. Produtores e consumidores conectam-se à porta do proxy em vez de diretamente ao broker.

Referência de Configuração

Propriedade	Tipo	Obrigatório	Padrão	Descrição
kemAlgorithm	enum	Não	ML_KEM_768	Conjunto de parâmetros ML-KEM. Um de ML_KEM_512, ML_KEM_768, ML_KEM_1024.
hybridMode	boolean	Não	true	Combina ML-KEM com X25519 ECDH para defesa em profundidade.
publicKeyPath	string	Apenas sistema de arquivos	-	Caminho no sistema de arquivos para a chave pública ML-KEM (codificada em X.509 DER).
privateKeyPath	string	Apenas sistema de arquivos	-	Caminho no sistema de arquivos para a chave privada ML-KEM (codificada em PKCS#8 DER).
topicPatterns	list<string>	Não	[".*"]	Padrões regex Java. Apenas registros em tópicos correspondentes são criptografados/descriptografados.
keyProviderType	string	Não	filesystem	Backend de armazenamento de chaves. Um de filesystem, vault.
keyProviderConfig	map<string, string>	Apenas Vault	{}	Configuração específica do backend (veja a seção Vault abaixo).

Provedores de Chave

Sistema de Arquivos (keyProviderType: filesystem, padrão): Carrega chaves ML-KEM de arquivos DER no disco. Se os arquivos não existirem, gera um novo par de chaves e os salva. Requer publicKeyPath e privateKeyPath.

HashiCorp Vault (keyProviderType: vault, requer compilação -Pvault): Obtém chaves ML-KEM de um mecanismo de segredos KV v2 do Vault. As chaves são armazenadas como DER codificada em base64 nos campos publicKey e privateKey. As versões dos segredos do Vault mapeiam para IDs de chave para suporte a rotação de chaves.

Propriedades keyProviderConfig do Vault:

Propriedade	Obrigatório	Padrão	Descrição
vaultAddress	Sim	Variável de ambiente VAULT_ADDR	URL do servidor Vault (ex.: http://vault:8200)
vaultToken	Para autenticação token	Variável de ambiente VAULT_TOKEN	Token de autenticação do Vault
secretPath	Sim	--	Caminho dentro do mecanismo de segredos (ex.: kroxylicious/pqc)
secretEngine	Não	secret	Nome do ponto de montagem do mecanismo de segredos KV v2
authMethod	Não	token	Método de autenticação: token, approle ou kubernetes
roleId	Para approle	--	ID da função AppRole
secretId	Para approle	--	ID do segredo AppRole
kubeRole	Para kubernetes	--	Nome da função de autenticação Kubernetes
kubeTokenPath	Não	/var/run/secrets/.../token	Caminho do arquivo de token da conta de serviço