omgrant/ft9201-libfprintLinux-libfprint-Treiber für den Focal-systems FT9201 (2808:93a9) USB-Fingerabdruckleser — führt FocalTechs eigene Windows-Matching-Engine nativ unter Linux aus, kein Wine. Enthält eine Methode zum Portieren anderer Windows-Hello-only-Leser.
# ft9201-libfprint
Linux-Fingerabdruckunterstützung für den **Focal-systems FT9201** USB-Leser
(`2808:93a9`, verkauft als eigenständiger Windows Hello-Dongle), als
[libfprint](https://gitlab.freedesktop.org/libfprint/libfprint)-Treiber.
<p align="center">
<img src="https://assets.kitploit.com/production/public/readmes/7029/9a4eac4876063dbf80466bd7c0d975430fb75f3f9655604d2d4aad3725c9e11e.jpg" alt="Focal-systems FT9201 USB-Fingerabdruckleser" width="360">
</p>
Der Sensor ist ein winziger 96×96 optischer Leser. Der eingebaute Matcher von libfprint liefert bei einem so kleinen Bild schlechte Ergebnisse, daher verwendet dieser Treiber stattdessen **FocalTechs eigene Matching-Engine** — die `ftWbioEngineAdapter.dll` aus ihrem signierten Windows-Treiber — und führt sie nativ unter Linux mit einem kleinen In-Prozess-PE-Lader. Kein Wine, kein Windows, keine Cloud.
> **Dieses Repository ist auch eine wiederverwendbare Methode, nicht nur ein einzelner Treiber.** Die Technik — die Windows-Matching-Engine eines Herstellers nativ unter Linux auszuführen, ohne Wine — lässt sich auf andere „nur Windows Hello“-Lesegeräte verallgemeinern, **einschließlich solcher mit einem SDCP-Sicherheitskanal** (die Kryptosensoren der Synaptics/Goodix/ELAN/EgisTec-Klasse), über das optionale Modul [`src/crypto_shims.c`](https://github.com/omgrant/ft9201-libfprint/blob/master/src/crypto_shims.c). Der FT9201 ist das ausgearbeitete Beispiel; der In-Prozess-Lader, die WinBio-Brücke und die Krypto-Bypass-Schicht lassen sich auf das nächste Gerät übertragen. Siehe **[PORTING.md](https://github.com/omgrant/ft9201-libfprint/blob/master/PORTING.md)** für die Schritt-für-Schritt-Methode und was unverändert übernommen werden kann.
## Status
Funktioniert durchgängig auf echter Hardware: Registrieren und Verifizieren über `fprintd` / Befehlszeilenwerkzeuge und nach der Installation in KDE/GNOME. Es vergleicht Ihren Finger mit dem echten Algorithmus des Herstellers.
Entwickelt und getestet mit [diesem speziellen Lesegerät](https://www.amazon.com/dp/B0DK7LQZGH) (ASIN `B0DK7LQZGH`) — der FT9348W-Variante von `2808:93a9`.
Einschränkungen:
- Nur mit dieser FT9348W-Variante des `2808:93a9`-Geräts getestet.
- Der Matcher ist ein proprietäres Blob, das wir aufrufen; wir können keine Fehler darin beheben.
- Nur x86-64 (die DLL und der Lader sind 64-Bit).
## Wie es funktioniert (Kurzfassung)
- Die USB-Initialisierungs- und Firmware-Boot-Sequenz wurde aus FocalTechs eigenen Treibern zurückentwickelt; die 8051-MCU-Firmware wird hochgeladen, dann startet eine spezifische Register-Konfigurationssequenz das Gerät.
- Jeder Capture (96×96) wird auf die vom Motor erwarteten 64×80 zentriert zugeschnitten.
- `ft_engine.c` ist ein etwa 450-zeiliger Lader, der `ftWbioEngineAdapter.dll` in den Speicher abbildet, die etwa 90 von ihr importierten `kernel32`-Funktionen bereitstellt, einen gefälschten Windows-TEB einrichtet und die WinBio-Schnittstelle des Motors für Registrierung/Verifizierung aufruft.
- Der Lader bildet Code als lese-ausführbar und Daten als lese-schreibbar aus einer Datei im Speicher ab, sodass **keine Seite jemals gleichzeitig beschreibbar *und* ausführbar ist**. Das bedeutet, dass er unter der standardmäßigen `MemoryDenyWriteExecute`-Härtung von `fprintd` läuft — Sie müssen **keine** Sicherheitseinstellungen deaktivieren.
Siehe [`docs/how-it-works.md`](https://github.com/omgrant/ft9201-libfprint/blob/master/docs/how-it-works.md) für die vollständige technische Beschreibung.
## Voraussetzungen
Build-Werkzeuge + Build-Abhängigkeiten von libfprint. Auf 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: die Entsprechungen — `libglib2.0-dev libgusb-dev libnss3-dev
libpixman-1-dev libgudev-1.0-dev libsystemd-dev`, plus `cabextract`.)
## Build & Installation
```
git clone https://github.com/OMGrant/ft9201-libfprint
cd ft9201-libfprint
scripts/fetch-blobs.sh # pull the vendor DLL + MCU firmware (see note below)
scripts/build.sh # clone pinned libfprint, graft the driver in, build
```
Probieren Sie es ohne Installation aus:
```
FT9201_ENGINE_DLL=$PWD/blobs/ftWbioEngineAdapter.dll \
LD_LIBRARY_PATH=libfprint/build/libfprint \
libfprint/build/examples/enroll
```
Installieren Sie es für KDE/GNOME/Anmeldung (nebeneinander; die libfprint Ihrer Distribution bleibt unberührt, keine Härtung deaktiviert):
```
sudo scripts/install.sh
fprintd-enroll
```
Alles rückgängig machen: `sudo scripts/install.sh --uninstall`.
## Die proprietären Blobs
Dieses Repository enthält **keine** proprietären Binärdateien. Zwei Dateien gehören FocalTech und werden zur Build-Zeit von `scripts/fetch-blobs.sh` aus vorhandenen öffentlichen Quellen abgerufen:
| Datei | Was es ist | Woher es kommt |
|------|------------|---------------------|
| `ftWbioEngineAdapter.dll` | die Matching-Engine | FocalTechs signierter Windows-Treiber im Microsoft Update Catalog |
| FT9348W MCU-Firmware (`src/ft9201_fw.h`) | 8051-Firmware, die der Sensor ausführt | extrahiert (Symbol `FOCALFP_9348_FW_APP`) aus dem öffentlichen [`ft9201-static`](https://github.com/mrrbrilliant/ft9201-static) Blob |
### Die Blobs manuell beschaffen
Falls einer der Download-URLs nicht mehr funktioniert, benötigen Sie nur diese beiden Dateien:
- **`ftWbioEngineAdapter.dll`** — durchsuchen Sie den Microsoft Update Catalog nach
*"FocalTech Electronics Biometric"* (Treiber 1.0.3.58, passt zur Hardware-ID
`USB\VID_2808&PID_93A9`). Laden Sie die `.cab` herunter, extrahieren Sie sie mit `cabextract` und
legen Sie `ftWbioEngineAdapter.dll` in `blobs/` ab.
- **MCU-Firmware** — besorgen Sie sich eine beliebige Kopie des FocalTech Linux libfprint-Blobs, das
das Symbol `FOCALFP_9348_FW_APP` enthält (z. B. aus `ft9201-static`) und führen Sie
`python3 scripts/extract-firmware.py <diese-libfprint-2.so> src/ft9201_fw.h` aus.
Führen Sie dann erneut `scripts/build.sh` aus.
## Danksagungen
- USB-Protokoll ursprünglich zurückentwickelt von
[banianitc/ft9201-fingerprint-driver](https://github.com/banianitc/ft9201-fingerprint-driver).
- Firmware und die Init-/Boot-Sequenz wurden mit FocalTechs Linux-Blob über
[mrrbrilliant/ft9201-static](https://github.com/mrrbrilliant/ft9201-static) abgeglichen.
- Basierend auf [libfprint](https://gitlab.freedesktop.org/libfprint/libfprint).
Die wiederverwendbare Methode und der Kryptosensor-Pfad bauen zusätzlich auf der Arbeit dieser Personen auf:
- **[uunicorn](https://github.com/uunicorn)** — dessen
[synaWudfBioUsb-sandbox](https://github.com/uunicorn/synaWudfBioUsb-sandbox) und
[Wine-Fork](https://github.com/uunicorn/wine) die Umgebung zum Verfolgen eines Windows-Biometrietreibers eines Herstellers unter Wine sind, wodurch das Befehlsprotokoll eines Kryptosensors ohne eine Windows-Box wiederhergestellt wird.
- **Marco Trevisan ([3v1n0](https://github.com/3v1n0))**, ein libfprint-Maintainer —
der den Weg zu diesem Wine-Tracing-Ansatz wies und dessen Bestreben, libfprints eigenes Matching zu verbessern, den Rahmen dafür liefert, warum der Hersteller-Matcher-Weg überhaupt existiert.
- **[championswimmer/libfprint-eh577](https://github.com/championswimmer/libfprint-eh577)**
— Vorarbeit für die EgisTec EH577-Sensorfamilie.
## Andere Möglichkeiten, einen FT9201 unter Linux zu betreiben
Dies ist nicht der einzige Ansatz — die Alternativen unterscheiden sich hauptsächlich darin, *wie* sie FocalTechs Matcher wiederverwenden (das tun sie alle; der winzige Sensor schließt generisches Matching aus).
- **[Romk-a/ft9201-linux-setup](https://github.com/Romk-a/ft9201-linux-setup)** — eine
Debian/Ubuntu (Astra Linux)-Anleitung, die FocalTechs **vorgebauten proprietären Linux „TOD“-Treiber** installiert (von
[ryenyuku/libfprint-ft9201](https://github.com/ryenyuku/libfprint-ft9201); Fedora-RPMs gab es auch)
und per Binärpatch dessen USB-ID-Tabelle (`9338` → `93a9`) ändert.
- **Wie es sich vergleicht:** dieser Weg ist *weniger Arbeit* — ein `.deb` installieren, zwei Bytes patchen,
keine Rückentwicklung. Aber er erfordert **TOD-fähiges libfprint**
(Debian/Ubuntu-Familie; **nicht** auf Standard-Fedora/Arch), er **ersetzt Ihr gesamtes
System-libfprint** durch einen alten, vollständig geschlossenen Build, und Sie müssen sich mit dem Paketmanager herumschlagen, um es fixiert zu halten. Dieses Projekt liefert stattdessen einen **offenen** Treiber, installiert
**nebeneinander** (die libfprint Ihrer Distribution bleibt unberührt), läuft auf
**mainline libfprint ohne TOD** und lädt nur die isolierte, herstellereigene *Matcher*-DLL —
was den gesamten Rückentwicklungsaufwand ausmacht.
- **Kurzfassung:** auf Debian/Ubuntu ist der TOD-Weg der einfache Knopf; auf
Fedora/Arch, oder wenn Sie es offen und nicht-invasiv möchten, verwenden Sie dieses.
- **Kernel-Treiber** existieren ([banianitc](https://github.com/banianitc/ft9201-fingerprint-driver)
— die Protokollreferenz, von der dieses Projekt zurückentwickelt wurde,
[bm16ton/ft92010x9338](https://github.com/bm16ton/ft92010x9338)), aber sie integrieren sich nicht in libfprint/fprintd, daher gibt es keine Anmelde-/PAM-Unterstützung.
Der proprietäre Linux TOD-Treiber, den diese `.deb`/RPM-Pakete weiterverteilen, scheint eine FocalTech/GPD-Veröffentlichung für das GPD Win 4 gewesen zu sein, die später **aus dem offiziellen Vertrieb genommen wurde** — weshalb er heute nur noch als Community-Neubereitstellungen überlebt. (Beachten Sie auch, dass einige GPD Win 4-Geräte einen völlig anderen Sensor enthalten, einen Chipsailing CS9711, nicht dieses FocalTech-Teil.)
## Verwandte Projekte
- [championswimmer/libfprint-eh577](https://github.com/championswimmer/libfprint-eh577)
— ein Linux-Treiberprojekt für den **EgisTec EH577** (`1c7a:0577`), ein weiteres Drucktyp-„nur Windows Hello“-Lesegerät (52×72 aktiver Sensor).
Anderer Hersteller und USB-Protokoll, aber die gleiche *Match-on-Host*-Struktur: Sein Windows-Paket enthält
eine DLL des Hersteller-Engine-Adapters (`EgisTouchFPEngine0577.dll`, keine VBS-Enklave), daher
ist die Methode in **[PORTING.md](https://github.com/omgrant/ft9201-libfprint/blob/master/PORTING.md)** auch darauf anwendbar.
- **[OMGrant/eh577-libfprint](https://github.com/OMGrant/eh577-libfprint)** — diese
Methode wurde durchgehend auf den **EgisTec EH577** übertragen und als funktionierender Treiber veröffentlicht.
Die §3b-Kryptotechniken wurden gegen seine SDCP-Builds validiert; der verteilte Treiber zielt auf einen
*Pre-SDCP*-Katalog-Build (einen reinen Software-Matcher — siehe §3b's Hinweis zur Build-Auswahl),
registriert und verifiziert echte Finger unter Linux.
## Lizenz
Der Treiber und der Lader (`src/`, `scripts/`) sind **LGPL-2.1-or-later**, entsprechend libfprint.
Die FocalTech-DLL und -Firmware sind ihr eigenes Eigentum und werden hier nicht verteilt — Sie besorgen sie selbst.
Dieses Projekt ist ein Interoperabilitätswerkzeug für Hardware, die Sie besitzen; es enthält keinen FocalTech-Code
und lizenziert diesen auch nicht neu.