## Kafka に PQC を使う理由

古典的な鍵確立アルゴリズム（RSA、ECDH）は、将来の量子コンピュータに対して脆弱です。レコード単位の暗号化鍵を古典的な KEM で確立すると、量子敵対者はブローカー上で暗号文と共に保存されたカプセル化データからその鍵を回復できてしまいます。

このプラグインは、量子耐性のある鍵カプセル化に ML-KEM（FIPS 203）を使用し、暗号学的に関連する量子コンピュータを持つ敵対者であっても、Kafka ブローカー上の保存データを復号できないようにします。

**注記:** このフィルタは、ブローカー上の**保存データ**を保護するものであり、転送中の TLS チャネルを保護するものではありません。防御対象とその範囲外の完全な分析については、[THREAT_MODEL.md](https://github.com/oscerd/kroxylicious-pqc-filter/blob/HEAD/THREAT_MODEL.md) を参照してください。

| 標準 | アルゴリズム | このプラグインでの用途 |
|----------|-----------|------------------------|
| 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+ 推奨） |
| 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

これは `spring-vault-core` と `VaultKeyProvider` を JAR にバンドルします。

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

または、設定内のキーパスを省略すると、初回起動時にフィルタが自動的にキーを生成します。

### 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 | 軽量、IoT |
| 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は、ML-KEM鍵ペアを `secret/<secretPath>`（例: `secret/kroxylicious/pqc`）に保持します:

| フィールド | 内容 | 形式 |
|-------|---------|--------|
| `publicKey` | ML-KEM公開鍵（カプセル化に使用） | Base64エンコードされたX.509 DER |
| `privateKey` | ML-KEM秘密鍵（脱カプセル化に使用） | Base64エンコードされたPKCS#8 DER |

各Vaultシークレットバージョンは鍵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` を介して登録されます。
起動時に1回 (`initialize`)、クライアント接続ごとに1回 (`createFilter`) 呼び出されます。

**`PqcRecordEncryptionFilter`** は `ProduceRequestFilter` と `FetchResponseFilter` を実装します。
`onProduceRequest` をインターセプトして暗号化し、`onFetchResponse` をインターセプトして復号化します。
接続ごとに1つのインスタンスが作成されます。同期は不要です (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