microarray.c — libfprint driver for MicroarrayTechnology MAFP (3274:8012)

Status: WORKING ✓

Enrollment and verify confirmed working on real hardware (2026-05-26).

Hardware

TNP Nano USB Fingerprint Reader (Amazon US)
TNP Nano USB Fingerprint Reader (Amazon UK)

Protocol fully reverse-engineered from MicroarrayFingerprintDevice.dll v9.47.11.214 using Ghidra 12.0.4 headless analysis. See Reverse Engineering for how to reproduce.

What Works

• Enrollment: 6-stage press/lift cycle, stores template to device flash
• Verify: correct finger matches, wrong finger rejects
• Finger-present detection via GET_IMAGE polling (CMD 0x01)
• Press/lift detection between captures via waiting_for_lift flag
• Per-enrollment handshake (CMD 0x23) to reset device session state
• Device flash clear (CMD 0x0D) at enrollment start to free FID slots
• FID bitmap parsing (CMD 0x1F) to find first free slot
• Template storage (CMD 0x06) and retrieval for verify (CMD 0x66)

Known Limitations / TODOs

1. CMD 0x0D (Empty) clears ALL templates at the start of each enrollment. This is necessary because failed enrollments leave stale templates in device flash. The proper fix is to track which FID slot we're writing to and only clear that slot, or to not clear at all if the device has free slots.

2. Interrupt endpoint (EP 0x82) not used. Currently polling CMD 0x01 for finger detection. The interrupt endpoint would be more efficient and allow proper finger-on/off events without extra USB traffic.

3. "Hold to complete" quirk: if the user holds their finger without lifting between captures, the waiting_for_lift flag will wait for a lift before accepting the next sample. This works correctly in practice.

4. Handshake response is accepted if header bytes EF 01 are present. The Windows driver validates 35 bytes via FUN_180006fc0 which was not fully decompiled.

5. Identify (1:N search) not implemented. CMD 0x66 may support searching all slots with FID=0xFFFF (unconfirmed).

Key Protocol Discoveries (from debugging)

• The Windows driver calls mfm_handshake (CMD 0x23) at the start of every enrollment, not just at device open. Without this, failed enrollments leave the device in a broken session state.
• The device supports exactly 30 FID slots (0–29). StoreChar returns 0x18 if the slot is out of range.
• CMD 0x0D (Empty) returns success and clears all 30 slots.
• The required number of GenChar samples for RegModel is DAT_180032020 / 3clamped to [3, 6]. For this device the value is 6.
• Extra GET_IMAGE calls between GenChars corrupt the device's char buffer state. The waiting_for_lift approach must minimize GET_IMAGE polling between captures.

Instructions

1. Plug in device & update your machine

sudo apt update

2. Install all required tools/libraries

sudo apt install -y git build-essential meson ninja-build \
  pkg-config libglib2.0-dev libgusb-dev libgudev-1.0-dev \
  libpixman-1-dev libnss3-dev libssl-dev libcairo2-dev \
  libgirepository1.0-dev gtk-doc-tools \
  fprintd libpam-fprintd

3. Clone the official libfprint source code to ~/libfprint directory

rm -rf ~/libfprint
git clone https://gitlab.freedesktop.org/libfprint/libfprint.git ~/libfprint

4. Manually create the microarray directory

cd ~/libfprint
mkdir -p libfprint/drivers/microarray
meson setup build

5. Copy this repo

rm -rf ~/libfprint-microarray/
git clone https://github.com/jadegamesuk/libfprint-microarray.git ~/libfprint-microarray

6. Make changes to ~/libfprint

# copy fixed meson.build file over to other library
cp ~/libfprint-microarray/meson.build ~/libfprint/libfprint/meson.build
cp ~/libfprint-microarray/src/microarray.c ~/libfprint/libfprint/drivers/microarray/microarray.c

cd ~/libfprint/build
meson configure -Ddrivers=all
ninja
sudo cp libfprint/libfprint-2.so.2.0.0 /usr/lib/x86_64-linux-gnu/libfprint-2.so.2
sudo cp libfprint/libfprint-2.so.2.0.0 /usr/lib/libfprint-2.so.2
sudo ldconfig
sudo udevadm control --reload-rules && sudo udevadm trigger
#sudo systemctl enable --now fprintd

Testing

# Restart daemon
sudo systemctl stop fprintd
sudo G_MESSAGES_DEBUG=all /usr/libexec/fprintd -t 2>&1

Open a new Terminal Window for the following

# Enroll right index finger (6 press/lift cycles)
fprintd-enroll -f right-index-finger

# Verify
fprintd-verify -f right-index-finger

# Options for [finger]:
left-thumb
left-index-finger
left-middle-finger
left-ring-finger
left-little-finger
right-thumb
right-index-finger
right-middle-finger
right-ring-finger
right-little-finger

If there is a future update of libfprint, re-running Step (6) above should make everything work again.

License

MIT

Legal

This driver was created by reverse engineering the proprietary Windows driver (MicroarrayFingerprintDevice.dll) for the sole purpose of hardware interoperability on Linux. No proprietary code is included — the driver is an independent implementation of the USB protocol.

Reverse engineering for interoperability is protected under:

• US: DMCA §1201(f) — software interoperability exemption
• EU: Software Directive Article 6 — decompilation for interoperability

See Reverse Engineering for full details on the analysis methodology.

Protocol Reference

See Protocol Documentation for full protocol details.