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:

Файл	Что это такое	Откуда берётся
ftWbioEngineAdapter.dll	механизм сравнения	подписанный Windows-драйвер FocalTech из каталога Microsoft Update
прошивка MCU FT9348W (src/ft9201_fw.h)	прошивка 8051, управляющая сенсором	извлечена (символ FOCALFP_9348_FW_APP) из общедоступного блоба 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.
• Прошивка и последовательность инициализации/загрузки сверены с 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 (все они это делают; крошечный сенсор исключает универсальное сравнение).