gpasskey

.. image:: https://gitlab.com/renich/gpasskey/-/raw/master/assets/logo.svg :width: 140px :align: center :alt: gpasskey logo

المُعزل المركزي للهوية التشفيرية لنظام لينكس.

.. image:: https://gitlab.com/renich/gpasskey/badges/master/pipeline.svg :target: https://gitlab.com/renich/gpasskey/-/commits/master :alt: pipeline status .. image:: https://img.shields.io/gitlab/v/release/renich/gpasskey?logo=gitlab&label=release :target: https://gitlab.com/renich/gpasskey/-/releases :alt: GitLab Release .. image:: https://img.shields.io/badge/Go-1.26+-00ADD8?style=flat&logo=go :target: https://golang.org/ :alt: Go Version .. image:: https://img.shields.io/badge/License-GPLv3-blue.svg?logo=gnu :target: https://www.gnu.org/licenses/gpl-3.0 :alt: License .. image:: https://img.shields.io/badge/FIDO2-CTAP2%20Virtual%20HID-4285F4?logo=fido :target: docs/technical/specs/ctap2-virtual-hid.rst :alt: FIDO2 CTAP2 .. image:: https://img.shields.io/badge/Hardware-TPM%202.0%20Sealed-4CAF50?logo=security :target: docs/technical/specs/tpm-binding.rst :alt: TPM 2.0 .. image:: https://img.shields.io/badge/Bridges-SSH%20%7C%20GPG%20%7C%20Age%20%7C%20D--Bus-8b5cf6 :target: docs/technical/specs/protocol-bridges.rst :alt: Multi-Protocol Bridges .. image:: https://img.shields.io/liberapay/receives/Renich.svg?logo=liberapay :target: https://liberapay.com/Renich/donate :alt: Liberapay .. image:: https://liberapay.com/assets/widgets/donate.svg :target: https://liberapay.com/Renich/donate :alt: Donate using Liberapay

.. caution::

برنامج في مرحلة ما قبل ألفا — استخدمه على مسؤوليتك الخاصة!

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

• خطر مرتفع لفقدان المفاتيح والبيانات: احرص دائمًا على تدوين عبارة الاسترداد BIP39 المكوّنة من 24 كلمة وتخزينها في مكان آمن.
• احرص على وجود تحقق ثانوي (2FA): عند تسجيل مفاتيح أمان FIDO2 الافتراضية في حسابات الإنتاج، قم دائمًا بإعداد وسيلة تحقق ثانوية (مثل TOTP أو رموز الاسترداد الاحتياطية).
• بدون ضمان: البرنامج مُقدَّم كما هو تمامًا دون أي ضمانات من أي نوع بموجب رخصة GNU GPLv3.

نظرة عامة

يوفر gpasskey مُعزلًا أمنيًا مدعومًا بالعتاد يخزّن المفاتيح الخاصة في خزنة مشفّرة. ويعمل كجسر متعدد البروتوكولات، إذ يدعم وكيل SSH (SSH Agent)، وبروتوكول إضافة التشفير age، ومحاكاة توقيع الالتزامات عبر GnuPG.

أهم الميزات

• دعم متعدد البروتوكولات:
  • مفاتيح مرور FIDO2 / CTAP2: محاكي مفتاح أمان USB افتراضي عبر /dev/uhid لمصادقة المتصفحات الأصلية (Firefox وChrome وChromium) ونظام التشغيل عبر Passkey.
  • وكيل SSH (SSH Agent): بروتوكول وكيل متوافق مع OpenSSH.
  • age-plugin: دعم أصلي لتشفير الملفات عبر age (الإصدار 1).
  • جسر GnuPG: يحاكي واجهة أوامر GPG لتوقيع التزامات Git والتحقق منها بسلاسة.
