100 lines
3.4 KiB
Markdown
100 lines
3.4 KiB
Markdown
# Goodix GXFP5130 userspace prototype
|
|
|
|
Experimental Linux userspace prototype for the Goodix GXFP5130 fingerprint
|
|
sensor transported through the `/dev/gxfp` EC mailbox ABI.
|
|
|
|
The low-level initialization, TLS session, finger detection and image capture
|
|
paths work on the tested hardware. The project is **not yet fully integrated
|
|
into libfprint**, and enrollment/verification is not production-ready.
|
|
|
|
The implementation has been tested on one GXFP5130 device with chip ID
|
|
`0x2504` and the ChicagoHU profile.
|
|
|
|
## Hardware-validated functionality
|
|
|
|
- mailbox record I/O through `/dev/gxfp`
|
|
- Goodix request and response framing
|
|
- chip-ID and 64-byte OTP reads
|
|
- OTP CRC validation and DAC calibration extraction
|
|
- OTP-derived 224-byte ChicagoHU configuration generation
|
|
- TLS 1.2 PSK session establishment with the sensor MCU
|
|
- finger-down and finger-up detection
|
|
- repeated image capture in one TLS session
|
|
- 7680-byte packed 12-bit image decoding into 5120 samples
|
|
- CRC-32/MPEG-2 image validation
|
|
- 64x80 12-bit image output and deterministic 8-bit conversion
|
|
- timeout, cancellation and session recovery regression paths
|
|
|
|
An experimental libfprint image-device skeleton is included under
|
|
`libfprint-driver/`. It can capture images through libfprint, but the final
|
|
enroll/verify pipeline and matching policy remain work in progress.
|
|
|
|
## Requirements
|
|
|
|
- Linux with the Goodix EC mailbox transport and `/dev/gxfp`
|
|
- a C11 compiler and GNU Make
|
|
- pkg-config
|
|
- mbedTLS development libraries
|
|
|
|
The corresponding kernel transport patch is archived at:
|
|
|
|
<https://lore.kernel.org/platform-driver-x86/20260803074454.49474-1-ertugtopcu0@gmail.com/>
|
|
|
|
## Build and test
|
|
|
|
```sh
|
|
make
|
|
sudo ./sensor-probe /dev/gxfp 10
|
|
```
|
|
|
|
Enable protocol/TLS debug output only when needed:
|
|
|
|
```sh
|
|
sudo env GXFP_DEBUG=1 ./sensor-probe /dev/gxfp 1
|
|
```
|
|
|
|
Run cancellation, timeout-recovery and normal-cycle regression tests:
|
|
|
|
```sh
|
|
sudo ./session-regression /dev/gxfp
|
|
```
|
|
|
|
## Layout
|
|
|
|
```text
|
|
include/gxfp/ protocol and session headers
|
|
src/ transport, configuration, TLS, capture and session code
|
|
examples/ hardware probes and session regression program
|
|
tools/ offline capture-analysis utilities
|
|
libfprint-driver/ experimental, incomplete libfprint integration
|
|
docs/ verified protocol documentation
|
|
```
|
|
|
|
See [docs/protocol.md](docs/protocol.md) for the protocol and capture format.
|
|
|
|
## Security and compatibility
|
|
|
|
The TLS material in `src/tls.c` was recovered for interoperability with the
|
|
tested hardware and forms part of this experimental protocol implementation.
|
|
It is not a user password or repository credential. Do not assume that the
|
|
protocol, configuration, TLS material or image geometry applies to another
|
|
Goodix model.
|
|
|
|
The prototype exposes raw biometric images. Captures, PGM files and enrollment
|
|
templates are ignored by Git and should not be shared without the subject's
|
|
consent.
|
|
|
|
## Reverse-engineering notes
|
|
|
|
Protocol and configuration behavior was reconstructed primarily from the
|
|
Windows implementation and verified against live hardware traces. Existing
|
|
community GXFP5130 experiments were used for comparison. The
|
|
`capture-to-pgm` utility is an offline diagnostic tool and is not used by the
|
|
capture/session implementation.
|
|
|
|
## License
|
|
|
|
The userspace library, examples and tools are GPL-2.0-only. The experimental
|
|
libfprint integration file carries an LGPL-2.1-or-later SPDX identifier. Full
|
|
license texts are available under `LICENSES/`.
|