WebAuthn TPM Portable Credentials

⚠️ إثبات مفهوم مبكر. لم يتم اختبار هذا المشروع أو تدقيقه بشكل شامل. لا تستخدمه لأي شيء يتجاوز التجارب.

مُعتمَدات WebAuthn/passkey محمولة ومدعومة بالأجهزة تعمل عبر أجهزة متعددة باستخدام TPM 2.0.

عُرفت تقليديًا أن مُعتمَدات TPM مقفلة على الجهاز الذي أنشأها. هذا المشروع يجعلها محمولة عن طريق استيراد مفتاح أصلي حتمي (مشتق من بذرة رئيسية) إلى TPM كل جهاز. يمكن لكتل المُعتمَدات المشفرة بواسطة TPM واحد أن تُحمّل وتُستخدم بواسطة أي TPM آخر مجهّز بنفس البذرة. يتم إنشاء مفاتيح التوقيع الخاصة بشكل عشوائي بواسطة TPM لكل مُعتمَدة ولا توجد مطلقًا كنص عادي خارج الجهاز.

البذرة الرئيسية مطلوبة فقط مرة واحدة لكل جهاز أثناء التجهيز. بعد ذلك، تحدث جميع العمليات التشفيرية بالكامل داخل TPM.

كيف يعمل

يلغي إضافة متصفح navigator.credentials ويوجّه مكالمات WebAuthn عبر التراسل الأصلي (native messaging) إلى خلفية Python تتواصل مباشرة مع TPM. عند التسجيل، ينشئ TPM مفتاح توقيع جديد تحت المفتاح الأصلي المحمول ويعيد كتلة مشفرة. عند المصادقة، يقوم بتحميل الكتلة مرة أخرى، وفك تشفيرها داخليًا، وتوقيع التحدي.

المتطلبات

• نظام التشغيل: Linux أو Windows (macOS لا يحتوي على TPM)
• الأجهزة: TPM 2.0
• Python: 3.10+
• المتصفح: Firefox (دعم Chrome مخطط له)

التثبيت

1. تثبيت التبعيات

Linux (Debian/Ubuntu):

sudo apt install tpm2-tools python3-tpm2-pytss python3-cryptography

Windows:

pip install cryptography

يتحدث Windows مع TPM عبر TBS (TPM Base Services) من خلال ctypes، لذلك لا حاجة إلى حزم محلية إضافية.

2. إعداد التراسل الأصلي

يتواصل إضافة المتصفح مع native_host.py من خلال التراسل الأصلي. تحتاج إلى تسجيل بيان يخبر Firefox بمكان المضيف.

أنشئ الملف ~/.mozilla/native-messaging-hosts/webauthn_tpm_portable.json:

{
    "name": "webauthn_tpm_portable",
    "description": "WebAuthn TPM Portable Credentials Backend",
    "path": "/absolute/path/to/native_host.py",
    "type": "stdio",
    "allowed_extensions": [
        "[email protected]"
    ]
}

استبدل path بالمسار المطلق إلى native_host.py. تأكد من أنه قابل للتنفيذ (chmod +x native_host.py).

على Windows، يتم تسجيل بيان التراسل الأصلي عبر سجل ويندوز. راجع وثائق التراسل الأصلي في Firefox للحصول على التفاصيل.

3. تحميل إضافة المتصفح

cd extension
npm install
npm run build

ثم في Firefox:

1. افتح about:debugging#/runtime/this-firefox
2. انقر على "Load Temporary Add-on..."
3. حدد أي ملف داخل مجلد extension/dist (مثل manifest.json)

4. تجهيز TPM

افتح نافذة الإضافة (popup) والصق بذرة موجودة أو انقر على "Generate" لإنشاء بذرة جديدة، ثم انقر على "Provision". إذا أنشأت بذرة جديدة، احفظها في مكان آمن. ستحتاجها لتجهيز أجهزة إضافية، وفقدانها يعني فقدان القدرة على إعداد أجهزة جديدة (ستظل المُعتمَدات الموجودة على الأجهزة المجهزة بالفعل تعمل).

