* **TPM 2.0**: جهاز TPM 2.0 فعلي (``/dev/tpmrm0`` أو ``/dev/tpm0``)، أو ``swtpm`` للتطوير بمحاكاة برمجية.
* **نواة Linux مع /dev/uhid**: دعم أصلي في النواة لأجهزة HID في مساحة المستخدم (مفعّل افتراضيًا في التوزيعات الحديثة) لدعم مفاتيح مرور FIDO2/CTAP2 الافتراضية في المتصفح.

تبعيات وقت التشغيل

* **Go 1.26** أو أحدث
* **GNU Make**
* **swtpm** (اختياري، مطلوب لتنفيذ مجموعة اختبارات التكامل الكاملة)

التثبيت عبر مدير الحزم
~~~~~~~~~~~~~~~~~~~~~~~~~~~~

على Fedora/RHEL/AlmaLinux:

.. code-block:: bash

   sudo dnf install golang make tpm2-tools zenity pinentry wl-clipboard swtpm

على Arch Linux:

.. code-block:: bash

   sudo pacman -S go make tpm2-tools zenity pinentry wl-clipboard swtpm

على Debian/Ubuntu:

.. code-block:: bash

   sudo apt install golang-go make tpm2-tools zenity pinentry-curses wl-clipboard swtpm

البدء السريع
-----------

البناء والتثبيت لحساب المستخدم الخاص بك (موصى به، بدون صلاحيات الجذر):

.. code-block:: bash

   make clean && make all
   make install-user   # Installs to ~/.local/bin, ~/.config/systemd/user, ~/.local/share/dbus-1

أو التثبيت على مستوى النظام (يتطلب صلاحيات الجذر):

.. code-block:: bash

   sudo make install   # Installs to /usr/local/bin

تفعيل وتشغيل تنشيط المقبس:

.. code-block:: bash

   systemctl --user enable --now genclave-ssh.socket genclave-gpg.socket

تهيئة الخزنة والتحقق من الحالة:

.. code-block:: bash

   ge status
   # Identities are enrolled automatically on first use by clients 
   # (WebAuthn passkeys, SSH, age, GPG) or via the portal API.

المصادقة المسبقة على الذاكرة المؤقتة للنصوص البرمجية الآلية أو الجلسات بدون واجهة:

.. code-block:: bash

   # Unlock cache interactively via TTY:
   ge unlock

   # Or pre-authenticate via pipeline in scripts:
   echo "$PIN" | ge unlock --stdin

   # Purge and lock immediately when finished:
   ge lock


مفاتيح مرور WebAuthn في المتصفح:

.. code-block:: bash

   # Open Firefox or Chrome, go to https://webauthn.io/
   # Click "Register" -> enter your PIN in the gEnclave prompt -> Passkey is created!
   # Click "Authenticate" -> enter your PIN -> Instant login verified!

إدارة الأسرار المشفرة في مخزن الإعدادات المدعوم بـ TPM:

.. code-block:: bash

   ge set-secret my-api-key "super-secret-value"
   ge get-secret my-api-key

التوثيق والمواصفات
------------------------------

تم تنظيم وثائقنا الهندسية الشاملة في مواصفات معيارية وسجلات معمارية وخرائط طريق:

* **المواصفات الوظيفية**: `Functional Spec Index`_ — تحدد متطلبات المستخدم ونماذج التفويض.
* **المخططات التقنية**: `Technical Spec Index`_ — معمارية Go التفصيلية والبدائيات التشفيرية وتصاميم الحاوية.
* **سجلات قرارات المعمارية (ADRs)**: `ADR Index`_ — سجل غير قابل للتغيير للخيارات المعمارية والتشفيرية والأمنية.
* **واجهات API وبروتوكولات الاتصال**: `API Spec Index`_ — مقبس الإدارة وبوابات D-Bus ومخططات اتصال الجسور.
* **خارطة طريق تنفيذ المشروع**: `Roadmap Index`_ — الجداول الزمنية الهندسية المرحلية وتسليمات المعالم.

أدلة المستخدم
~~~~~~~~~~~

* `User Quick Start`_ - البدء والتشغيل في 5 دقائق.
* `Installation Guide`_ - إعداد تفصيلي للبناء وudev وsystemd.
* `OpenSSH Guide`_ - تكامل وكيل OpenSSH ومضيفات القفز ومفاتيح FIDO2.
* `GnuPG & Git Signing Guide`_ - إدارة مفاتيح OpenPGP وتوقيع التزامات Git.
* `Pluggable Factors Guide`_ - ملفات المفاتيح وYubiKeys والمقاييس الحيوية ونصاب Shamir.
* `Security Guide`_ - حاوية TPM 2.0 الفعلية وعزل الذاكرة "Wrap and Clear".
* `Configuration Guide`_ - متغيرات البيئة وخيارات الخدمة.
* `CLI Reference`_ - توثيق واجهة سطر الأوامر الكامل.

