omgrant/ft9201-libfprintДрайвер для libfprint в Linux для USB-сканера отпечатков пальцев Focal-systems FT9201 (2808:93a9) — нативно запускает собственный Windows-движок сравнения FocalTech на Linux, без Wine. Включает метод портирования других считывателей, предназначенных только для Windows Hello.
# ft9201-libfprint
Поддержка отпечатков пальцев в Linux для 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` из их подписанного Windows-драйвера,
запуская его нативно в Linux с помощью небольшого in-process PE-загрузчика. Ни Wine,
ни Windows, ни облака не нужны.
> **Этот репозиторий — не просто один драйвер, а переиспользуемый метод.** Метод —
> запуск Windows-движка сравнения вендора нативно в Linux без 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 — рабочий пример; in-process загрузчик,
> мост 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; прошивка микроконтроллера 8051 загружается, затем запускается определённая последовательность конфигурации регистров.
- Каждый снимок (96×96) центрально обрезается до 64×80, которые ожидает движок.
- `ft_engine.c` — загрузчик размером ~450 строк, который отображает `ftWbioEngineAdapter.dll` в память, предоставляет около 90 функций `kernel32`, которые она импортирует, настраивает фиктивный Windows 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` | механизм сравнения | подписанный Windows-драйвер FocalTech из каталога Microsoft Update |
| прошивка MCU FT9348W (`src/ft9201_fw.h`) | прошивка 8051, управляющая сенсором | извлечена (символ `FOCALFP_9348_FW_APP`) из общедоступного блоба [`ft9201-static`](https://github.com/mrrbrilliant/ft9201-static) |
### Ручное получение блобов
Если какой-либо URL загрузки изменился, вам нужны только эти два файла:
- **`ftWbioEngineAdapter.dll`** — найдите в каталоге Microsoft Update *"FocalTech Electronics Biometric"* (драйвер 1.0.3.58, соответствует аппаратному ID `USB\VID_2808&PID_93A9`). Загрузите `.cab`, извлеките с помощью `cabextract` и поместите `ftWbioEngineAdapter.dll` в `blobs/`.
- **Прошивка MCU** — получите любую копию блоба FocalTech Linux libfprint, содержащего символ `FOCALFP_9348_FW_APP` (например, из `ft9201-static`) и выполните `python3 scripts/extract-firmware.py <путь-к-тому-libfprint-2.so> src/ft9201_fw.h`.
Затем снова запустите `scripts/build.sh`.
## Благодарности
- Протокол USB первоначально обратно разработан
[banianitc/ft9201-fingerprint-driver](https://github.com/banianitc/ft9201-fingerprint-driver).
- Прошивка и последовательность инициализации/загрузки сверены с Linux-блобом 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) являются инструментом для трассировки Windows-биометрического драйвера вендора под Wine, что позволяет восстановить командный протокол криптосенсора без Windows.
- **Marco Trevisan ([3v1n0](https://github.com/3v1n0))**, мэйнтейнера libfprint — который указал путь к этому подходу с трассировкой через Wine, и чьи усилия по улучшению собственного механизма сравнения libfprint показывают, почему вообще существует путь с использованием вендорского модуля.
- **[championswimmer/libfprint-eh577](https://github.com/championswimmer/libfprint-eh577)**
— предшествующая работа для семейства сенсоров EgisTec EH577.
## Другие способы запуска FT9201 в Linux
Это не единственный подход — альтернативы различаются в основном *тем, как* они переиспользуют механизм сравнения 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-ID (`9338` → `93a9`).
- **Как это сравнивается:** этот путь *требует меньше работы* — установить `.deb`, пропатчить два байта, никакой обратной разработки. Но он требует **libfprint с поддержкой TOD** (семейство Debian/Ubuntu; **не** в стандартной Fedora/Arch), он **заменяет всю системную `libfprint`** на старую, полностью закрытую сборку, и вам приходится бороться с менеджером пакетов, чтобы зафиксировать её версию. Этот проект, напротив, предоставляет **открытый** драйвер, устанавливается **рядом** (ваша дистрибутивная libfprint остаётся нетронутой), работает на **основной libfprint без TOD** и загружает только изолированную DLL *механизма сравнения* вендора — это и было целью всей обратной разработки.
- **Кратко:** на Debian/Ubuntu путь TOD — это простая кнопка; на Fedora/Arch или если вы хотите открытое и неинвазивное решение, используйте этот проект.
- **Драйверы ядра** существуют ([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)
— попытка создания драйвера для Linux для **EgisTec EH577** (`1c7a:0577`), ещё одного нажимного ридера «только Windows Hello» (активный сенсор 52×72). Другой вендор и USB-протокол, но та же схема *сравнение на хосте*: его Windows-пакет содержит DLL адаптера движка вендора (`EgisTouchFPEngine0577.dll`, без защищённого контейнера VBS), поэтому метод из **[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 о выборе сборки), выполняя регистрацию и верификацию настоящих пальцев в Linux.
## Лицензия
Драйвер и загрузчик (`src/`, `scripts/`) распространяются под лицензией **LGPL-2.1-or-later**, соответствующей libfprint. DLL и прошивка FocalTech являются их собственной собственностью и не распространяются здесь — вы получаете их самостоятельно. Этот проект является инструментом обеспечения совместимости для аппаратного обеспечения, которым вы владеете; он не включает и не перелицензирует код FocalTech.