## 为什么要为 Kafka 使用 PQC？

经典密钥建立算法（RSA、ECDH）容易受到未来量子计算机的攻击。如果使用经典 KEM 建立每条记录的加密密钥，量子对手可以从存储在 broker 上、与密文一起保存的封装数据中恢复出这些密钥。

该插件使用 ML-KEM（FIPS 203）进行抗量子密钥封装，确保即使对手拥有具备密码学相关能力的量子计算机，也无法解密 Kafka broker 上的静态数据。

**注意：** 此过滤器保护的是 **broker 上的静态数据**，而不是传输中的 TLS 信道。有关哪些攻击受到防御、哪些未受到防御的完整分析，请参阅 [THREAT_MODEL.md](https://github.com/oscerd/kroxylicious-pqc-filter/blob/HEAD/THREAT_MODEL.md)。

| Standard | Algorithm | 本插件中的用途 |
|----------|-----------|------------------------|
| FIPS 203 | ML-KEM (Kyber) | 密钥封装——安全地为每条消息建立 AES 密钥 |
| N/A | AES-256-GCM | 记录负载的对称认证加密 |
| N/A | X25519 ECDH | 用于混合模式纵深防御的经典密钥协商 |

## 功能特性

- **透明加解密** - 无需客户端修改
- **ML-KEM-512、ML-KEM-768（默认）、ML-KEM-1024** 参数集
- **混合模式**（默认）- 结合 ML-KEM + X25519 ECDH，两者都必须被破解
- **每条记录加密** - 每条记录获得全新的 KEM 封装和随机 IV
- **主题过滤** - 通过正则表达式选择要加密的主题
- **篡改检测** - AES-GCM 认证加密可拒绝被修改的密文
- **语义安全** - 相同明文产生不同密文（IND-CCA2）
- **密钥自动生成** - 首次启动时若缺少 ML-KEM 密钥，将自动生成并保存
- **`x-pqc-encrypted` 标头** - 标记加密记录，供下游感知
- **可插拔密钥提供者** - `KeyProvider` SPI 支持文件系统（默认）和 HashiCorp Vault 后端

## 先决条件

| 要求 | 版本 |
|-------------|---------|
| JDK | 17+ (21+ recommended) |
| Maven | 3.8+ |
| Kroxylicious | 0.19.0 |
| Apache Kafka | 3.9.x |

## 快速开始

### 1. 构建插件```bash
git clone <this-repo>
cd kroxylicious-pqc-filter
mvn clean package -DskipTests

This bundles `spring-vault-core` and the `VaultKeyProvider` into the JAR.

### 2. Generate ML-KEM keys```bash
java -cp target/kroxylicious-pqc-filter-1.0.0-SNAPSHOT.jar \
  io.kroxylicious.filter.pqc.PqcKeyGeneratorCli \
  ML_KEM_768 \
  /etc/kroxylicious/pqc/

或者，在配置中省略密钥路径，过滤器将在首次启动时自动生成密钥。

### 3. 配置 Kroxylicious

将过滤器添加到你的 Kroxylicious 代理 YAML 配置中：```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

使用 Docker 时，请在容器环境中设置：```yaml
environment:
  KROXYLICIOUS_CLASSPATH: /opt/kroxylicious/plugins/*

### ML-KEM 参数集

| 算法 | 安全级别 | 公钥 | 私钥 | 密文开销 | 用例 |
|-----------|---------------|------------|-------------|--------------------:|----------|
| ML-KEM-512 | 128 位 | 822 B | 1,730 B | ~854 B | 轻量级、物联网 |
| ML-KEM-768 | 192 位 | 1,206 B | 2,498 B | ~1,174 B | **推荐默认** |
| ML-KEM-1024 | 256 位 | 1,590 B | 3,266 B | ~1,654 B | 涉密/长期数据 |

### 加密模式

**纯 PQC**（`hybridMode: false`）：
仅使用 ML-KEM。AES-256 密钥由 ML-KEM 共享秘密通过
`SHA-256(0x01 || "kroxylicious-pqc-v1" || secret)` 派生。

**混合模式**（`hybridMode: true`，默认）：
结合 ML-KEM + X25519。AES-256 密钥由两个秘密通过
`SHA-256(0x02 || "kroxylicious-pqc-hybrid-v1" || pqcSecret || x25519Secret)` 派生。
即使其中一种算法被攻破，也能确保安全性。

## 加密信封格式

每个加密的记录值都会被替换为二进制信封：```
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 |        |                 |
+--------+-----------+--------------------+---------+--------+-----------------+

### 数据流

#### Vault 中存储的内容

Vault KV v2 在 `secret/<secretPath>`（例如 `secret/kroxylicious/pqc`）中保存 ML-KEM 密钥对：

| 字段 | 内容 | 格式 |
|-------|---------|--------|
| `publicKey` | ML-KEM 公钥（用于封装） | Base64 编码的 X.509 DER |
| `privateKey` | ML-KEM 私钥（用于解封装） | Base64 编码的 PKCS#8 DER |

每个 Vault secret 版本都充当一个密钥 ID，支持密钥轮换。新版本
加密新记录；旧版本仍可解密用它们加密的记录。

#### 启动流程```
┌─────────────────────────────────────────────────────────────────────┐
│                           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)
                    ┌───────────────────────────────────────────┐

#### 获取流程（解密）```
                                  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)

### 关键类

**`PqcRecordEncryptionFilterFactory`** 实现 `FilterFactory<PqcEncryptionConfig, SharedPqcContext>`。
使用 `@Plugin(configType = PqcEncryptionConfig.class)` 进行注解。
通过 `META-INF/services/io.kroxylicious.proxy.filter.FilterFactory` 注册。
在启动时调用一次（`initialize`），每个客户端连接调用一次（`createFilter`）。

**`PqcRecordEncryptionFilter`** 实现 `ProduceRequestFilter` 和 `FetchResponseFilter`。
拦截 `onProduceRequest` 进行加密，拦截 `onFetchResponse` 进行解密。
每个连接一个实例；无需同步（Kroxylicious 线程模型）。

**`PqcCryptoEngine`** 执行所有密码学操作。
除密钥材料和 `SecureRandom` 外无状态。
`encrypt()` 返回自描述信封；`decrypt()` 解析该信封。
在静态初始化器中注册 Bouncy Castle 提供者（`BC`、`BCPQC`）。

**`PqcKeyManager`** 通过 `ServiceLoader` 解析 `KeyProvider`，依据
`keyProviderType` 进行匹配。将所有密钥操作委托给已解析的提供者。

**`KeyProvider`** 是可插拔密钥存储后端的 SPI 接口。
实现通过 `META-INF/services` 发现。内置提供者：
`FileSystemKeyProvider`（默认）和 `VaultKeyProvider`（使用 `-Pvault`）。

**`PqcEncryptionConfig`** 是 Jackson 注解的 POJO。
从 Kroxylicious 代理 YAML 的 `config:` 块中反序列化。
支持 `keyProviderType` 和 `keyProviderConfig` 用于后端选择。

## 构建与测试```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