mlkem-native

mlkem-native هو تنفيذ آمن وسريع وقابل للنقل بلغة C90¹ لمعيار ML-KEM². وهو مشتق من التنفيذ المرجعي لـ ML-KEM³.

جميع أكواد C في mlkem/src/* و mlkem/src/fips202/* مُثبتة أنها آمنة من حيث الذاكرة (بدون تجاوز للذاكرة) وآمنة من حيث الأنواع (بدون تجاوز للأعداد الصحيحة) باستخدام CBMC⁴. جميع أكواد التجميع (assembly) لمعماريّتي AArch64 و x86_64 مُثبتة أنها صحيحة وظيفيًا، وآمنة من حيث الذاكرة، وذات توقيت مستقل عن الأسرار (ثابت الزمن)، باستخدام HOL-Light⁵.

يتضمن mlkem-native واجهات خلفية أصلية لمعمارية Arm (64-بت، Neon)، وIntel/AMD (64-بت، AVX2)، وRISC-V (64-بت، RVV)، وPOWER (ppc64le، VSX). راجع المعايير لبيانات الأداء.

mlkem-native مدعوم من تحالف التشفير ما بعد الكمي كجزء من مؤسسة Linux.

بدء سريع لـ Ubuntu

# تثبيت الحزم الأساسية
sudo apt-get update
sudo apt-get install make gcc python3 git

# استنساخ mlkem-native
git clone https://github.com/pq-code-package/mlkem-native.git
cd mlkem-native

# البناء وتشغيل الاختبارات
make build
make test

# نفس الأمر باستخدام `tests`، وهو غلاف ملائم حول `make`
./scripts/tests all
# عرض جميع الخيارات
./scripts/tests --help

راجع BUILDING.md لمزيد من المعلومات.

التطبيقات

يُستخدم mlkem-native في

• libOQS من مشروع Open Quantum Safe منذ 0.13.0 (كتنفيذ ML-KEM الافتراضي)
• مكتبة التشفير الخاصة بـ AWS AWS-LC منذ v1.50.0
• مكتبة TLS rustls المكتوبة بلغة Rust منذ 0.23.28 (عبر AWS-LC كمزوّد التشفير الافتراضي)
• Pavona - مكتبة من الكتل السيليكونية المفتوحة المعيارية والمُثبتة على مستوى التصنيع والآمنة افتراضيًا

التحقق الرسمي

جميع أكواد C في mlkem/src/* و mlkem/src/fips202/* مُثبتة أنها آمنة من حيث الذاكرة (بدون تجاوز للذاكرة) وآمنة من حيث الأنواع (بدون تجاوز للأعداد الصحيحة). يستخدم هذا المُدقّق النموذجي المحدود C (CBMC) ويستند إلى عقود الدوال وتعليقات حلقات الثبات (loop invariants) في الكود المصدري. راجع proofs/cbmc للتفاصيل.

جميع أكواد التجميع لمعماريّتي AArch64 و x86_64 مُثبتة أنها صحيحة وظيفيًا، وآمنة من حيث الذاكرة، وذات توقيت مستقل عن الأسرار (ثابت الزمن)، على مستوى كود الكائن. يستخدم هذا مُثبِت النظريات التفاعلي HOL-Light والبنية التحتية للتحقق s2n-bignum (التي تتضمن نماذج للأجزاء ذات الصلة من معماريّتي Arm و x86). راجع proofs/hol_light للتفاصيل.

ملاحظة: التحقق الرسمي ليس مطلقًا أبدًا. راجع SOUNDNESS.md لتحليل مفصّل لنطاق وافتراضات ومخاطر جهود التحقق الرسمي حول mlkem-native.

الأمان

جميع أكواد التجميع لمعماريّتي AArch64 و x86_64 في mlkem-native مُثبتة رسميًا في HOL Light أنها خالية من تدفق التحكم المعتمد على الأسرار، وأنماط الوصول إلى الذاكرة، والتعليمات ذات زمن الاستجابة المتغير، مما يحبط معظم القنوات الجانبية الزمنية (راجع proofs/hol_light للتفاصيل). كود C مُحصّن ضد القنوات الجانبية الزمنية التي يُدخلها المترجم (مثل KyberSlash⁶ أو clangover⁷) من خلال حواجز مناسبة وأنماط ثابتة الزمن.

يتم أيضًا اختبار غياب الفروع المعتمدة على الأسرار، وأنماط الوصول إلى الذاكرة، والتعليمات ذات زمن الاستجابة المتغير باستخدام valgrind مع مجموعات مختلفة من المترجمين وخيارات الترجمة.

هجمات أخرى. يستهدف mlkem-native مقاومة القنوات الجانبية الزمنية فقط. فئات الهجمات الأخرى، مثل القنوات الجانبية للطاقة والكهرومغناطيسية، والقنوات الجانبية المعمارية الدقيقة (مثل التنفيذ التخميني)، أو هجمات حقن الأخطاء، خارج النطاق حاليًا.

التصميم

ينقسم mlkem-native إلى واجهة أمامية و_واجهتين خلفيتين_ للحساب و FIPS202 / SHA3. الواجهة الأمامية ثابتة، مكتوبة بلغة C، وتغطي جميع الإجراءات غير الحرجة للأداء. الواجهات الخلفية مرنة، وتتولى الإجراءات الحساسة للأداء، ويمكن تنفيذها بلغة C أو كود أصلي (تجميع/تعليمات داخلية)؛ راجع mlkem/src/native/api.h للواجهة الخلفية الحسابية و mlkem/src/fips202/native/api.h للواجهة الخلفية FIPS-202.

يوفّر mlkem-native حاليًا الواجهات الخلفية التالية:

• الواجهة الخلفية الافتراضية المحمولة بلغة C
• واجهة خلفية لمعمارية Arm 64-بت (باستخدام Neon)
• واجهة خلفية لمعمارية Intel/AMD 64-بت (باستخدام AVX2)
• واجهة خلفية لمعمارية RISC-V 64-بت (باستخدام RVV)
• واجهة خلفية لمعمارية POWER 64-بت (ppc64le، باستخدام VSX؛ تدعم POWER8 وما فوق)
• واجهة خلفية لمعمارية Armv8.1-M 32-بت (باستخدام Helium/MVE) -- راجع #1501. لا تزال هذه الواجهة تجريبية ومعطّلة افتراضيًا.

إذا كنت ترغب في المساهمة بواجهات خلفية جديدة، يرجى التواصل أو فتح طلب سحب (PR).

تم تطوير كود التجميع الخاص بنا لمعمارية AArch64 باستخدام المُحسِّن الفائق SLOTHY، باتباع النهج الموصوف في ورقة SLOTHY⁸: نكتب كود التجميع "النظيف" يدويًا ونؤتمت التحسينات الدقيقة (على سبيل المثال، راجع النظيف مقابل المُحسَّن لـ AArch64 NTT). راجع dev/README.md لمزيد من التفاصيل.

متجهات الاختبار

يتم اختبار mlkem-native ضد جميع متجهات اختبار ACVP الرسمية لـ ML-KEM⁹ ومتجهات اختبار Wycheproof¹⁰ لـ ML-KEM.

ACVP

يمكنك تشغيل اختبارات ACVP باستخدام سكربت tests أو عميل ACVP مباشرة:

# باستخدام سكربت الاختبارات
./scripts/tests acvp
# باستخدام إصدار ACVP محدد
./scripts/tests acvp --version v1.1.0.41

# باستخدام عميل ACVP مباشرة
python3 ./test/acvp/acvp_client.py
python3 ./test/acvp/acvp_client.py --version v1.1.0.41

# باستخدام ملفات متجهات اختبار ACVP محددة (تم تنزيلها من خادم ACVP)
# python3 ./test/acvp/acvp_client.py -p {PROMPT}.json -e {EXPECTED_RESULT}.json
# على سبيل المثال، بافتراض أنك قمت بتشغيل ما سبق
python3 ./test/acvp/acvp_client.py \
  -p ./test/acvp/.acvp-data/v1.1.0.41/files/ML-KEM-keyGen-FIPS203/prompt.json \
  -e ./test/acvp/.acvp-data/v1.1.0.41/files/ML-KEM-keyGen-FIPS203/expectedResults.json

Wycheproof

يمكنك تشغيل اختبارات Wycheproof¹⁰ باستخدام سكربت tests أو عميل Wycheproof مباشرة:

# باستخدام سكربت الاختبارات
./scripts/tests wycheproof

# باستخدام عميل Wycheproof مباشرة
python3 ./test/wycheproof/wycheproof_client.py

قياس الأداء

يمكنك قياس الأداء واستخدام الذاكرة وحجم الملف الثنائي باستخدام سكربت tests:

# معايير السرعة (-c تحدد عداد الدورة: NO، PMU، PERF، أو MAC)
# ملاحظة: قد يتطلب PERF/MAC علامة -r لتشغيل ملفات قياس الأداء الثنائية باستخدام sudo
./scripts/tests bench -c PMU
./scripts/tests bench -c PERF -r

# تحليل استخدام المكدس
./scripts/tests stack

# قياس حجم الملف الثنائي
./scripts/tests size

لنتائج معايير CI وبيانات الأداء التاريخية، راجع صفحة قياس الأداء.

الاستخدام

إذا كنت تريد استخدام mlkem-native، فاستورد mlkem إلى شجرة المصدر لمشروعك وقم بالبناء باستخدام نظام البناء المفضل لديك. راجع mlkem لمزيد من المعلومات، و examples/basic للحصول على مثال بسيط. نظام البناء المقدم في هذا المستودع مخصص لأغراض التطوير فقط.

راجع API-CONVENTIONS.md للاتفاقيات المطبقة على جميع الدوال العامة، مثل قيم الإرجاع، وصحة المؤشرات، وحالة مخازن الإخراج عند الخطأ.

هل يمكنني استخدام FIPS-202 الخاص بي؟

يعتمد mlkem-native على تنفيذ FIPS-202¹¹ ويأتي معه. إذا كانت مكتبتك تحتوي على تنفيذ FIPS-202 خاص بها، يمكنك استخدامه بدلاً من التنفيذ المرفق مع mlkem-native. راجع FIPS202.md، و examples/bring_your_own_fips202 للحصول على مثال يستخدم tiny_sha3¹².

هل أحتاج إلى استخدام واجهات التجميع الخلفية؟

لا. إذا كنت تريد بناء بلغة C فقط، فما عليك سوى حذف الدليلين mlkem/src/native و/أو mlkem/src/fips202/native من استيرادك وإلغاء تعيين MLK_CONFIG_USE_NATIVE_BACKEND_ARITH و/أو MLK_CONFIG_USE_NATIVE_BACKEND_FIPS202 في mlkem_native_config.h.

هل أحتاج إلى إعداد CBMC لاستخدام mlkem-native؟

لا. على الرغم من أننا نوصي بالنظر في استخدامه، فإن mlkem-native سيعمل بشكل جيد بدون CBMC -- فقط تأكد من تضمين cbmc.h وترك CBMC غير معرّف. على وجه الخصوص، لست بحاجة إلى إزالة جميع عقود الدوال وحلقات الثبات من الكود؛ سيتم تجاهلها ما لم يتم تعيين CBMC.

هل يدعم mlkem-native جميع مستويات الأمان في ML-KEM؟

نعم. مستوى الأمان هو معامل وقت الترجمة يتم تكوينه عن طريق تعيين MLK_CONFIG_PARAMETER_SET=512/768/1024 في mlkem_native_config.h. إذا كانت مكتبتك/تطبيقك يتطلب مستويات أمان متعددة، يمكنك بناء وربط ثلاث نسخ من mlkem-native مع مشاركة الكود المشترك؛ يُسمى هذا "بناء متعدد المستويات" وهو موضح في examples/multilevel_build. راجع أيضًا mlkem.

هل يمكنني استخدام واجهة خلفية خاصة بي؟

نعم، يمكنك إضافة واجهات خلفية إضافية للحساب الأصلي لـ ML-KEM و/أو لـ FIPS-202. اتبع الواجهات الخلفية الموجودة كنماذج أو راجع examples/custom_backend للحصول على مثال بسيط حول كيفية تسجيل واجهة خلفية مخصصة.

لديك سؤال؟

إذا كنت تعتقد أنك وجدت ثغرة أمنية في mlkem-native، يرجى الإبلاغ عن الثغرة من خلال الإبلاغ الخاص عن الثغرات في Github. يرجى عدم إنشاء مشكلة (issue) عامة على GitHub.

إذا كان لديك أي سؤال آخر / مشكلة غير متعلقة بالأمان / طلب ميزة، يرجى فتح مشكلة على GitHub.

المساهمة

إذا كنت تريد مساعدتنا في بناء mlkem-native، يرجى التواصل. يمكنك الاتصال بفريق mlkem-native عبر خادم PQCA على Discord. راجع أيضًا CONTRIBUTING.md.