يمكن أيضًا إجراء التجهيز من سطر الأوامر:

./webauthn_cli.py provision --generate
# أو ببذرة موجودة:
./webauthn_cli.py provision <seed_hex>

5. التحقق

./webauthn_cli.py test

ينشئ هذا مُعتمَدة، ويوقع تحديًا، ويتحقق من التوقيع.

مرجع سطر الأوامر

webauthn_cli.py [--backend=BACKEND] <command> [args]

الأوامر:

النهايات الخلفية (تُختار باستخدام --backend أو متغير البيئة WEBAUTHN_BACKEND):

الأمان

ما هو محمي

يتم إنشاء مفاتيح توقيع المُعتمَدات داخل TPM ولا تتركه أبدًا كنص عادي. الكتلة المشفرة في معرف المُعتمَدة غير مفيدة بدون الوصول إلى TPM مجهز. على عكس مخازن المُعتمَدات البرمجية، فإن المفاتيح الخاصة لا توجد أبدًا في ذاكرة المضيف أثناء المصادقة، مما يحمي من هجمات الإقلاع البارد (cold boot attacks) واستخراج المفاتيح بواسطة البرامج الضارة.

TPM2_Duplicate (الذي يمكنه نظريًا تصدير المفاتيح) معطل لأن المُعتمَدات تُنشأ مع authPolicy فارغ، مما يجعل التكرار مستحيلًا حتى مع الوصول الكامل للنظام.

ما هو غير محمي

يمكن للبرامج الضارة التي تعمل على نظام مجهز أن تطلب من TPM توقيع التحديات، حيث لا يوجد التحقق من المستخدم (لا زر ضغط أو بصمة). لا يمكنها استخراج المفاتيح، لكن يمكنها استخدامها أثناء النشاط. هذا سطح هجوم أضيق من مخازن المُعتمَدات البرمجية حيث يمكن للبرامج الضارة سرقة المفاتيح بشكل كامل.

أمان البذرة

البذرة الرئيسية هي جذر الثقة. إذا تم اختراقها، يمكن للمهاجم تجهيز TPM خاص به واستخدام أي كتل مُعتمَدات يحصل عليها. إذا فقدت وأصبحت جميع الأجهزة المجهزة غير متاحة، فلن يمكن استرداد المُعتمَدات. خزّنها كما تفعل مع عبارة استرداد محفظة الأجهزة (hardware wallet recovery phrase): غير متصل بالإنترنت، في مكان آمن، ويفضل مع تكرار (مثل تقسيمها عبر مواقع متعددة).

النهايات الخلفية

يتضمن المشروع ثلاث نهايات خلفية قابلة للتبديل:

webauthn_tpm_portable.py هي النهاية الخلفية الرئيسية. تقوم ببناء أوامر TPM على مستوى البايت وتعمل على كل من Linux (/dev/tpmrm0) وWindows (واجهة برمجة TBS عبر ctypes).

webauthn_tpm_linux.py تستخدم مكتبة Python tpm2-pytss وتعمل فقط على Linux.

webauthn_soft.py هي تنفيذ برمجي بحت يقلد نفس تنسيق المُعتمَدة دون أي TPM. مفيدة للاختبار والتطوير، لكنها لا توفر حماية من الأجهزة.

استكشاف الأخطاء وإصلاحها

"Permission denied" على /dev/tpmrm0: أضف المستخدم الخاص بك إلى مجموعة tss وأعد تسجيل الدخول: sudo usermod -aG tss $USER

أخطاء استيراد tpm2-pytss: جرب sudo apt install python3-tpm2-pytss أو pip install --upgrade tpm2-pytss --break-system-packages.

الإضافة لا تتصل بالمضيف الأصلي: تحقق من أن path في بيان التراسل الأصلي هو مسار مطلق يشير إلى native_host.py. افتح وحدة التحكم في المتصفح في Firefox (Ctrl+Shift+J) للتحقق من الأخطاء القادمة من الإضافة.

الترخيص

MIT