## لماذا PQC لكافكا؟

خوارزميات التأسيس الكلاسيكية للمفاتيح (RSA، ECDH) معرّضة لأجهزة الكمبيوتر الكمومية المستقبلية. إذا تم تأسيس مفاتيح تشفير لكل سجل باستخدام آلية تغليف مفاتيح كلاسيكية (KEM)، فإن خصماً كمومياً قد يتمكن من استعادة هذه المفاتيح من التغليفات المخزّنة بجانب النص المشفر على الوسيط (broker).

يستخدم هذا الملحق ML-KEM (FIPS 203) لتغليف المفاتيح المقاوم للكموم، مما يضمن عدم قدرة أي خصم يمتلك حاسوباً كمومياً ذا أهمية تشفيرية على فك تشفير البيانات المخزّنة على وسيط كافكا (Kafka broker).

**ملاحظة:** يحمي هذا الفلتر **البيانات المخزّنة على الوسيط**، وليس قناة TLS أثناء النقل. راجع [THREAT_MODEL.md](https://github.com/oscerd/kroxylicious-pqc-filter/blob/main/THREAT_MODEL.md) للحصول على تحليل كامل لما يتم الدفاع عنه وما لا يتم الدفاع عنه.

| Standard | Algorithm | Purpose in this plugin |
|----------|-----------|------------------------|
| 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 عشوائي
- **تصفية المواضيع** - أنماط regex تختار المواضيع التي سيتم تشفيرها
- **كشف العبث** - تشفير AES-GCM الموثّق يرفض النص المشفر المعدّل
- **الأمان الدلالي** - النصوص الواضحة المتطابقة تنتج نصوصًا مشفرة مختلفة (IND-CCA2)
- **التوليد التلقائي للمفاتيح** - يولّد ويحفظ مفاتيح ML-KEM عند أول تشغيل إذا كانت غائبة
- **ترويسة `x-pqc-encrypted`** - تعلّم السجلات المشفرة لتوعية الأنظمة النهائية
- **موفرو مفاتيح قابلون للتوصيل** - يدعم `KeyProvider` SPI أنظمة الملفات (الافتراضي) والخلفيات HashiCorp Vault

## المتطلبات الأساسية

| Requirement | Version |
|-------------|---------|
| 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

This bundles `spring-vault-core` and the `VaultKeyProvider` into the 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-bit | 822 B | 1,730 B | ~854 B | خفيف الوزن، إنترنت الأشياء |
| 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-only** (`hybridMode: false`):
يستخدم ML-KEM حصريًا. يتم اشتقاق مفتاح AES-256 من السر المشترك لـ ML-KEM
عبر `SHA-256(0x01 || "kroxylicious-pqc-v1" || secret)`.

**Hybrid** (`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`):

| Field | Content | Format |
|-------|---------|--------|
| `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