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.

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. 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 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 (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 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:

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.
• Il firmware e la sequenza di init/avvio sono stati incrociati con il blob Linux di FocalTech tramite mrrbrilliant/ft9201-static.
• Basato su libfprint.

Il metodo riutilizzabile e il percorso per sensori crittografici si basano inoltre sul lavoro di:

• uunicorn — il cui synaWudfBioUsb-sandbox e fork di 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), 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 — 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 — una guida Debian/Ubuntu (Astra Linux) che installa il driver Linux "TOD" proprietario precompilato di FocalTech (da 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 — il riferimento di protocollo da cui questo progetto ha fatto reverse-engineering, 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 — 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 si applica anche a lui.
• 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.