ft9201-libfprint

Поддержка отпечатков пальцев в Linux для USB-ридера Focal-systems FT9201 (2808:93a9, продаётся как автономный Windows Hello-донгл) в качестве драйвера для libfprint.

Сенсор — крошечный оптический ридер 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. FT9201 — рабочий пример; in-process загрузчик, мост WinBio и слой обхода криптографии переносятся на следующее устройство. См. PORTING.md для пошагового метода и того, что можно использовать как есть.

Статус

Работает «из коробки» на реальном оборудовании: регистрация и верификация через fprintd / инструменты командной строки, а также в KDE/GNOME после установки. Сравнение пальца осуществляется с помощью реального алгоритма вендора.

Разработан и протестирован на этом конкретном ридере (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.

Требования

Инструменты сборки + зависимости сборки 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:

Ручное получение блобов

Если какой-либо 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.
• Прошивка и последовательность инициализации/загрузки сверены с Linux-блобом FocalTech через mrrbrilliant/ft9201-static.
• Построено на libfprint.

Метод переиспользования и путь к криптосенсору дополнительно основаны на работе:

• uunicorn — чьи synaWudfBioUsb-sandbox и форк Wine являются инструментом для трассировки Windows-биометрического драйвера вендора под Wine, что позволяет восстановить командный протокол криптосенсора без Windows.
• Marco Trevisan (3v1n0), мэйнтейнера libfprint — который указал путь к этому подходу с трассировкой через Wine, и чьи усилия по улучшению собственного механизма сравнения libfprint показывают, почему вообще существует путь с использованием вендорского модуля.
• championswimmer/libfprint-eh577 — предшествующая работа для семейства сенсоров EgisTec EH577.

Другие способы запуска FT9201 в Linux

Это не единственный подход — альтернативы различаются в основном тем, как они переиспользуют механизм сравнения FocalTech (все они это делают; крошечный сенсор исключает универсальное сравнение).

• Romk-a/ft9201-linux-setup — руководство для Debian/Ubuntu (Astra Linux), которое устанавливает предварительно собранный проприетарный Linux-драйвер "TOD" FocalTech (из 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 — протокольный референс, с которого этот проект начал обратную разработку, bm16ton/ft92010x9338), но они не интегрируются с libfprint/fprintd, поэтому нет поддержки входа/PAM.

Проприетарный Linux-драйвер TOD, который распространяют эти .deb/RPM-пакеты, по-видимому, был выпуском FocalTech/GPD для GPD Win 4, который позже был изъят из официального распространения — поэтому теперь он сохраняется только в виде сообщества перезаливок. (Заметим также, что некоторые устройства GPD Win 4 имеют другой сенсор, Chipsailing CS9711, а не этот компонент FocalTech.)

Связанные проекты

• championswimmer/libfprint-eh577 — попытка создания драйвера для Linux для EgisTec EH577 (1c7a:0577), ещё одного нажимного ридера «только Windows Hello» (активный сенсор 52×72). Другой вендор и USB-протокол, но та же схема сравнение на хосте: его Windows-пакет содержит DLL адаптера движка вендора (EgisTouchFPEngine0577.dll, без защищённого контейнера VBS), поэтому метод из PORTING.md применим и к нему.
• OMGrant/eh577-libfprint — этот метод полностью перенесён на EgisTec EH577 и опубликован как рабочий драйвер. Криптографические техники §3b были проверены на его SDCP-сборках; распространяемый драйвер нацелен на сборку из каталога до-SDCP (чисто программный механизм сравнения — см. примечание §3b о выборе сборки), выполняя регистрацию и верификацию настоящих пальцев в Linux.

Лицензия

Драйвер и загрузчик (src/, scripts/) распространяются под лицензией LGPL-2.1-or-later, соответствующей libfprint. DLL и прошивка FocalTech являются их собственной собственностью и не распространяются здесь — вы получаете их самостоятельно. Этот проект является инструментом обеспечения совместимости для аппаратного обеспечения, которым вы владеете; он не включает и не перелицензирует код FocalTech.