مفتاح أمان KL

مشروع هندسي وتوافقي مفتوح المصدر تجريبي لمصادقة FIDO2/WebAuthn على RP2040 من Karaaslan Labs.

الحالة: مشروع هندسي/بحثي. غير معتمد من FIDO Alliance. ليس رمزًا أمنيًا تجاريًا عالي الضمان.

مفتاح أمان KL هو نسخة مشتقة منسّقة من polhenarejos/pico-fido. يستكشف إلى أي مدى يمكن دفع لوحة RP2040 منخفضة التكلفة لتكون مصادق WebAuthn فعليًا مع الحفاظ على الهوية والإثبات وأدلة التحقق وحدود الثقة واضحة وصريحة.

نظرة سريعة

المجال	المرجع الهندسي الحالي
العتاد	لوحة تطوير RP2040 USB
النقل	USB FIDO HID
إصدارات CTAP/GetInfo	FIDO_2_0، FIDO_2_1، FIDO_2_3
حضور المستخدم / التحقق	زر فعلي + دعم PIN/UV
الإثبات	Packed ES256، x5c، شهادة خاصة بالجهاز
AAGUID	d9359dc7-6938-5822-b951-006507247d8f
التوافقية	Windows WebAuthn + تحقق Microsoft Entra محلي للمستأجر
التوزيع	المصدر أولًا؛ لا يوجد إصدار ثنائي لبرنامج KL
العنصر الآمن	لا يوجد
الاعتماد	غير معتمد من FIDO Alliance

لماذا يوجد هذا المشروع

بدأ المشروع بسؤال عملي: هل يمكن للوحة تطوير غير مكلفة أن تصبح مفتاح أمان فعليًا قابلًا للاستخدام لتسجيل دخول WebAuthn حقيقي، دون إخفاء التنازلات الهندسية؟

تبيّن أن العمل المثير لم يكن مجرد تشغيل FIDO2 على RP2040. كانت الأجزاء الأصعب هي هوية المصادق، والحضور الفعلي للمستخدم، والإثبات، وسلوك Windows، والتغييرات المصدرية القابلة لإعادة الإنتاج، والتوافقية مع الأطراف المعتمدة، ومعرفة ما يثبته الدليل بالضبط — وما لا يثبته.

تم التحقق منه على المرجع الفعلي

• تسجيل WebAuthn جديد: ناجح.
• المصادقة / GetAssertion بنفس بيانات الاعتماد: ناجح.
• مزود Windows: MicrosoftCtapHidProvider.
• مسار CTAP2 تم رصده مع U2fProtocol=false.
• الحضور الفعلي للمستخدم مطلوب للتسجيل وتسجيل الدخول.
• مسار PIN/التحقق من المستخدم تم التحقق منه.
• توقيع إثبات Packed: ناجح.
• التحقق من شهادة الإثبات الطرفية → KL Security Key Root CA: ناجح.
• تطابق AAGUID بين بيانات المصادق وامتداد الشهادة: ناجح.
• التسجيل المرتبط بالجهاز محليًا في مستأجر Microsoft Entra وتسجيل الدخول الفعلي بمفتاح جديد: ناجح مع تعطيل فرض الإثبات.

نتيجة Entra هي نتيجة توافقية، وليست اعتمادًا من Microsoft أو اعترافًا عالميًا بالمصادق. راجع docs/interoperability-case-study.md للحدود الدقيقة.

البنية المعمارية

flowchart LR
    RP["Relying party / Microsoft Entra"] --> WA["Browser + Windows WebAuthn"]
    WA --> CTAP["CTAP2 over USB HID"]
    CTAP --> KEY["KL Security Key<br/>RP2040"]
    KEY --> AT["Packed ES256 attestation<br/>device-specific key + x5c"]
    AT --> ROOT["KL Security Key Root CA"]

بيئة التشغيل التي تم التحقق منها ضيقة عمدًا: FIDO HID هو واجهة مفتاح الأمان؛ واجهات التشغيل غير ذات الصلة من نوع لوحة المفاتيح/CCID ليست جزءًا من ملف تعريف مرجع KL.

بناء ملف التعريف المرجعي

git clone --recurse-submodules https://github.com/karaaslanlabs/kl-security-key.git
cd kl-security-key
export PICO_SDK_PATH=/path/to/pico-sdk
export PICO_TOOLCHAIN_PATH=/path/to/arm-none-eabi-toolchain
./scripts/build-kl-reference.sh

