## Зачем нужен PQC для Kafka?

Классические алгоритмы установки ключей (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`** — помечает зашифрованные записи для информирования нижестоящих компонентов
- **Подключаемые поставщики ключей** — SPI `KeyProvider` поддерживает файловую систему (по умолчанию) и бэкенды 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

Добавьте фильтр в YAML-конфигурацию вашего прокси 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

При использовании Docker задайте его в среде вашего контейнера:```yaml
environment:
  KROXYLICIOUS_CLASSPATH: /opt/kroxylicious/plugins/*

### Параметры наборов ML-KEM

| Алгоритм | Уровень безопасности | Открытый ключ | Закрытый ключ | Накладные расходы на шифртекст | Вариант использования |
|-----------|---------------|------------|-------------|--------------------:|----------|
| ML-KEM-512 | 128-бит | 822 Б | 1 730 Б | ~854 Б | Лёгкий, IoT |
| ML-KEM-768 | 192-бит | 1 206 Б | 2 498 Б | ~1 174 Б | **Рекомендуемый по умолчанию** |
| ML-KEM-1024 | 256-бит | 1 590 Б | 3 266 Б | ~1 654 Б | Секретные / долгоживущие данные |

### Режимы шифрования

**Только 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 действует как идентификатор ключа, обеспечивая ротацию ключей. Новые версии
шифруют новые записи; старые версии по-прежнему могут расшифровывать записи, зашифрованные с их помощью.

#### Порядок запуска```
┌─────────────────────────────────────────────────────────────────────┐
│                           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`** разрешает `KeyProvider` через `ServiceLoader`, сопоставляя по
`keyProviderType`. Делегирует все операции с ключами разрешённому провайдеру.

**`KeyProvider`** — это SPI-интерфейс для подключаемых бэкендов хранения ключей.
Реализации обнаруживаются через `META-INF/services`. Встроенные провайдеры:
`FileSystemKeyProvider` (по умолчанию) и `VaultKeyProvider` (с `-Pvault`).

**`PqcEncryptionConfig`** — это POJO с Jackson-аннотациями.
Десериализуется из блока `config:` в YAML-конфигурации прокси Kroxylicious.
Поддерживает `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