omgrant/ft9201-libfprintDriver libfprint para Linux para o leitor de impressão digital USB Focal-systems FT9201 (2808:93a9) — executa o mecanismo de correspondência Windows da própria FocalTech nativamente no Linux, sem Wine. Inclui um método para portar outros leitores exclusivos do Windows Hello.
# ft9201-libfprint
Suporte a impressão digital no Linux para o leitor USB **Focal-systems FT9201** (`2808:93a9`, vendido como um dongle independente do Windows Hello), como um driver do [libfprint](https://gitlab.freedesktop.org/libfprint/libfprint).
<p align="center">
<img src="https://assets.kitploit.com/production/public/readmes/7029/9a4eac4876063dbf80466bd7c0d975430fb75f3f9655604d2d4aad3725c9e11e.jpg" alt="Leitor de impressão digital USB Focal-systems FT9201" width="360">
</p>
O sensor é um minúsculo leitor óptico de 96×96. O comparador embutido do libfprint não funciona bem em uma imagem tão pequena, então este driver em vez disso reutiliza **o próprio mecanismo de correspondência da FocalTech** — a `ftWbioEngineAdapter.dll` de seu driver Windows assinado — executando-o nativamente no Linux com um pequeno carregador PE em processo. Sem Wine, sem Windows, sem nuvem.
> **Este repositório também é um método reutilizável, não apenas um driver.** A técnica — executar o mecanismo de correspondência Windows de um fornecedor nativamente no Linux, sem Wine — generaliza-se para outros leitores "somente Windows Hello", **incluindo aqueles que possuem um canal seguro SDCP** (os sensores criptográficos das classes Synaptics/Goodix/ELAN/EgisTec), através do módulo opcional [`src/crypto_shims.c`](https://github.com/omgrant/ft9201-libfprint/blob/master/src/crypto_shims.c). O FT9201 é o exemplo prático; o carregador em processo, a ponte WinBio e a camada de bypass criptográfico são transferíveis para o próximo dispositivo. Veja **[PORTING.md](https://github.com/omgrant/ft9201-libfprint/blob/master/PORTING.md)** para o método passo a passo e o que reutilizar como está.
## Status
Funcionando de ponta a ponta em hardware real: inscrição e verificação através do `fprintd` / ferramentas de linha de comando, e no KDE/GNOME após a instalação. Ele corresponde à sua digital usando o algoritmo real do fornecedor.
Desenvolvido e testado contra [este leitor exato](https://www.amazon.com/dp/B0DK7LQZGH) (ASIN `B0DK7LQZGH`) — a variante FT9348W do `2808:93a9`.
Caveats:
- Testado apenas naquela variante FT9348W do dispositivo `2808:93a9`.
- O matcher é um blob proprietário que chamamos; não podemos corrigir bugs dentro dele.
- Apenas x86-64 (a DLL e o carregador são 64 bits).
## Como funciona (versão resumida)
- A sequência de inicialização USB + firmware foi engenharia reversa dos próprios drivers da FocalTech; o firmware do MCU 8051 é carregado, então uma sequência específica de configuração de registradores o inicia.
- Cada captura (96×96) é cortada ao centro para os 64×80 que o mecanismo espera.
- `ft_engine.c` é um carregador de ~450 linhas que mapeia `ftWbioEngineAdapter.dll` na memória, fornece as ~90 funções `kernel32` que ela importa, configura um TEB Windows falso e chama a interface WinBio do mecanismo para inscrição/verificação.
- O carregador mapeia código como leitura-execução e dados como leitura-escrita a partir de um arquivo na memória, então **nenhuma página é jamais gravável *e* executável**. Isso significa que ele é executado sob o endurecimento `MemoryDenyWriteExecute` padrão do `fprintd` — você **não** precisa desabilitar nenhuma configuração de segurança.
Veja [`docs/how-it-works.md`](https://github.com/omgrant/ft9201-libfprint/blob/master/docs/how-it-works.md) para o artigo técnico completo.
## Requisitos
Ferramentas de compilação + dependências de compilação do libfprint. No 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: os equivalentes — `libglib2.0-dev libgusb-dev libnss3-dev libpixman-1-dev libgudev-1.0-dev libsystemd-dev`, mais `cabextract`.)
## Compilar e instalar
```
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
```
Experimente sem instalar nada:
```
FT9201_ENGINE_DLL=$PWD/blobs/ftWbioEngineAdapter.dll \
LD_LIBRARY_PATH=libfprint/build/libfprint \
libfprint/build/examples/enroll
```
Instale-o para KDE/GNOME/login (lado a lado; o libfprint da sua distribuição não é alterado, nenhum endurecimento desabilitado):
```
sudo scripts/install.sh
fprintd-enroll
```
Desfaça tudo: `sudo scripts/install.sh --uninstall`.
## Os blobs proprietários
Este repositório **não** contém binários proprietários. Dois arquivos são da FocalTech e são obtidos de fontes públicas existentes durante a compilação pelo `scripts/fetch-blobs.sh`:
| Arquivo | O que é | De onde vem |
|---------|---------|-------------|
| `ftWbioEngineAdapter.dll` | o mecanismo de correspondência | driver Windows assinado da FocalTech no Catálogo de Atualizações da Microsoft |
| Firmware MCU FT9348W (`src/ft9201_fw.h`) | firmware 8051 que o sensor executa | extraído (símbolo `FOCALFP_9348_FW_APP`) do blob público [`ft9201-static`](https://github.com/mrrbrilliant/ft9201-static) |
### Obtendo os blobs manualmente
Se alguma URL de download tiver mudado, você só precisa desses dois arquivos:
- **`ftWbioEngineAdapter.dll`** — pesquise no Catálogo de Atualizações da Microsoft por *"FocalTech Electronics Biometric"* (driver 1.0.3.58, corresponde ao ID de hardware `USB\VID_2808&PID_93A9`). Baixe o `.cab`, extraia com `cabextract` e coloque `ftWbioEngineAdapter.dll` em `blobs/`.
- **Firmware MCU** — obtenha qualquer cópia do blob libfprint Linux da FocalTech que contenha o símbolo `FOCALFP_9348_FW_APP` (por exemplo, de `ft9201-static`) e execute `python3 scripts/extract-firmware.py <esse-libfprint-2.so> src/ft9201_fw.h`.
Em seguida, execute novamente `scripts/build.sh`.
## Créditos
Protocolo USB originalmente engenheirado reversamente por [banianitc/ft9201-fingerprint-driver](https://github.com/banianitc/ft9201-fingerprint-driver).
Firmware e sequência de inicialização referenciados cruzadamente com o blob Linux da FocalTech via [mrrbrilliant/ft9201-static](https://github.com/mrrbrilliant/ft9201-static).
Construído sobre [libfprint](https://gitlab.freedesktop.org/libfprint/libfprint).
O método reutilizável e o caminho do sensor criptográfico também se baseiam no trabalho de:
- **[uunicorn](https://github.com/uunicorn)** — cujo [synaWudfBioUsb-sandbox](https://github.com/uunicorn/synaWudfBioUsb-sandbox) e [fork do wine](https://github.com/uunicorn/wine) são a estrutura para rastrear um driver biométrico Windows de um fornecedor sob Wine, que é como o protocolo de comando de um sensor criptográfico é recuperado sem uma máquina Windows.
- **Marco Trevisan ([3v1n0](https://github.com/3v1n0))**, um mantenedor do libfprint — que apontou o caminho para essa abordagem de rastreamento com Wine, e cujo impulso para melhorar a correspondência upstream do próprio libfprint enquadra por que a rota do matcher do fornecedor existe.
- **[championswimmer/libfprint-eh577](https://github.com/championswimmer/libfprint-eh577)** — trabalho anterior para a família de sensores EgisTec EH577.
## Outras formas de executar um FT9201 no Linux
Esta não é a única abordagem — as alternativas diferem principalmente em *como* reutilizam o matcher da FocalTech (todas o fazem; o sensor minúsculo descarta a correspondência genérica).
- **[Romk-a/ft9201-linux-setup](https://github.com/Romk-a/ft9201-linux-setup)** — um guia para Debian/Ubuntu (Astra Linux) que instala o **driver Linux "TOD" proprietário pré-compilado da FocalTech** (de [ryenyuku/libfprint-ft9201](https://github.com/ryenyuku/libfprint-ft9201); RPMs do Fedora também existiram) e faz patch binário em sua tabela de IDs USB (`9338` → `93a9`).
- **Como se compara:** essa rota é *menos trabalho* — instalar um `.deb`, corrigir dois bytes, sem engenharia reversa. Mas precisa de **libfprint habilitado para TOD** (família Debian/Ubuntu; **não** no Fedora/Arch padrão), **substitui todo o `libfprint` do sistema** por uma compilação antiga e totalmente fechada, e você tem que lutar com o gerenciador de pacotes para mantê-lo fixado. Este projeto, em vez disso, inclui um driver **aberto**, instala **lado a lado** (o libfprint da sua distribuição não é tocado), funciona no **libfprint principal sem TOD** e carrega apenas a DLL *matcher* isolada do fornecedor — que é o que toda a engenharia reversa conquistou.
- **Versão resumida:** no Debian/Ubuntu, a rota TOD é o botão fácil; no Fedora/Arch, ou se você quiser algo aberto e não invasivo, use este.
- **Drivers de kernel** existem ([banianitc](https://github.com/banianitc/ft9201-fingerprint-driver) — a referência de protocolo da qual este projeto fez engenharia reversa, [bm16ton/ft92010x9338](https://github.com/bm16ton/ft92010x9338)) mas eles não se integram com libfprint/fprintd, então não há suporte a login/PAM.
O driver Linux TOD proprietário que esses pacotes `.deb`/RPM redistribuem parece ter sido um lançamento da FocalTech/GPD para o GPD Win 4 que posteriormente foi **retirado da distribuição oficial** — razão pela qual agora sobrevive apenas como re-hospedagens da comunidade. (Observe também que algumas unidades do GPD Win 4 possuem um sensor completamente diferente, um Chipsailing CS9711, não esta peça da FocalTech.)
## Projetos relacionados
- [championswimmer/libfprint-eh577](https://github.com/championswimmer/libfprint-eh577) — um esforço de driver Linux para o **EgisTec EH577** (`1c7a:0577`), outro leitor do tipo pressão "somente Windows Hello" (sensor ativo de 52×72). Fornecedor e protocolo USB diferentes, mas o mesmo formato *match-on-host*: seu pacote Windows inclui uma DLL adaptadora de mecanismo do fornecedor (`EgisTouchFPEngine0577.dll`, sem enclave VBS), então o método em **[PORTING.md](https://github.com/omgrant/ft9201-libfprint/blob/master/PORTING.md)** também se aplica a ele.
- **[OMGrant/eh577-libfprint](https://github.com/OMGrant/eh577-libfprint)** — este método levado de ponta a ponta para o **EgisTec EH577** e publicado como um driver funcional. As técnicas criptográficas §3b foram validadas contra suas compilações SDCP; o driver distribuído tem como alvo uma compilação do Catálogo *pré-SDCP* (um matcher puramente de software — veja a nota §3b sobre seleção de compilação), inscrevendo e verificando digitais reais no Linux.
## Licença
O driver e o carregador (`src/`, `scripts/`) são **LGPL-2.1-or-later**, em conformidade com o libfprint. A DLL e o firmware da FocalTech são de sua própria propriedade e não são distribuídos aqui — você os obtém por conta própria. Este projeto é uma ferramenta de interoperabilidade para hardware que você possui; ele não inclui nem relicencia nenhum código da FocalTech.