omgrant/ft9201-libfprintDriver Linux libfprint per il lettore di impronte digitali USB Focal-systems FT9201 (2808:93a9) — esegue il motore di corrispondenza Windows di FocalTech nativamente su Linux, senza Wine. Include un metodo per portare altri lettori solo Windows Hello.
# ft9201-libfprint
Supporto per impronte digitali su Linux per il lettore USB **Focal-systems FT9201**
(`2808:93a9`, venduto come dongle standalone per Windows Hello), come driver
[libfprint](https://gitlab.freedesktop.org/libfprint/libfprint).
<p align="center">
<img src="https://assets.kitploit.com/production/public/readmes/7029/9a4eac4876063dbf80466bd7c0d975430fb75f3f9655604d2d4aad3725c9e11e.jpg" alt="Lettore di impronte digitali USB Focal-systems FT9201" width="360">
</p>
Il sensore è un minuscolo lettore ottico 96×96. Il matcher integrato di libfprint lavora
male su un'immagine così piccola, quindi questo driver riutilizza invece **il motore di
riconoscimento di FocalTech** — il `ftWbioEngineAdapter.dll` del loro driver Windows
firmato — eseguendolo nativamente su Linux con un piccolo caricatore PE in-process.
Niente Wine, niente Windows, niente cloud.
> **Questa repo è anche un metodo riutilizzabile, non solo un driver.** La tecnica —
> eseguire il motore di riconoscimento Windows di un vendor nativamente su Linux, senza
> Wine — si generalizza ad altri lettori "solo Windows Hello", **inclusi quelli che
> forniscono un canale sicuro SDCP** (i sensori crittografici classe Synaptics/Goodix/ELAN/EgisTec),
> tramite il modulo opzionale [`src/crypto_shims.c`](https://github.com/omgrant/ft9201-libfprint/blob/master/src/crypto_shims.c). Il FT9201 è
> l'esempio pratico; il caricatore in-process, il bridge WinBio e il livello di bypass
> crittografico sono trasferibili al prossimo dispositivo. Vedi **[PORTING.md](https://github.com/omgrant/ft9201-libfprint/blob/master/PORTING.md)**
> per il metodo passo-passo e cosa riutilizzare così com'è.
## Stato
Funzionante end-to-end su hardware reale: enroll e verify tramite `fprintd` /
strumenti da riga di comando, e in KDE/GNOME dopo l'installazione. Riconosce il dito
usando il vero algoritmo del vendor.
Sviluppato e testato con
[questo esatto lettore](https://www.amazon.com/dp/B0DK7LQZGH) (ASIN `B0DK7LQZGH`) —
la variante FT9348W del `2808:93a9`.
Avvertenze:
- Testato solo su quella variante FT9348W del dispositivo `2808:93a9`.
- Il matcher è un blob proprietario che chiamiamo; non possiamo correggere bug al suo interno.
- Solo x86-64 (la DLL e il caricatore sono a 64 bit).
## Come funziona (versione breve)
- La sequenza di init USB + avvio firmware è stata reverse-engineered dai driver stessi di
FocalTech; il firmware MCU 8051 viene caricato, poi una specifica sequenza di
configurazione registri lo avvia.
- Ogni acquisizione (96×96) viene ritagliata al centro a 64×80, come richiesto dal motore.
- `ft_engine.c` è un caricatore di ~450 righe che mappa `ftWbioEngineAdapter.dll` in
memoria, fornisce le ~90 funzioni `kernel32` che importa, imposta un falso TEB Windows,
e chiama l'interfaccia WinBio del motore per enroll/verify.
- Il caricatore mappa il codice come read-execute e i dati come read-write da un file in
memoria, quindi **nessuna pagina è mai scrivibile *ed* eseguibile**. Ciò significa che
funziona sotto l'hardening predefinito `MemoryDenyWriteExecute` di `fprintd` — **non**
devi disabilitare alcuna impostazione di sicurezza.
Vedi [`docs/how-it-works.md`](https://github.com/omgrant/ft9201-libfprint/blob/master/docs/how-it-works.md) per la documentazione tecnica completa.
## Requisiti
Strumenti di build + dipendenze di build di libfprint. Su 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: gli equivalenti — `libglib2.0-dev libgusb-dev libnss3-dev
libpixman-1-dev libgudev-1.0-dev libsystemd-dev`, più `cabextract`.)
## Build e installazione
```
git clone https://github.com/OMGrant/ft9201-libfprint
cd ft9201-libfprint
scripts/fetch-blobs.sh # scarica la DLL del vendor + firmware MCU (vedi nota sotto)
scripts/build.sh # clona libfprint fissato, innesta il driver, compila
```
Prova senza installare nulla:
```
FT9201_ENGINE_DLL=$PWD/blobs/ftWbioEngineAdapter.dll \
LD_LIBRARY_PATH=libfprint/build/libfprint \
libfprint/build/examples/enroll
```
Installalo per KDE/GNOME/login (affiancato; il libfprint della tua distribuzione viene
lasciato intatto, nessun hardening disabilitato):
```
sudo scripts/install.sh
fprintd-enroll
```
Annulla tutto: `sudo scripts/install.sh --uninstall`.
## I blob proprietari
Questa repo **non contiene** binari proprietari. Due file sono di FocalTech e vengono
recuperati da fonti pubbliche esistenti al momento della build da `scripts/fetch-blobs.sh`:
| File | Cosa è | Da dove proviene |
|------|--------|------------------|
| `ftWbioEngineAdapter.dll` | il motore di riconoscimento | Driver Windows firmato di FocalTech dal Microsoft Update Catalog |
| Firmware MCU FT9348W (`src/ft9201_fw.h`) | Firmware 8051 eseguito dal sensore | estratto (simbolo `FOCALFP_9348_FW_APP`) dal blob pubblico [`ft9201-static`](https://github.com/mrrbrilliant/ft9201-static) |
### Recupero manuale dei blob
Se uno degli URL di download è cambiato, ti servono solo questi due file:
- **`ftWbioEngineAdapter.dll`** — cerca nel Microsoft Update Catalog
*"FocalTech Electronics Biometric"* (driver 1.0.3.58, corrisponde all'hardware ID
`USB\VID_2808&PID_93A9`). Scarica il `.cab`, estrai con `cabextract`, e
metti `ftWbioEngineAdapter.dll` in `blobs/`.
- **Firmware MCU** — ottieni una copia del blob Linux libfprint di FocalTech che
contiene il simbolo `FOCALFP_9348_FW_APP` (ad es. da `ft9201-static`) ed esegui
`python3 scripts/extract-firmware.py <quel-libfprint-2.so> src/ft9201_fw.h`.
Poi esegui di nuovo `scripts/build.sh`.
## Crediti
- Il protocollo USB è stato originariamente reverse-engineered da
[banianitc/ft9201-fingerprint-driver](https://github.com/banianitc/ft9201-fingerprint-driver).
- Il firmware e la sequenza di init/avvio sono stati incrociati con il blob Linux di
FocalTech tramite [mrrbrilliant/ft9201-static](https://github.com/mrrbrilliant/ft9201-static).
- Basato su [libfprint](https://gitlab.freedesktop.org/libfprint/libfprint).
Il metodo riutilizzabile e il percorso per sensori crittografici si basano inoltre sul
lavoro di:
- **[uunicorn](https://github.com/uunicorn)** — il cui
[synaWudfBioUsb-sandbox](https://github.com/uunicorn/synaWudfBioUsb-sandbox) e
[fork di wine](https://github.com/uunicorn/wine) sono l'infrastruttura per tracciare
un driver biometrico Windows di un vendor sotto Wine, che è come si recupera il
protocollo di comando di un sensore crittografico senza una macchina Windows.
- **Marco Trevisan ([3v1n0](https://github.com/3v1n0))**, un manutentore di libfprint —
che ha indicato la strada a quell'approccio di tracciamento con Wine, e la cui spinta
a migliorare il matcher principale di libfprint a monte spiega perché esista la via
del matcher del vendor.
- **[championswimmer/libfprint-eh577](https://github.com/championswimmer/libfprint-eh577)**
— lavoro precedente per la famiglia di sensori EgisTec EH577.
## Altri modi per eseguire un FT9201 su Linux
Non è l'unico approccio — le alternative differiscono principalmente in *come* riutilizzano
il matcher di FocalTech (lo fanno tutte; il minuscolo sensore esclude il matching generico).
- **[Romk-a/ft9201-linux-setup](https://github.com/Romk-a/ft9201-linux-setup)** — una
guida Debian/Ubuntu (Astra Linux) che installa il **driver Linux "TOD" proprietario
precompilato di FocalTech** (da
[ryenyuku/libfprint-ft9201](https://github.com/ryenyuku/libfprint-ft9201); sono
esistiti anche RPM Fedora) e applica patch binarie alla sua tabella ID USB (`9338` → `93a9`).
- **Come si confronta:** quella via è *meno lavoro* — installa un `.deb`, patch due byte,
nessun reverse-engineering. Ma richiede **libfprint abilitato per TOD**
(famiglia Debian/Ubuntu; **non** su Fedora/Arch standard), **sostituisce l'intero
`libfprint` di sistema** con una build vecchia e completamente chiusa, e devi
combattere con il gestore pacchetti per tenerlo bloccato. Questo progetto invece
fornisce un driver **aperto**, si installa **affiancato** (il libfprint della tua
distribuzione è intoccato), funziona su **libfprint principale senza TOD**, e carica
solo il *matcher* DLL isolato del vendor — che è ciò che tutto il reverse-engineering
ha comprato.
- **Versione breve:** su Debian/Ubuntu, la via TOD è il pulsante facile; su
Fedora/Arch, o se lo vuoi aperto e non invasivo, usa questo.
- **Driver del kernel** esistono ([banianitc](https://github.com/banianitc/ft9201-fingerprint-driver)
— il riferimento di protocollo da cui questo progetto ha fatto reverse-engineering,
[bm16ton/ft92010x9338](https://github.com/bm16ton/ft92010x9338)) ma non si integrano
con libfprint/fprintd, quindi non c'è supporto per login/PAM.
Il driver Linux TOD proprietario che quei pacchetti `.deb`/RPM ridistribuiscono sembra
essere stato un rilascio FocalTech/GPD per il GPD Win 4 che è stato successivamente
**ritirato dalla distribuzione ufficiale** — motivo per cui sopravvive solo come
re-hosting della community. (Nota anche che alcuni GPD Win 4 montano un sensore
completamente diverso, un Chipsailing CS9711, non questo componente FocalTech.)
## Progetti correlati
- [championswimmer/libfprint-eh577](https://github.com/championswimmer/libfprint-eh577)
— uno sforzo driver Linux per **EgisTec EH577** (`1c7a:0577`), un altro lettore
"solo Windows Hello" a pressione (sensore attivo 52×72). Vendor e protocollo USB
diversi, ma la stessa forma *match-on-host*: il suo pacchetto Windows include una
DLL adapter del motore del vendor (`EgisTouchFPEngine0577.dll`, senza enclave VBS),
quindi il metodo in **[PORTING.md](https://github.com/omgrant/ft9201-libfprint/blob/master/PORTING.md)** si applica anche a lui.
- **[OMGrant/eh577-libfprint](https://github.com/OMGrant/eh577-libfprint)** — questo
metodo portato end-to-end su **EgisTec EH577** e pubblicato come driver funzionante.
Le tecniche crittografiche §3b sono state validate contro le sue build SDCP; il driver
distribuito ha come target una build del Catalogo *pre-SDCP* (un matcher puramente
software — vedi nota §3b sulla selezione della build), eseguendo enroll e verify di
dita reali su Linux.
## Licenza
Il driver e il caricatore (`src/`, `scripts/`) sono **LGPL-2.1-or-later**, in
corrispondenza con libfprint. La DLL e il firmware FocalTech sono di loro proprietà e
non vengono distribuiti qui — li recuperi tu stesso. Questo progetto è uno strumento
di interoperabilità per hardware che possiedi; non include né ri-licenzia alcun codice
FocalTech.