• أمان مدعوم بالعتاد: تُشفَّر المفاتيح الخاصة باستخدام AES-256-GCM، وتُختَم بشكل أساسي على TPM 2.0 مع تخزين مؤقت لمفتاح جذر التخزين (SRK).
• ربط تشفيري بالرقم السري (PIN) وذاكرة تخزين مؤقت للتحقق من المستخدم (UV): ترتبط كل عملية بمفتاح فرعي مشتق من الرقم السري، مع ذاكرة تخزين مؤقت آمنة للجلسة مدتها 15 ثانية في ذاكرة RAM مقفلة (mlock).
• اشتقاق مفاتيح Argon2id (KDF): اشتقاق مفاتيح كثيف الاستخدام للذاكرة لعبارة المرور الرئيسية وللاسترداد وللمفاتيح الفرعية.
• الحماية من هجمات القوة العمياء: تراجع أُسّي تلقائي لمحاولات التفويض الفاشلة.
• توجيه ذكي لواجهة المستخدم: كشف تلقائي لنوع الجلسة (رسومية مقابل TTY) لمطالبات التفويض.
• ذاكرة آمنة: يستخدم mmap/mlock واستراتيجية «التغليف والمسح» (Wrap and Clear) لمنع تسرب المواد المفتاحية إلى مساحة التبديل (swap) أو كومة جامع القمامة (GC heap).
• إدارة الهويات: واجهة أوامر قوية (gpasskey-cli) لإدارة الخزنة والأسرار المشفّرة.

تكامل TPM 2.0

يدعم gpasskey الأمان المدعوم بالعتاد عبر TPM 2.0. وهذا يضمن ألا يغادر مفتاحك الرئيسي شريحة TPM دون تشفير، وأن يظل مرتبطًا بحالة إقلاع النظام.

المتطلبات

* جهاز متوافق مع TPM 2.0 (أو ``swtpm`` لأغراض التطوير).
* تثبيت ``tpm2-tools`` على النظام.

التهيئة
~~~~~~~~~~

تتم تهيئة تخزين TPM تلقائيًا عند إنشاء هوية جديدة. للتحقق من حالة TPM:

.. code-block:: bash

   gpasskey-cli status

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

بعد التهيئة، يستخدم البرنامج الخفي (daemon) شريحة TPM بشفافية. تُختَم جميع البيانات الحساسة مقابل **PCR 0** (البرنامج الثابت الأساسي للنظام) و**PCR 7** (حالة Secure Boot). أي تعديل على البرنامج الثابت أو على إعدادات Secure Boot سيمنع فتح الخزنة، مما يوفر الحماية ضد الهجمات دون اتصال والعبث غير المصرح به بالنظام.

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

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

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

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

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

فعّل وابدأ آلية socket activation::

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

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

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

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

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

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

   gpasskey-cli set-secret my-api-key "super-secret-value"
   gpasskey-cli 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.
• Security Guide_ - مُعزل عتاد TPM 2.0 وعزل الذاكرة عبر «التغليف والمسح» (Wrap and Clear).
• Configuration Guide_ - متغيرات البيئة وخيارات الخدمة.

.. _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 .. _Security Guide: docs/user/security.rst .. _Configuration Guide: docs/user/configuration.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 مادية (الفتحة 2 HMAC-SHA1)، ومفاتيح FIDO2 مادية (hmac-secret)، والقياسات الحيوية لنظام لينكس (fprintd).
• إعادة توليد مفاتيح العوامل ديناميكيًا: إعادة تشفير ذرّية في الذاكرة (gpk rekey) لتبديل سياسة عوامل الهوية أثناء التشغيل دون إعادة إنشاء المفاتيح.
• تحديث واجهة الأوامر: تبسيط واجهة سطر الأوامر إلى أمر gpk المعياري (/usr/local/bin/gpk).
• الفتح التلقائي على سطح المكتب: تكامل سلس مع 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

المكونات

• gpasskeyd: البرنامج الخفي الذي يمثل المُعزل الأمني الأساسي ومفتاح الأمان الافتراضي USB CTAP2/FIDO2.
• gpasskey-cli: أداة إدارية لإدارة الخزنة والإعدادات المشفّرة.
• age-plugin-gpasskey: إضافة لأداة التشفير age.
• gpasskey-gpg: جسر محاكاة للتوقيع والتحقق المتوافقين مع GnuPG.
• gpasskey-ui: مساعد رسومي لإدخال الرقم السري (PIN).

التطوير

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

make test

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

make integration-test

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

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

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

الترخيص

حقوق النشر 2026 EVALinux

هذا المشروع مرخّص بموجب رخصة GNU العامة (GPL) الإصدار 3.0 أو أي إصدار لاحق. راجع ملف LICENSE للتفاصيل.