ft9201-libfprint

Focal-systems FT9201 USB リーダー（2808:93a9、スタンドアロンの Windows Hello ドングル）向けの Linux 指紋認識サポート。libfprint ドライバとして提供します。

Focal-systems FT9201 USB 指紋リーダー

このセンサーは小さな 96×96 光学リーダーです。libfprint 組み込みのマッチャーでは、これほど小さな画像に対して性能が不十分であるため、本ドライバーは代わりに FocalTech 独自のマッチングエンジン（署名済み Windows ドライバに含まれる ftWbioEngineAdapter.dll）を再利用し、小型のインプロセス PE ローダーを用いて Linux 上でネイティブに実行します。Wine も Windows もクラウドも不要です。

このリポジトリは単なるドライバではなく、再利用可能な手法でもあります。 ベンダーの Windows マッチングエンジンを Linux 上で Wine なしでネイティブ実行する手法は、他の「Windows Hello 専用」リーダー（SDCP セキュアチャネルを搭載したもの、すなわち Synaptics/Goodix/ELAN/EgisTec 系の暗号化センサーを含む）にも適用可能で、オプションの src/crypto_shims.c モジュールを介して対応します。FT9201 は実装例であり、インプロセスローダー、WinBio ブリッジ、暗号バイパス層はそのまま他のデバイスに流用できます。詳しい手法とそのまま再利用できるものについては PORTING.md を参照してください。

ステータス

実機でエンドツーエンドに動作確認済み：fprintd / コマンドラインツールでの登録と検証、インストール後の KDE/GNOME での動作。ベンダーの実際のアルゴリズムを使用して指を照合します。

開発およびテストはこちらのリーダー（ASIN B0DK7LQZGH）— 2808:93a9 の FT9348W バリアント— で行いました。

注意点：

テストは上記 2808:93a9 デバイスの FT9348W バリアントのみ。
マッチャーはプロプライエタリなバイナリであり、内部のバグを修正することはできません。
x86-64 のみ（DLL とローダーは 64 ビット）。

動作の仕組み（簡易版）

USB 初期化とファームウェア起動シーケンスは FocalTech のドライバからリバースエンジニアリング。8051 MCU ファームウェアをアップロードし、特定のレジスタ設定シーケンスで起動します。
キャプチャ画像（96×96）は、エンジンが期待する 64×80 に中央クロップされます。
ft_engine.c は約 450 行のローダーで、ftWbioEngineAdapter.dll をメモリにマッピングし、DLL がインポートする約 90 個の kernel32 関数を提供し、偽の Windows TEB を設定して、エンジンの WinBio インターフェースを呼び出して登録/検証を行います。
ローダーはメモリ上のファイルからコードを読み取り実行、データを読み取り書き込みとしてマッピングするため、書き込み可能かつ実行可能なページは存在しません。つまり、fprintd のデフォルトの MemoryDenyWriteExecute ハードニング下でも動作し、セキュリティ設定を無効にする必要は一切ありません。

完全な技術解説は 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。

プロプライエタリなバイナリ

このリポジトリにはプロプライエタリなバイナリは含まれていません。以下の 2 ファイルは FocalTech のもので、scripts/fetch-blobs.sh によりビルド時に既存の公開ソースから取得されます：

ファイル	内容	入手元
`ftWbioEngineAdapter.dll`	マッチングエンジン	Microsoft Update Catalog 上の FocalTech 署名済み Windows ドライバ
FT9348W MCU ファームウェア (`src/ft9201_fw.h`)	センサーが実行する 8051 ファームウェア	公開されている `ft9201-static` バイナリから抽出（シンボル `FOCALFP_9348_FW_APP`）

手動でバイナリを入手する

どちらかのダウンロード URL が移動した場合、必要なのは次の 2 ファイルだけです：

