Kroxylicious PQC Record Encryption Filter

مكوّن إضافي لمرشّح 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

## لماذا 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

يُجمّع ملف JAR المُظلَّل (shaded JAR) عند target/kroxylicious-pqc-filter-1.0.0-SNAPSHOT.jar مكتبة Bouncy Castle داخله، بحيث يمكن وضعه مباشرة في Kroxylicious دون أي تبعيات إضافية.

لتضمين دعم مزوّد مفاتيح HashiCorp Vault، قم بالبناء باستخدام ملف التعريف vault:```bash mvn clean package -Pvault -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/

المخرجات:``` 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

أضف الفلتر إلى إعدادات 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

4. النشر

ضع ملف JAR في دليل يمكن الوصول إليه من Kroxylicious وأضفه إلى classpath عبر متغير البيئة 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>	لا	[".*"]	أنماط regex في Java. فقط السجلات في المواضيع المتطابقة يتم تشفيرها/فك تشفيرها.
keyProviderType	string	لا	filesystem	الواجهة الخلفية لتخزين المفاتيح. أحد الخيارات filesystem، vault.
keyProviderConfig	map<string, string>	Vault فقط	{}	إعدادات خاصة بالواجهة الخلفية (انظر قسم Vault أدناه).

مزوّدو المفاتيح

نظام الملفات (keyProviderType: filesystem، الافتراضي): يحمل مفاتيح ML-KEM من ملفات DER على القرص. إذا لم تكن الملفات موجودة، يقوم بإنشاء زوج مفاتيح جديد وحفظها. يتطلب publicKeyPath و privateKeyPath.

HashiCorp Vault (keyProviderType: vault، يتطلب بناء -Pvault): يجلب مفاتيح ML-KEM من محرك أسرار KV v2 في Vault. تُخزَّن المفاتيح بصيغة DER مشفّرة بـ base64 في حقلي publicKey و privateKey. ترتبط إصدارات أسرار Vault بمعرّفات المفاتيح لدعم تدوير المفاتيح.

خصائص keyProviderConfig الخاصة بـ Vault:

الخاصية	مطلوب	الافتراضي	الوصف
vaultAddress	نعم	VAULT_ADDR متغير بيئة	عنوان URL لخادم Vault (مثل http://vault:8200)
vaultToken	لمصادقة token	VAULT_TOKEN متغير بيئة	رمز مصادقة Vault
secretPath	نعم	--	المسار داخل محرك الأسرار (مثل kroxylicious/pqc)
secretEngine	لا	secret	اسم نقطة التحميل لمحرك أسرار KV v2
authMethod	لا	token	طريقة المصادقة: token، approle، أو kubernetes
roleId	لـ approle	--	معرّف دور AppRole
secretId	لـ approle	--	معرّف سر AppRole
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-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)`.