omgrant/ft9201-libfprintPilote Linux libfprint pour le lecteur d'empreintes digitales USB Focal-systems FT9201 (2808:93a9) — exécute le moteur de correspondance Windows de FocalTech nativement sous Linux, sans Wine. Inclut une méthode pour porter d'autres lecteurs réservés à Windows Hello.
# ft9201-libfprint
Prise en charge des empreintes digitales sous Linux pour le lecteur USB **Focal-systems FT9201**
(`2808:93a9`, vendu comme un dongle Windows Hello autonome), en tant que pilote
[libfprint](https://gitlab.freedesktop.org/libfprint/libfprint).
<p align="center">
<img src="https://assets.kitploit.com/production/public/readmes/7029/9a4eac4876063dbf80466bd7c0d975430fb75f3f9655604d2d4aad3725c9e11e.jpg" alt="Lecteur d'empreintes digitales USB Focal-systems FT9201" width="360">
</p>
Le capteur est un minuscule lecteur optique 96×96. Le comparateur intégré de libfprint fait
un mauvais travail sur une image aussi petite, donc ce pilote réutilise plutôt **le propre moteur de correspondance de FocalTech**
— le `ftWbioEngineAdapter.dll` de leur pilote Windows signé —
en l'exécutant nativement sous Linux avec un petit chargeur PE en processus. Pas de Wine,
pas de Windows, pas de cloud.
> **Ce dépôt est aussi une méthode réutilisable, pas seulement un pilote.** La technique —
> exécuter le moteur de correspondance Windows d'un fabricant nativement sous Linux, sans Wine —
> se généralise à d'autres lecteurs « Windows Hello uniquement », **y compris ceux qui embarquent un
> canal sécurisé SDCP** (les capteurs crypto de classe Synaptics/Goodix/ELAN/EgisTec),
> via le module optionnel [`src/crypto_shims.c`](https://github.com/omgrant/ft9201-libfprint/blob/master/src/crypto_shims.c). Le FT9201 est
> l'exemple pratique ; le chargeur en processus, le pont WinBio et la couche de
> contournement crypto sont réutilisables pour le prochain périphérique. Voir **[PORTING.md](https://github.com/omgrant/ft9201-libfprint/blob/master/PORTING.md)**
> pour la méthode pas à pas et ce qui peut être réutilisé tel quel.
## Statut
Fonctionne de bout en bout sur du matériel réel : inscription et vérification via `fprintd` /
outils en ligne de commande, et dans KDE/GNOME une fois installé. Il fait correspondre votre doigt
en utilisant le véritable algorithme du fabricant.
Développé et testé avec
[ce lecteur exact](https://www.amazon.com/dp/B0DK7LQZGH) (ASIN `B0DK7LQZGH`) —
la variante FT9348W du `2808:93a9`.
Limitations :
- Testé uniquement sur cette variante FT9348W du périphérique `2808:93a9`.
- Le comparateur est un binaire propriétaire que nous appelons ; nous ne pouvons pas corriger les bugs à l'intérieur.
- x86-64 uniquement (la DLL et le chargeur sont en 64 bits).
## Comment ça fonctionne (version courte)
- L'initialisation USB + la séquence de démarrage du firmware ont été rétro-conçues à partir des
propres pilotes de FocalTech ; le firmware du microcontrôleur 8051 est chargé, puis une séquence
spécifique de configuration de registre le démarre.
- Chaque capture (96×96) est recadrée au centre pour obtenir le 64×80 attendu par le moteur.
- `ft_engine.c` est un chargeur d'environ 450 lignes qui mappe `ftWbioEngineAdapter.dll` en
mémoire, fournit les ~90 fonctions `kernel32` qu'il importe, configure un faux
TEB Windows, et appelle l'interface WinBio du moteur pour l'inscription/vérification.
- Le chargeur mappe le code en lecture-exécution et les données en lecture-écriture depuis un fichier
en mémoire, donc **aucune page n'est jamais accessible en écriture *et* exécutable**. Cela signifie qu'il fonctionne sous
le durcissement `MemoryDenyWriteExecute` par défaut de `fprintd` — vous n'avez **pas** à
désactiver de paramètres de sécurité.
Voir [`docs/how-it-works.md`](https://github.com/omgrant/ft9201-libfprint/blob/master/docs/how-it-works.md) pour le compte rendu technique complet.
## Prérequis
Outils de compilation + dépendances de construction de libfprint. Sur 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 : les équivalents — `libglib2.0-dev libgusb-dev libnss3-dev
libpixman-1-dev libgudev-1.0-dev libsystemd-dev`, plus `cabextract`.)
## Construction et installation
```
git clone https://github.com/OMGrant/ft9201-libfprint
cd ft9201-libfprint
scripts/fetch-blobs.sh # récupérer la DLL du fabricant + le firmware MCU (voir note ci-dessous)
scripts/build.sh # cloner libfprint épinglé, greffer le pilote, construire
```
Essayez sans rien installer :
```
FT9201_ENGINE_DLL=$PWD/blobs/ftWbioEngineAdapter.dll \
LD_LIBRARY_PATH=libfprint/build/libfprint \
libfprint/build/examples/enroll
```
Installez-le pour KDE/GNOME/connexion (côte à côte ; la bibliothèque libfprint de votre distribution
est laissée intacte, aucun durcissement désactivé) :
```
sudo scripts/install.sh
fprintd-enroll
```
Tout annuler : `sudo scripts/install.sh --uninstall`.
## Les binaires propriétaires
Ce dépôt ne contient **aucun** binaire propriétaire. Deux fichiers appartiennent à FocalTech et sont
récupérés depuis des sources publiques existantes lors de la construction par `scripts/fetch-blobs.sh` :
| Fichier | Ce que c'est | D'où ça vient |
|---------|--------------|---------------|
| `ftWbioEngineAdapter.dll` | le moteur de correspondance | Le pilote Windows signé de FocalTech sur le Catalogue Microsoft Update |
| Firmware MCU FT9348W (`src/ft9201_fw.h`) | Firmware 8051 exécuté par le capteur | extrait (symbole `FOCALFP_9348_FW_APP`) du binaire public [`ft9201-static`](https://github.com/mrrbrilliant/ft9201-static) |
### Récupérer les binaires manuellement
Si l'une des URL de téléchargement a changé, vous n'avez besoin que de ces deux fichiers :
- **`ftWbioEngineAdapter.dll`** — recherchez sur le Catalogue Microsoft Update
*« FocalTech Electronics Biometric »* (pilote 1.0.3.58, correspondant à l'ID matériel
`USB\VID_2808&PID_93A9`). Téléchargez le `.cab`, extrayez-le avec `cabextract` et
placez `ftWbioEngineAdapter.dll` dans `blobs/`.
- **Firmware MCU** — obtenez n'importe quelle copie du binaire libfprint Linux de FocalTech qui
contient le symbole `FOCALFP_9348_FW_APP` (par exemple depuis `ft9201-static`) et lancez
`python3 scripts/extract-firmware.py <ce-libfprint-2.so> src/ft9201_fw.h`.
Ensuite, relancez `scripts/build.sh`.
## Crédits
- Le protocole USB a été initialement rétro-conçu par
[banianitc/ft9201-fingerprint-driver](https://github.com/banianitc/ft9201-fingerprint-driver).
- Le firmware et la séquence d'initialisation/démarrage ont été recoupés avec le binaire Linux de FocalTech via
[mrrbrilliant/ft9201-static](https://github.com/mrrbrilliant/ft9201-static).
- Construit sur [libfprint](https://gitlab.freedesktop.org/libfprint/libfprint).
La méthode réutilisable et le chemin pour les capteurs crypto s'appuient également sur les travaux de :
- **[uunicorn](https://github.com/uunicorn)** — dont
[synaWudfBioUsb-sandbox](https://github.com/uunicorn/synaWudfBioUsb-sandbox) et
[fourche Wine](https://github.com/uunicorn/wine) sont le harnais pour tracer le
pilote biométrique Windows d'un fabricant sous Wine, ce qui permet de récupérer le protocole
de commande d'un capteur crypto sans machine Windows.
- **Marco Trevisan ([3v1n0](https://github.com/3v1n0))**, un mainteneur de libfprint —
qui a indiqué la voie vers cette approche de traçage sous Wine, et dont l'impulsion pour améliorer
la correspondance propre de libfprint en amont cadre pourquoi la voie du comparateur fabricant
existe.
- **[championswimmer/libfprint-eh577](https://github.com/championswimmer/libfprint-eh577)**
— travaux antérieurs pour la famille de capteurs EgisTec EH577.
## Autres façons d'utiliser un FT9201 sous Linux
Ce n'est pas la seule approche — les alternatives diffèrent principalement par *comment* elles
réutilisent le comparateur de FocalTech (elles le font toutes ; le minuscule capteur exclut
la correspondance générique).
- **[Romk-a/ft9201-linux-setup](https://github.com/Romk-a/ft9201-linux-setup)** — un
guide Debian/Ubuntu (Astra Linux) qui installe le **pilote Linux « TOD » propriétaire précompilé de FocalTech** (depuis
[ryenyuku/libfprint-ft9201](https://github.com/ryenyuku/libfprint-ft9201) ; des RPM Fedora
ont aussi existé) et patche binairement sa table d'IDs USB (`9338` → `93a9`).
- **Comparaison :** cette voie demande *moins de travail* — installer un `.deb`, patcher deux
octets, pas de rétro-ingénierie. Mais elle nécessite **libfprint compatible TOD**
(famille Debian/Ubuntu ; **pas** sur Fedora/Arch standard), elle **remplace toute votre
`libfprint` système** par une ancienne construction entièrement fermée, et vous devez lutter
contre le gestionnaire de paquets pour la garder épinglée. Ce projet livre plutôt un pilote
**ouvert**, s'installe **côte à côte** (la libfprint de votre distribution est intacte),
fonctionne sur **libfprint standard sans TOD**, et ne charge que la DLL du comparateur
propriétaire isolée — c'est ce que la rétro-ingénierie a apporté.
- **En résumé :** sur Debian/Ubuntu, la voie TOD est le bouton facile ; sur
Fedora/Arch, ou si vous voulez quelque chose d'ouvert et non invasif, utilisez ce projet.
- **Des pilotes noyau** existent ([banianitc](https://github.com/banianitc/ft9201-fingerprint-driver)
— la référence de protocole que ce projet a rétro-conçue,
[bm16ton/ft92010x9338](https://github.com/bm16ton/ft92010x9338)) mais ils ne
s'intègrent pas avec libfprint/fprintd, donc pas de support pour la connexion/PAM.
Le pilote Linux TOD propriétaire que ces paquets `.deb`/RPM redistribuent semble avoir été
une version FocalTech/GPD pour le GPD Win 4 qui a ensuite été **retirée de la distribution
officielle** — c'est pourquoi elle ne survit aujourd'hui que sous forme de réhébergements
communautaires. (Notez aussi que certains GPD Win 4 sont livrés avec un capteur entièrement
différent, un Chipsailing CS9711, et non cette pièce FocalTech.)
## Projets connexes
- [championswimmer/libfprint-eh577](https://github.com/championswimmer/libfprint-eh577)
— un effort de pilote Linux pour l'**EgisTec EH577** (`1c7a:0577`), un autre
lecteur « Windows Hello uniquement » de type presse (capteur actif 52×72). Fabricant
et protocole USB différents, mais la même forme *correspondance sur l'hôte* : son pack Windows
contient une DLL d'adaptateur de moteur fabricant (`EgisTouchFPEngine0577.dll`, sans enclave VBS),
donc la méthode décrite dans **[PORTING.md](https://github.com/omgrant/ft9201-libfprint/blob/master/PORTING.md)** s'y applique aussi.
- **[OMGrant/eh577-libfprint](https://github.com/OMGrant/eh577-libfprint)** — cette
méthode appliquée de bout en bout à l'**EgisTec EH577** et publiée sous forme de pilote
fonctionnel. Les techniques crypto de la §3b ont été validées contre ses constructions SDCP ;
le pilote distribué cible une construction *pré-SDCP* du Catalogue (un comparateur purement
logiciel — voir la note de la §3b sur le choix de la construction), qui inscrit et vérifie
de vraies empreintes sous Linux.
## Licence
Le pilote et le chargeur (`src/`, `scripts/`) sont sous **LGPL-2.1-ou-ultérieure**, en
accord avec libfprint. La DLL et le firmware FocalTech sont leur propre propriété et ne sont
pas distribués ici — vous les récupérez vous-même. Ce projet est un outil d'interopérabilité
pour du matériel que vous possédez ; il n'inclut ni ne relicencie aucun code FocalTech.