Kroxylicious PQC レコード暗号化フィルター

Kroxylicious フィルタープラグイン。透過的な 耐量子暗号 (PQC) レコードレベル暗号化を Apache Kafka 向けに提供し、 ML-KEM (FIPS 203) 鍵カプセル化と AES-256-GCM 対称暗号化を使用します。

Kafka プロデューサーとコンシューマーは コード変更が一切不要 です。Kroxylicious プロキシが トラフィックをインターセプトし、Produce 時に暗号化し、Fetch 時に自動的に復号化します。``` Producer ──plaintext──> Kroxylicious ──encrypted──> Kafka Broker Consumer <──plaintext── Kroxylicious <──encrypted── Kafka Broker

## Kafka に PQC を使う理由

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

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

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

target/kroxylicious-pqc-filter-1.0.0-SNAPSHOT.jar にあるシャドーJAR は、Bouncy Castle をバンドルしているため、追加の依存関係なしで Kroxylicious にそのまま配置できます。

HashiCorp Vault キープロバイダーのサポートを含めるには、vault プロファイルでビルドします:```bash mvn clean package -Pvault -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/

I'm ready to translate chunk 9 of 33, but the input content appears to be empty. Please provide the Markdown text you'd like me to translate into Japanese.``` 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

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

### 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

4. デプロイ

Kroxylicious がアクセスできるディレクトリに JAR を配置し、それを KROXYLICIOUS_CLASSPATH 環境変数経由でクラスパスに追加します:```bash export KROXYLICIOUS_CLASSPATH="/opt/kroxylicious/plugins/*"

Dockerを使用する場合は、コンテナ環境で設定してください:```yaml
environment:
  KROXYLICIOUS_CLASSPATH: /opt/kroxylicious/plugins/*

次にプロキシを起動します。プロデューサーとコンシューマーは、プロキシポートに接続します。 ブローカーに直接接続するのではなく。

設定リファレンス

プロパティ	型	必須	デフォルト	説明
kemAlgorithm	enum	いいえ	ML_KEM_768	ML-KEM パラメータセット。ML_KEM_512、ML_KEM_768、ML_KEM_1024 のいずれか。
hybridMode	boolean	いいえ	true	ML-KEM と X25519 ECDH を組み合わせて多層防御を実現します。
publicKeyPath	string	ファイルシステムのみ	-	ML-KEM 公開鍵（X.509 DER エンコード）へのファイルシステムパス。
privateKeyPath	string	ファイルシステムのみ	-	ML-KEM 秘密鍵（PKCS#8 DER エンコード）へのファイルシステムパス。
topicPatterns	list<string>	いいえ	[".*"]	Java 正規表現パターン。一致するトピックのレコードのみが暗号化/復号化されます。
keyProviderType	string	いいえ	filesystem	鍵ストレージバックエンド。filesystem、vault のいずれか。
keyProviderConfig	map<string, string>	Vault のみ	{}	バックエンド固有の設定（下記の Vault セクションを参照）。

鍵プロバイダー

ファイルシステム（keyProviderType: filesystem、デフォルト）: ディスク上の DER ファイルから ML-KEM 鍵を読み込みます。ファイルが存在しない場合は、 新しい鍵ペアを生成して保存します。publicKeyPath と privateKeyPath が必要です。

HashiCorp Vault（keyProviderType: vault、-Pvault ビルドが必要）: Vault KV v2 シークレットエンジンから ML-KEM 鍵を取得します。鍵は、 publicKey および privateKey フィールドに base64 エンコードされた DER として保存されます。Vault のシークレットバージョンは、 鍵ローテーションをサポートするために鍵 ID にマッピングされます。

Vault の keyProviderConfig プロパティ:

プロパティ	必須	デフォルト	説明
vaultAddress	はい	VAULT_ADDR 環境変数	Vault サーバーの URL（例：http://vault:8200）
vaultToken	token 認証の場合	VAULT_TOKEN 環境変数	Vault 認証トークン
secretPath	はい	--	シークレットエンジン内のパス（例：kroxylicious/pqc）
secretEngine	いいえ	secret	KV v2 シークレットエンジンのマウント名
authMethod	いいえ	token	認証方式：token、approle、kubernetes のいずれか
roleId	approle の場合	--	AppRole ロール ID
secretId	approle の場合	--	AppRole シークレット ID
kubeRole	kubernetes の場合	--	Kubernetes 認証ロール名
kubeTokenPath	いいえ	/var/run/secrets/.../token	サービスアカウントトークンファイルのパス

Vault 設定の例:```yaml filterDefinitions:

• name: pqc-encryption type: PqcRecordEncryptionFilterFactory config: kemAlgorithm: ML_KEM_768 hybridMode: false keyProviderType: vault keyProviderConfig: vaultAddress: http://vault:8200 vaultToken: my-token secretPath: kroxylicious/pqc topicPatterns: - "sensitive-.*"

### 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 |        |                 |
+--------+-----------+--------------------+---------+--------+-----------------+

バージョンバイトにより、復号化ツールは設定なしでモードを判別できます。

アーキテクチャ