يُفعّل البناء فرض الحضور الفعلي للمستخدم، وملف تعريف التشغيل الخاص بـ FIDO فقط، ومسار إثبات Packed. يجب توفير مواد مفتاح/شهادة الإثبات الصالحة بشكل منفصل؛ لا يتم نشر مفاتيح الإثبات الخاصة أو توفيرها تلقائيًا بواسطة هذا المستودع.

حدود الثقة وعدم الادعاءات

هذا المستودع لا يدّعي:

• اعتماد FIDO Alliance؛
• حماية بمستوى العنصر الآمن ضد الاستخراج الفعلي للمفتاح؛
• ثقة عالمية من الأطراف المعتمدة أو إدراجًا في القوائم المسموح بها أو توافقية؛
• التكافؤ مع YubiKey أو Nitrokey أو أي بائع آخر لمفاتيح الأمان التجارية؛
• ملكية Karaaslan Labs لـ USB VID/PID الخاص بالمشروع الأصلي/المشتق؛
• اعتماد Microsoft أو اعتراف عالمي من البائعين؛
• أن النجاح على مستوى البروتوكول مع طرف معتمد واحد يثبت القبول من طرف آخر.

اقرأ THREAT-MODEL.md قبل التعامل مع المرجع على أنه أي شيء يتجاوز كونه مصادقًا هندسيًا/بحثيًا.

خريطة الوثائق

الوثيقة	الغرض
docs/architecture.md	ملف تعريف التشغيل وتخطيط المصدر والحدود الهندسية
docs/attestation-and-pki.md	AAGUID وإثبات Packed ونموذج PKI
docs/validation-evidence.md	أدلة التحقق على المرجع الفعلي والمصدر المنسّق
docs/interoperability-case-study.md	أدلة التوافقية مع الأطراف المعتمدة / Microsoft Entra وحدودها
docs/windows-webauthn-debugging.md	سير عمل تصحيح أخطاء Windows/WebAuthn المبني على الأدلة
THREAT-MODEL.md	نموذج التهديد وعدم الادعاءات الأمنية
UPSTREAM.md	المصدر الأصلي والتغييرات المشتقة
SECURITY.md	الإبلاغ عن الثغرات وسياسة الأمان

المصدر والأصل ونموذج النشر

الوحدة الفرعية pico-keys-sdk مثبّتة على commit معروف من المصدر الأصلي. تُطبَّق تغييرات SDK الخاصة بـ KL بواسطة scripts/apply-sdk-overlay.py، وهو مثبّت على commit دقيق ويفشل بشكل آمن عند وجود حالة مصدرية غير متوقعة.

هذا المستودع العام منسّق عمدًا حول مسار مرجع KL Security Key. القطع البحثية الموروثة غير ذات الصلة وأدوات الإصدار القديمة ليست جزءًا من السطح المنشور لـ KL؛ ويبقى الأصل الأصلي موثقًا في UPSTREAM.md وفي سجل Git.

التوزيع الثنائي ليس هدف النشر الأولي عمدًا طالما بقيت متطلبات هوية/توزيع USB غير محسومة. المصدر والوثائق ومنهجية التحقق هي القطع الأساسية.

شهادة جذر الإثبات العامة متاحة في certs/KL-Security-Key-Root-CA-v1.cert.pem. لا يتم نشر مفاتيح الجذر/الجهاز الخاصة أبدًا.

المساهمة والأمان

المساهمات مرحّب بها عندما تكون صغيرة وقابلة للتدقيق وصريحة بشأن التأثير الأمني. ابدأ بـ CONTRIBUTING.md. لا تفتح issue عامًا لثغرة غير مُرقّعة؛ اتبع SECURITY.md.

الترخيص وإسناد المصدر الأصلي

مفتاح أمان KL مشتق من polhenarejos/pico-fido ويستخدم polhenarejos/pico-keys-sdk. يبقى المصدر تحت رخصة GNU Affero General Public License v3.0؛ راجع LICENSE وNOTICE.md وUPSTREAM.md.

لا تدّعي Karaaslan Labs تأليف العمل الأصلي Pico FIDO / Pico Keys SDK. الإشعارات الأصلية محفوظة والتعديلات الخاصة بـ KL موثقة بشكل منفصل.

استفسارات هندسية

لاستفسارات تصحيح أخطاء WebAuthn/passkey المحدودة أو الاستفسارات الهندسية حول مصادق/إثبات FIDO2، تواصل عبر [email protected].

خدمة تصحيح أخطاء مدفوعة: https://www.upwork.com/services/product/development-it-get-expert-webauthn-passkey-and-fido2-authentication-debugging-2106330281996723797. تغطي هذه الخدمة هندسة البرمجيات/المصادقة؛ مفتاح أمان KL الفعلي غير معروض للبيع.

Karaaslan Labs: https://karaaslanlabs.com