omgrant/ft9201-libfprintبرنامج تشغيل libfprint لنظام لينكس لقارئ بصمات الأصابع USB من Focal-systems FT9201 (2808:93a9) — يقوم بتشغيل محرك مطابقة ويندوز الخاص بـ FocalTech بشكل أصلي على لينكس، بدون Wine. يتضمن طريقة لنقل قُرّاء آخرين خاصين بـ Windows-Hello فقط.
# ft9201-libfprint
دعم بصمات الأصابع في لينكس لقارئ USB **Focal-systems FT9201**
(`2808:93a9`، يُباع كدونجل مستقل لـ Windows Hello)، كسائق لـ
[libfprint](https://gitlab.freedesktop.org/libfprint/libfprint).
<p align="center">
<img src="https://assets.kitploit.com/production/public/readmes/7029/9a4eac4876063dbf80466bd7c0d975430fb75f3f9655604d2d4aad3725c9e11e.jpg" alt="قارئ بصمات USB Focal-systems FT9201" width="360">
</p>
المستشعر هو قارئ بصري صغير بحجم 96×96. محرك المطابقة المدمج في libfprint لا يؤدي
عملاً جيداً على صورة بهذا الصغر، لذلك يستخدم هذا السائق بدلاً من ذلك **محرك المطابقة الخاص بشركة FocalTech**
— ملف `ftWbioEngineAdapter.dll` من سائق ويندوز الموقّع — ويشغله أصلاً على لينكس باستخدام مُحمّل PE صغير داخل العملية. لا Wine، لا ويندوز، لا سحابة.
> **هذا المستودع هو أيضاً طريقة قابلة لإعادة الاستخدام، وليس مجرد سائق واحد.** التقنية —
> تشغيل محرك المطابقة الخاص ببائع على لينكس أصلاً، بدون Wine — يمكن تعميمها على قارئات أخرى
> "لـ Windows Hello فقط"، **بما في ذلك تلك التي تحتوي على قناة آمنة SDCP** (المستشعرات المشفرة من فئة
> Synaptics/Goodix/ELAN/EgisTec)، عبر الوحدة الاختيارية [`src/crypto_shims.c`](https://github.com/omgrant/ft9201-libfprint/blob/master/src/crypto_shims.c). جهاز FT9201
> هو المثال العملي؛ المُحمّل داخل العملية، جسر WinBio، وطبقة تجاوز التشفير ينطبقون على الجهاز التالي.
> انظر **[PORTING.md](https://github.com/omgrant/ft9201-libfprint/blob/master/PORTING.md)** للحصول على الطريقة خطوة بخطوة وما يمكن إعادة استخدامه كما هو.
## الحالة
يعمل من البداية إلى النهاية على أجهزة حقيقية: التسجيل والتحقق عبر `fprintd` /
أدوات سطر الأوامر، وفي KDE/GNOME بعد التثبيت. يطابق إصبعك باستخدام الخوارزمية الحقيقية للبائع.
تم تطويره واختباره ضد
[هذا القارئ بالضبط](https://www.amazon.com/dp/B0DK7LQZGH) (ASIN `B0DK7LQZGH`) —
متغير FT9348W من `2808:93a9`.
تحذيرات:
- تم اختباره فقط على متغير FT9348W من جهاز `2808:93a9`.
- المُطابق هو كائن مغلق المصدر نستدعيه؛ لا يمكننا إصلاح الأخطاء داخله.
- x86-64 فقط (DLL والمُحمّل 64 بت).
## كيف يعمل (نسخة مختصرة)
- تم هندسة عكسية لتسلسل تهيئة USB + تشغيل البرنامج الثابت من سائقات FocalTech
الخاصة؛ يتم تحميل برنامج MCU 8051 الثابت، ثم تسلسل تكوين سجل محدد يبدأ تشغيله.
- كل لقطة (96×96) يتم قصها مركزياً إلى حجم 64×80 الذي تتوقعه المحركة.
- `ft_engine.c` هو مُحمّل بحوالي 450 سطراً يقوم بتعيين `ftWbioEngineAdapter.dll` في
الذاكرة، ويوفر وظائف `kernel32` التسعين التي يستوردها، وينشئ TEB ويندوز وهمي،
ويستدعي واجهة WinBio للمحركة للتسجيل/التحقق.
- المُحمّل يعيّن الكود للقراءة-والتنفيذ والبيانات للقراءة-والكتابة من ملف في الذاكرة،
لذا **لا توجد صفحة قابلة للكتابة *و* للتنفيذ في نفس الوقت**. هذا يعني أنه يعمل تحت
إعدادات `MemoryDenyWriteExecute` الافتراضية لـ `fprintd` — ليس عليك **تعطيل أي إعدادات أمنية**.
انظر [`docs/how-it-works.md`](https://github.com/omgrant/ft9201-libfprint/blob/master/docs/how-it-works.md) للكتابة الفنية الكاملة.
## المتطلبات
أدوات بناء + تبعيات بناء libfprint. على Fedora/Nobara:
```
sudo dnf install git meson ninja-build gcc cabextract python3 \
glib2-devel gusb-devel nss-devel pixman-devel gobject-introspection-devel \
libgudev-devel systemd-devel
```
(Debian/Ubuntu: المكافئات — `libglib2.0-dev libgusb-dev libnss3-dev
libpixman-1-dev libgudev-1.0-dev libsystemd-dev`، بالإضافة إلى `cabextract`.)
## البناء والتثبيت
```
git clone https://github.com/OMGrant/ft9201-libfprint
cd ft9201-libfprint
scripts/fetch-blobs.sh # سحب DLL الخاص بالبائع + البرنامج الثابت لـ MCU (انظر الملاحظة أدناه)
scripts/build.sh # استنساخ libfprint المثبت، تركيب السائق فيه، بناء
```
جربه بدون تثبيت أي شيء:
```
FT9201_ENGINE_DLL=$PWD/blobs/ftWbioEngineAdapter.dll \
LD_LIBRARY_PATH=libfprint/build/libfprint \
libfprint/build/examples/enroll
```
ثبته لـ KDE/GNOME/تسجيل الدخول (بجانب التثبيت الحالي؛ يبقى libfprint الخاص بتوزيعتك كما هو، بدون تعطيل أي تعزيزات أمنية):
```
sudo scripts/install.sh
fprintd-enroll
```
التراجع عن كل شيء: `sudo scripts/install.sh --uninstall`.
## الملفات المغلقة المصدر
هذا المستودع **لا يحتوي** على أي ملفات ثنائية مغلقة المصدر. ملفان هما ملك لـ FocalTech ويتم جلبهما
من مصادر عامة موجودة وقت البناء بواسطة `scripts/fetch-blobs.sh`:
| الملف | ما هو | من أين يأتي |
|------|------------|---------------------|
| `ftWbioEngineAdapter.dll` | محرك المطابقة | سائق ويندوز الموقّع من FocalTech على كتالوج تحديثات مايكروسوفت |
| برنامج MCU FT9348W الثابت (`src/ft9201_fw.h`) | برنامج 8051 الثابت الذي يشغله المستشعر | مستخرج (الرمز `FOCALFP_9348_FW_APP`) من الملف العام [`ft9201-static`](https://github.com/mrrbrilliant/ft9201-static) |
### جلب الملفات يدوياً
إذا تغير رابط التحميل، فأنت بحاجة فقط إلى هذين الملفين:
- **`ftWbioEngineAdapter.dll`** — ابحث في كتالوج تحديثات مايكروسوفت عن
*"FocalTech Electronics Biometric"* (سائق 1.0.3.58، يطابق معرف الجهاز
`USB\VID_2808&PID_93A9`). حمّل ملف `.cab`، استخرجه باستخدام `cabextract`، وضع
`ftWbioEngineAdapter.dll` في `blobs/`.
- **البرنامج الثابت لـ MCU** — احصل على أي نسخة من ملف libfprint الخاص بـ FocalTech لنظام لينكس
يحتوي على الرمز `FOCALFP_9348_FW_APP` (مثلاً من `ft9201-static`) وقم بتشغيل
`python3 scripts/extract-firmware.py <that-libfprint-2.so> src/ft9201_fw.h`.
ثم أعد تشغيل `scripts/build.sh`.
## الإشادات
- تمت هندسة بروتوكول USB عكسياً أصلاً بواسطة
[banianitc/ft9201-fingerprint-driver](https://github.com/banianitc/ft9201-fingerprint-driver).
- تمت مقارنة البرنامج الثابت وتسلسل التهيئة/التشغيل مع ملف FocalTech الخاص بلينكس عبر
[mrrbrilliant/ft9201-static](https://github.com/mrrbrilliant/ft9201-static).
- مبني على [libfprint](https://gitlab.freedesktop.org/libfprint/libfprint).
الطريقة القابلة لإعادة الاستخدام ومسار المستشعر المشفر يبنيان بالإضافة إلى ذلك على عمل:
- **[uunicorn](https://github.com/uunicorn)** — الذي كانت
[synaWudfBioUsb-sandbox](https://github.com/uunicorn/synaWudfBioUsb-sandbox) و
[فرع wine](https://github.com/uunicorn/wine) هما الأداتين لتتبع سائق ويندوز البيومتري للبائع تحت Wine،
وهو كيف يتم استعادة بروتوكول أوامر المستشعر المشفر بدون جهاز ويندوز.
- **Marco Trevisan ([3v1n0](https://github.com/3v1n0))**، وهو أحد المشرفين على libfprint —
الذي أشار إلى نهج تتبع Wine هذا، والذي دفع لتحسين محرك المطابقة الخاص بـ libfprint في المنبع يوضح لماذا
يوجد مسار المُطابق البائع أساساً.
- **[championswimmer/libfprint-eh577](https://github.com/championswimmer/libfprint-eh577)**
— عمل سابق لعائلة مستشعرات EgisTec EH577.
## طرق أخرى لتشغيل FT9201 على لينكس
هذه ليست الطريقة الوحيدة — البدائل تختلف بشكل رئيسي في *كيفية* إعادة استخدام
مُطابق FocalTech (كلها تفعل ذلك؛ المستشعر الصغير يمنع المطابقة العامة).
- **[Romk-a/ft9201-linux-setup](https://github.com/Romk-a/ft9201-linux-setup)** — دليل
لـ Debian/Ubuntu (Astra Linux) يقوم بتثبيت **سائق Linux "TOD" المُعد مسبقاً والمغلق من FocalTech** (من
[ryenyuku/libfprint-ft9201](https://github.com/ryenyuku/libfprint-ft9201); كانت هناك أيضاً
حزم RPM لـ Fedora) ويقوم بتصحيح جدول معرفات USB بشكل ثنائي (`9338` → `93a9`).
- **كيف يقارن:** هذا المسار هو *عمل أقل* — ثبّت ملف `.deb`، صحح بايتين،
لا حاجة للهندسة العكسية. لكنه يحتاج إلى **libfprint ممكّن لـ TOD**
(عائلة Debian/Ubuntu؛ **ليس** على Fedora/Arch الأساسي)، كما أنه **يستبدل libfprint النظام بالكامل**
ببناء قديم ومغلق تماماً، وعليك محاربة مدير الحزم لإبقائه مقيداً. هذا المشروع بدلاً من ذلك يقدم سائقاً **مفتوحاً**،
يُثبت **بجانب النظام** (يبقى libfprint الخاص بتوزيعتك دون تغيير)، ويعمل على
**libfprint الرئيسي بدون TOD**، ويُحمّل فقط ملف DLL المُطابق المغلق والمُعزول
— وهو ما اشترته كل الهندسة العكسية.
- **النسخة المختصرة:** على Debian/Ubuntu، مسار TOD هو الزر السهل؛ على
Fedora/Arch، أو إذا كنت تريده مفتوحاً وغير متداخل، استخدم هذا.
- **توجد سائقات Kernel** ([banianitc](https://github.com/banianitc/ft9201-fingerprint-driver)
— المرجع البروتوكولي الذي تمت هندسته عكسياً في هذا المشروع،
[bm16ton/ft92010x9338](https://github.com/bm16ton/ft92010x9338)) لكنها لا تتكامل
مع libfprint/fprintd، لذلك لا يوجد دعم لتسجيل الدخول/PAM.
يبدو أن سائق Linux TOD المغلق الذي تعيد توزيعه حزم `.deb`/RPM تلك كان
إصداراً من FocalTech/GPD لجهاز GPD Win 4 الذي تم **سحبه لاحقاً من التوزيع الرسمي**
— ولهذا السبب بقي الآن فقط كاستضافات مجتمعية.
(لاحظ أيضاً أن بعض وحدات GPD Win 4 تحتوي على مستشعر مختلف تماماً، وهو Chipsailing
CS9711، وليس هذا الجزء من FocalTech.)
## مشاريع ذات صلة
- [championswimmer/libfprint-eh577](https://github.com/championswimmer/libfprint-eh577)
— جهد سائق لينكس لـ **EgisTec EH577** (`1c7a:0577`)، وهو قارئ آخر من نوع "Windows Hello فقط"
بالضغط (مستشعر نشط 52×72). بائع وبروتوكول USB مختلفان، ولكن نفس الهيئة
*التطابق على المضيف*: حزمة ويندوز الخاصة به تحتوي على DLL محرك محول بائع (`EgisTouchFPEngine0577.dll`،
بدون VBS enclave)، لذا فإن الطريقة في **[PORTING.md](https://github.com/omgrant/ft9201-libfprint/blob/master/PORTING.md)** تنطبق عليه أيضاً.
- **[OMGrant/eh577-libfprint](https://github.com/OMGrant/eh577-libfprint)** — هذه
الطريقة تم تطبيقها من البداية إلى النهاية على **EgisTec EH577** ونشرها كسائق عامل.
تم التحقق من تقنيات التشفير في §3b ضد بنيات SDCP الخاصة به؛ السائق الموزع يستهدف
بناءً من الكتالوج *قبل SDCP* (مُطابق برمجي بحت — انظر ملاحظة §3b حول اختيار البناء)،
ويسجل ويحقق من الأصابع الحقيقية على لينكس.
## الترخيص
السائق والمُحمّل (`src/`، `scripts/`) هما **LGPL-2.1-or-later**، مطابقين لـ libfprint.
ملف DLL الخاص بـ FocalTech والبرنامج الثابت هما ملكيتهما الخاصة ولا يتم توزيعهما هنا
— أنت تجلبهما بنفسك. هذا المشروع هو أداة توافق للأجهزة التي تمتلكها؛ لا يحتوي
على أي كود من FocalTech ولا يعيد ترخيصه.