ftWbioEngineAdapter.dll — Microsoft Update Catalog で "FocalTech Electronics Biometric"（ドライバ 1.0.3.58、ハードウェア ID USB\VID_2808&PID_93A9 に一致）を検索。.cab をダウンロードし、cabextract で展開して ftWbioEngineAdapter.dll を blobs/ に配置します。
MCU ファームウェア — FOCALFP_9348_FW_APP シンボルを含む FocalTech Linux libfprint バイナリのコピーを入手し（例：ft9201-static から）、python3 scripts/extract-firmware.py <その-libfprint-2.so> src/ft9201_fw.h を実行します。

その後、scripts/build.sh を再実行します。

クレジット

USB プロトコルは、もともと banianitc/ft9201-fingerprint-driver によりリバースエンジニアリングされました。
ファームウェアおよび初期化/起動シーケンスは、mrrbrilliant/ft9201-static を介して FocalTech の Linux バイナリと相互参照されました。
libfprint 上に構築されています。

再利用可能な手法と暗号化センサーパスは、さらに以下の成果に基づいています：

uunicorn — 彼の synaWudfBioUsb-sandbox と wine fork は、Wine 下でベンダーの Windows 生体認証ドライバをトレースするためのハーネスであり、これにより Windows マシンなしで暗号化センサーのコマンドプロトコルを復元する方法が確立されました。
Marco Trevisan (3v1n0)、libfprint メンテナー — 彼がこの Wine トレース手法を示唆し、libfprint 自身のマッチャーを改善する取り組みが、ベンダーマッチャー経路が存在する理由を形作っています。
championswimmer/libfprint-eh577 — EgisTec EH577 センサーファミリの先行事例。

FT9201 を Linux で動作させる他の方法

これが唯一のアプローチではありません。代替手法は主に、FocalTech のマッチャーをどのように再利用するか（すべての手法がマッチャーを再利用します。小さなセンサーでは汎用マッチングが不可能なため）が異なります。

Romk-a/ft9201-linux-setup — Debian/Ubuntu (Astra Linux) 向けガイドで、FocalTech のプリビルドプロプライエタリ Linux "TOD" ドライバ（ryenyuku/libfprint-ft9201 から；Fedora RPM も存在しました）をインストールし、USB-ID テーブルをバイナリパッチ（9338 → 93a9）します。
- 比較： こちらの方法は作業が少ない — .deb をインストールし、2 バイトパッチするだけで、リバースエンジニアリングは不要です。ただし、TOD 対応の libfprint（Debian/Ubuntu 系；通常の Fedora/Arch では不可）が必要で、システム全体の libfprint を古い完全クローズドビルドに置き換え、パッケージマネージャと競合して固定し続ける必要があります。一方、本プロジェクトはオープンなドライバを提供し、サイドバイサイドでインストール（ディストリの libfprint はそのまま）、TOD なしのメインライン libfprint で動作し、隔離されたベンダーマッチャー DLL のみをロードします。これがリバースエンジニアリングの成果です。
- 短いまとめ： Debian/Ubuntu では TOD ルートが簡単ですが、Fedora/Arch の場合や、オープンで非侵襲的な方法を望む場合は、こちらを使用してください。
カーネルドライバも存在します（banianitc — 本プロジェクトがリバースエンジニアリング元としたプロトコルリファレンス、bm16ton/ft92010x9338）が、libfprint/fprintd と統合されていないため、ログイン/PAM 対応はありません。

これらの .deb/RPM パッケージが再配布するプロプライエタリ Linux TOD ドライバは、GPD Win 4 向けに FocalTech/GPD がリリースしたものの、後に公式配布から削除されたようです。そのため現在はコミュニティの再ホストとしてのみ存続しています。（また、一部の GPD Win 4 ユニットはまったく別のセンサー、Chipsailing CS9711 を搭載しており、この FocalTech 部品とは異なります。）

ライセンス

ドライバとローダー（src/、scripts/）は libfprint に合わせて LGPL-2.1-or-later です。FocalTech の DLL とファームウェアはそれぞれの所有者の財産であり、ここでは配布されません。自分で取得してください。本プロジェクトはあなたが所有するハードウェアのための相互運用ツールであり、FocalTech のコードを含んだり再ライセンスしたりするものではありません。

ft9201-libfprint — Updated!

カテゴリ