.. _Functional Spec Index: docs/functional/spec.rst
.. _Technical Spec Index: docs/technical/spec.rst
.. _ADR Index: docs/adrs/index.rst
.. _API Spec Index: docs/api/spec.rst
.. _Roadmap Index: docs/project/roadmap.rst
.. _User Quick Start: docs/user/quickstart.rst
.. _Installation Guide: docs/user/installation.rst
.. _OpenSSH Guide: docs/user/ssh.rst
.. _GnuPG & Git Signing Guide: docs/user/gpg.rst
.. _Pluggable Factors Guide: docs/user/factors.rst
.. _Security Guide: docs/user/security.rst
.. _Configuration Guide: docs/user/configuration.rst
.. _CLI Reference: docs/user/cli.rst

العوامل القابلة للتوصيل والنصاب متعدد الأطراف (المرحلة 7)
------------------------------------------------

**المرحلة 7: محرك العوامل المتعددة القابلة للتوصيل والنصاب متعدد الأطراف** يوفر:

* **مُجزِّئ ملفات عشوائي متدفق**: استخدم أي ملف (من قصيدة نصية قصيرة إلى ملف FLAC صوتي رئيسي بحجم 100GB أو صورة) كعامل تفويض باستهلاك ذاكرة ثابت :math:`\mathcal{O}(1)` (مخزن مؤقت :math:`\le 64\,\text{KB}`).
* **نصاب متعدد الأطراف ("وصفة كوكاكولا")**: **مشاركة سر Shamir الملفوفة بالمفاتيح** على :math:`\text{GF}(2^8)` مع علامات تحقق HMAC، مما يتيح تفويض مفتاح مقسم :math:`k`-من-:math:`n`.
* **العتاد والمقاييس الحيوية**: YubiKey فعلي (Slot 2 HMAC-SHA1)، ومفاتيح FIDO2 فعلية (``hmac-secret``)، والمقاييس الحيوية في Linux (``fprintd``).
* **إعادة تشفير العوامل الديناميكية**: إعادة تشفير ذرية في الذاكرة (``ge rekey``) لتبديل سياسة عوامل الهوية أثناء التشغيل دون إعادة إنشاء المفاتيح.
* **تحديث CLI**: تبسيط واجهة سطر الأوامر إلى ``ge`` المعيارية.
* **فتح تلقائي لسطح المكتب**: تكامل سلس مع Freedesktop Secret Service (``org.freedesktop.secrets``).

راجع `Phase 7 Roadmap`_ و`ADR-006`_ للحصول على المواصفات الكاملة.

.. _Phase 7 Roadmap: docs/project/roadmaps/phase-7-pluggable-factors.rst
.. _ADR-006: docs/adrs/2026-08-25-pluggable-auth-factors.rst

المكونات
----------

* **genclaved**: حاوية الأمان الأساسية وخادم مفتاح أمان USB CTAP2/FIDO2 الافتراضي (``man 8 genclaved``).
* **ge**: أداة سطر الأوامر الأساسية لإدارة الخزنة وإنشاء مفاتيح OpenSSH/GnuPG والإعدادات المشفرة (``man 1 ge``).
* **age-plugin-ge**: إضافة لأداة التشفير ``age`` (``man 1 age-plugin-ge``).
* **genclave-gpg**: جسر محاكاة لتوقيع والتحقق المتوافق مع GnuPG (``man 1 genclave-gpg``).
* **genclave-ui**: مساعد رسومي لإدخال PIN (``man 1 genclave-ui``).

التطوير
-----------

تشغيل اختبارات الوحدة:

.. code-block:: bash

   make test

تشغيل مجموعة اختبارات التكامل الكاملة الأصلية لـ Go (تتطلب ``swtpm``):

.. code-block:: bash

   make integration-test

الدعم والتبرعات
-------------------

إذا وجدت **gEnclave** مفيدًا وترغب في دعم تطويره المستمر، فكّر في التبرع عبر Liberapay:

.. image:: https://liberapay.com/assets/widgets/donate.svg
   :target: https://liberapay.com/Renich/donate
   :alt: Donate using Liberapay

الرخصة
-------

حقوق النشر 2026 EVALinux

هذا المشروع مرخص بموجب رخصة GNU General Public License v3.0 أو أحدث.
راجع ملف LICENSE للحصول على التفاصيل.