## 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-bit | 822 B | 1,730 B | ~854 B | 경량, IoT |
| ML-KEM-768 | 192-bit | 1,206 B | 2,498 B | ~1,174 B | **권장 기본값** |
| ML-KEM-1024 | 256-bit | 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 역할을 하여 키 순환(rotation)을 지원합니다. 새 버전은 새 레코드를 암호화하고, 이전 버전은 해당 버전으로 암호화된 레코드를 여전히 복호화할 수 있습니다.

#### 시작 흐름```
┌─────────────────────────────────────────────────────────────────────┐
│                           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()`는 자체 설명형 봉투(self-describing envelope)를 반환하고, `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