ft9201-libfprint

# ft9201-libfprint

Soporte de huellas dactilares en Linux para el lector USB **Focal-systems FT9201**
(`2808:93a9`, vendido como un dongle independiente de Windows Hello), como un
controlador de [libfprint](https://gitlab.freedesktop.org/libfprint/libfprint).

<p align="center">
  <img src="https://assets.kitploit.com/production/public/readmes/7029/9a4eac4876063dbf80466bd7c0d975430fb75f3f9655604d2d4aad3725c9e11e.jpg" alt="Lector de huellas dactilares USB Focal-systems FT9201" width="360">
</p>

El sensor es un diminuto lector óptico de 96×96. El comparador incorporado de libfprint
funciona mal con una imagen tan pequeña, por lo que este controlador reutiliza el **motor de comparación propio de FocalTech**
— el `ftWbioEngineAdapter.dll` de su controlador Windows firmado —
ejecutándolo de forma nativa en Linux con un pequeño cargador PE en proceso. Sin Wine,
sin Windows, sin nube.

> **Este repositorio también es un método reutilizable, no solo un controlador.** La técnica —
> ejecutar el motor de comparación de Windows de un proveedor de forma nativa en Linux, sin Wine —
> se generaliza a otros lectores "solo Windows Hello", **incluyendo aquellos que incorporan un
> canal seguro SDCP** (los sensores criptográficos de clase Synaptics/Goodix/ELAN/EgisTec),
> a través del módulo opcional [`src/crypto_shims.c`](https://github.com/omgrant/ft9201-libfprint/blob/master/src/crypto_shims.c). El FT9201 es
> el ejemplo práctico; el cargador en proceso, el puente WinBio y la capa de omisión criptográfica
> se trasladan al siguiente dispositivo. Consulte **[PORTING.md](https://github.com/omgrant/ft9201-libfprint/blob/master/PORTING.md)**
> para conocer el método paso a paso y qué reutilizar tal cual.

## Estado

Funciona de principio a fin en hardware real: inscripción y verificación a través de `fprintd` /
herramientas de línea de comandos, y en KDE/GNOME una vez instalado. Reconoce su huella
usando el algoritmo real del proveedor.

Desarrollado y probado con
[este lector exacto](https://www.amazon.com/dp/B0DK7LQZGH) (ASIN `B0DK7LQZGH`) —
la variante FT9348W de `2808:93a9`.

Advertencias:
- Probado solo en esa variante FT9348W del dispositivo `2808:93a9`.
- El comparador es un binario propietario al que llamamos; no podemos corregir errores dentro de él.
- Solo x86-64 (la DLL y el cargador son de 64 bits).

## Cómo funciona (versión corta)

- La secuencia de inicio USB + carga del firmware fue obtenida mediante ingeniería inversa de los
  controladores propios de FocalTech; el firmware de la MCU 8051 se carga, luego una secuencia específica
  de configuración de registros lo inicia.
- Cada captura (96×96) se recorta al centro a los 64×80 que espera el motor.
- `ft_engine.c` es un cargador de ~450 líneas que mapea `ftWbioEngineAdapter.dll` en
  memoria, proporciona las ~90 funciones `kernel32` que importa, configura un TEB ficticio de Windows
  y llama a la interfaz WinBio del motor para inscripción/verificación.
- El cargador mapea el código como lectura-ejecución y los datos como lectura-escritura desde un archivo en memoria,
  por lo que **ninguna página es a la vez escribible *y* ejecutable**. Eso significa que se ejecuta bajo
  el endurecimiento `MemoryDenyWriteExecute` predeterminado de `fprintd` — **no** tiene que
  desactivar ninguna opción de seguridad.

Consulte [`docs/how-it-works.md`](https://github.com/omgrant/ft9201-libfprint/blob/master/docs/how-it-works.md) para el informe técnico completo.

## Requisitos

Herramientas de compilación + dependencias de compilación de libfprint. En 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: los equivalentes — `libglib2.0-dev libgusb-dev libnss3-dev
libpixman-1-dev libgudev-1.0-dev libsystemd-dev`, más `cabextract`.)

## Compilar e instalar

```
git clone https://github.com/OMGrant/ft9201-libfprint
cd ft9201-libfprint
scripts/fetch-blobs.sh     # obtiene la DLL del proveedor + firmware de la MCU (ver nota abajo)
scripts/build.sh           # clona libfprint fijado, injerta el controlador, compila
```

Pruébelo sin instalar nada:

```
FT9201_ENGINE_DLL=$PWD/blobs/ftWbioEngineAdapter.dll \
LD_LIBRARY_PATH=libfprint/build/libfprint \
libfprint/build/examples/enroll
```

Instálelo para KDE/GNOME/inicio de sesión (de forma paralela; la libfprint de su distribución
no se toca, no se desactiva ningún endurecimiento):

```
sudo scripts/install.sh
fprintd-enroll
```

Deshacer todo: `sudo scripts/install.sh --uninstall`.

## Los binarios propietarios

Este repositorio **no** contiene binarios propietarios. Dos archivos son de FocalTech y se
obtienen de fuentes públicas existentes en tiempo de compilación mediante `scripts/fetch-blobs.sh`:

| Archivo | Qué es | De dónde viene |
|---------|--------|----------------|
| `ftWbioEngineAdapter.dll` | el motor de comparación | Controlador Windows firmado de FocalTech en el Catálogo de Actualizaciones de Microsoft |
| Firmware MCU FT9348W (`src/ft9201_fw.h`) | Firmware 8051 que ejecuta el sensor | extraído (símbolo `FOCALFP_9348_FW_APP`) del binario público [`ft9201-static`](https://github.com/mrrbrilliant/ft9201-static) |

### Obteniendo los binarios manualmente

Si alguna URL de descarga se ha movido, solo necesita esos dos archivos:

- **`ftWbioEngineAdapter.dll`** — busque en el Catálogo de Actualizaciones de Microsoft
  *"FocalTech Electronics Biometric"* (controlador 1.0.3.58, coincide con el ID de hardware
  `USB\VID_2808&PID_93A9`). Descargue el `.cab`, extraiga con `cabextract` y
  coloque `ftWbioEngineAdapter.dll` en `blobs/`.
- **Firmware MCU** — obtenga cualquier copia del binario Linux libfprint de FocalTech que
  contenga el símbolo `FOCALFP_9348_FW_APP` (p. ej., de `ft9201-static`) y ejecute
  `python3 scripts/extract-firmware.py <ese-libfprint-2.so> src/ft9201_fw.h`.

Luego vuelva a ejecutar `scripts/build.sh`.

## Créditos

- Protocolo USB originalmente sometido a ingeniería inversa por
  [banianitc/ft9201-fingerprint-driver](https://github.com/banianitc/ft9201-fingerprint-driver).
- Firmware y secuencia de inicio/carga cotejados con el binario Linux de FocalTech a través de
  [mrrbrilliant/ft9201-static](https://github.com/mrrbrilliant/ft9201-static).
- Construido sobre [libfprint](https://gitlab.freedesktop.org/libfprint/libfprint).

El método reutilizable y la ruta del sensor criptográfico se basan adicionalmente en el trabajo de:

- **[uunicorn](https://github.com/uunicorn)** — cuyo
  [synaWudfBioUsb-sandbox](https://github.com/uunicorn/synaWudfBioUsb-sandbox) y
  [fork de wine](https://github.com/uunicorn/wine) son el armazón para rastrear el
  controlador biométrico Windows de un proveedor bajo Wine, que es cómo se recupera el protocolo de comandos
  de un sensor criptográfico sin una máquina Windows.
- **Marco Trevisan ([3v1n0](https://github.com/3v1n0))**, mantenedor de libfprint —
  quien señaló el camino hacia ese enfoque de rastreo con Wine, y cuyo impulso para mejorar
  la propia comparación de libfprint río arriba enmarca por qué existe la ruta del comparador del proveedor.
- **[championswimmer/libfprint-eh577](https://github.com/championswimmer/libfprint-eh577)**
  — trabajo previo para la familia de sensores EgisTec EH577.

## Otras formas de ejecutar un FT9201 en Linux

No es el único enfoque — las alternativas difieren principalmente en *cómo* reutilizan
el comparador de FocalTech (todas lo hacen; el sensor diminuto descarta la comparación genérica).

- **[Romk-a/ft9201-linux-setup](https://github.com/Romk-a/ft9201-linux-setup)** — una
  guía para Debian/Ubuntu (Astra Linux) que instala el **controlador Linux "TOD" propietario
  precompilado** de FocalTech (de
  [ryenyuku/libfprint-ft9201](https://github.com/ryenyuku/libfprint-ft9201); también han existido
  RPMs para Fedora) y parchea binariamente la tabla de ID USB (`9338` → `93a9`).
  - **Cómo se compara:** esa ruta requiere *menos trabajo* — instalar un `.deb`, parchear dos
    bytes, sin ingeniería inversa. Pero necesita **libfprint con soporte TOD**
    (familia Debian/Ubuntu; **no** en Fedora/Arch estándar), **reemplaza toda su
    `libfprint` del sistema** con una compilación antigua y completamente cerrada, y tiene que
    luchar con el gestor de paquetes para mantenerla fijada. Este proyecto, en cambio, proporciona un
    controlador **abierto**, se instala **de forma paralela** (la libfprint de su distribución
    no se toca), funciona en **libfprint principal sin TOD** y carga solo el *comparador*
    DLL aislado del proveedor — que es lo que toda la ingeniería inversa logró.
  - **Versión corta:** en Debian/Ubuntu, la ruta TOD es el botón fácil; en
    Fedora/Arch, o si lo quiere abierto y no invasivo, use este.
- **Existen controladores de kernel** ([banianitc](https://github.com/banianitc/ft9201-fingerprint-driver)
  — la referencia de protocolo de la que este proyecto hizo ingeniería inversa,
  [bm16ton/ft92010x9338](https://github.com/bm16ton/ft92010x9338)) pero no se integran
  con libfprint/fprintd, por lo que no hay soporte para inicio de sesión/PAM.

El controlador Linux TOD propietario que esos paquetes `.deb`/RPM redistribuyen parece haber
sido un lanzamiento de FocalTech/GPD para la GPD Win 4 que luego fue **retirado de la
distribución oficial** — razón por la cual ahora sobrevive solo como realojamientos de la comunidad.
(Tenga en cuenta también que algunas unidades GPD Win 4 incluyen un sensor completamente diferente, un
Chipsailing CS9711, no esta pieza de FocalTech).

## Proyectos relacionados

- [championswimmer/libfprint-eh577](https://github.com/championswimmer/libfprint-eh577)
  — un esfuerzo de controlador Linux para el **EgisTec EH577** (`1c7a:0577`), otro
  lector de tipo presión "solo Windows Hello" (sensor activo de 52×72). Diferente proveedor
  y protocolo USB, pero la misma forma de *comparación en el host*: su paquete Windows incluye
  una DLL adaptadora del motor del proveedor (`EgisTouchFPEngine0577.dll`, sin enclave VBS), por lo que
  el método en **[PORTING.md](https://github.com/omgrant/ft9201-libfprint/blob/master/PORTING.md)** también se aplica a él.
- **[OMGrant/eh577-libfprint](https://github.com/OMGrant/eh577-libfprint)** — este
  método llevado de principio a fin al **EgisTec EH577** y publicado como un controlador
  funcional. Las técnicas criptográficas de la §3b se validaron contra sus compilaciones SDCP;
  el controlador distribuido apunta a una compilación del Catálogo *anterior a SDCP* (un comparador
  puramente software — véase la nota de la §3b sobre selección de compilación), inscribiendo y verificando
  huellas reales en Linux.

## Licencia

El controlador y el cargador (`src/`, `scripts/`) tienen licencia **LGPL-2.1-o-superior**, coincidiendo
con libfprint. La DLL y el firmware de FocalTech son propiedad de ellos y no se distribuyen
aquí — usted los obtiene por su cuenta. Este proyecto es una herramienta de interoperabilidad
para hardware que usted posee; no incluye ni relicencia ningún código de FocalTech.