|
|
1 month ago | |
|---|---|---|
| driverdlls | 1 month ago | |
| drivers | 1 month ago | |
| work | 1 month ago | |
| .gitignore | 1 month ago | |
| README.md | 1 month ago |
Enrollment and verification both work end-to-end on Linux using rstar000's Wine-sandbox approach (vendor driver + hacked Wine 4.8 winusb → live libusb → sensor). See "Wine sandbox route" section at the bottom.
Quick usage:
work/debug/run_aexe.sh enroll a.exework/fp-verify.sh → exit 0 = MATCH, 1 = no match, 2 = timeout/errorpam_fp.so — fingerprint OR password,
whichever comes first (no timeout wait); polkit is finger-first with a
password fallback. Installer: sudo work/pam/install.sh.work/fprintd-shim/ (see the
"GNOME lock-screen fingerprint" section).
Evidence: work/debug/fprintd_shim_lock_screen_SUCCESS.txt.The native synaTudor route below remains blocked (driver-internal NULL in the capture ioctl path); the Wine route is the pragmatic working solution.
Relink the vendor Windows driver in userspace (rstar000's synaTudor fork):
work/synaTudor/ - patched fork (builds at work/synaTudor/build)driverdlls/ - Synaptics WBDI driver DLLs 5.5.2731.1050 (non-SGX), extracted from
the Microsoft Update Catalog CABs in drivers/work/debug/ - run logs, core analyses, enrollment driverAttach -> Reset -> QueryStatus (returns real device status;
0x5 = NOT_CALIBRATED until calibration runs)build/cli/tudor_cli) reaches its interactive command loop and can
save/load its datastorewinbio.h: WINBIO_SENSOR_INTERFACE_V1 - accurate pre-Win10 table layout.
The real table (verified from the adapter's own debug strings) is:
Attach, Detach, ClearContext, QueryStatus, Reset, SetMode, SetIndicatorStatus,
GetIndicatorStatus, StartCapture, FinishCapture, ExportSensorData, Cancel,
PushDataToEngine, ControlUnit, ResetOwnership (Synaptics extension).
There is no PipelineInit/Activate in this driver generation.driver_wudf1.cpp:
GetNamedValue("CalibrationData") must return a well-formed empty
PROPVARIANT; the original left vt uninitialized.tudor_devctrl_wudf1 must wait for the driver's completion and return its
real status, and signal the caller's OVERLAPPED (winio_complete_overlapped).DeviceIoControl returns TRUE when the overlapped completed synchronously
and only signals ERROR_IO_PENDING when genuinely pending.winusb.c: re-acquire the device across re-enumeration cycles instead of
exiting; graceful failure on lost devices./home/rstar000/...), GCC15 build fixes.The fork contains TWO WUDF hosts:
driver_wudf1.cpp (homemade, active) — implements the UMDF v2 COM entry
(DllGetClassObject + IClassFactory + IDriverEntry), which is what this
driver uses.device.c/driver.c + wdf/*.c (native framework, disabled) — implements
UMDF v1 (FxDriverEntryUm), used by the older synaFpAdapter104 driver
generation.The 06cb:0081 driver DLL exports only DllGetClassObject and
Microsoft_WDF_UMDF_Version - it is a v2 driver. The native framework cannot
load it at all ("Couldn't find DLL export 'FxDriverEntryUm'"). Porting to the
native framework is therefore a dead end; the homemade v2 host is the correct
architecture, and the remaining work is completing its v2 object graph.
Capture ioctl 0x44202c crashes at driver offset 0x34314 dereferencing
[ctx+0x1c0] == NULL. Verified against the official UMDF 1.x COM interfaces
(Microsoft wudfddi.h; the driver uses the UMDF-1 COM entry via
DllGetClassObject):
GetDeviceIoControlParameters ->
GetInput/OutputMemory -> GetDataBuffer -> SetInformation -> Complete) runs
correctly and completes for every ioctl except the capture one, which dies
after GetDataBuffer of the output memory - i.e. inside the driver's own
capture handler, not in our stubs.ctx is a driver-built C++ object (12+ driver-function vtable slots at
driver rvas 0x190c0..0x1ce70). Its +0x1c0 slot holds a driver-internal
child object created by factory 0x163f0, stored at 0x6ea49 (capture path) or
at 0x1cc61 (init path gated on [obj+0x238]==2). None of those writers run
before the crash.[obj+0x238] (0=idle,1,2=active) is never
advanced to 2 in our host; the state writers (0x1cd95, 0x1d8e9, 0x249f0) are
never reached.Conclusion: the remaining gap is a WUDF v2 object-lifecycle linkage (device object internal state + child object creation) that the homemade host does not reproduce. Everything host-side that is verifiable against the public UMDF/WUDF documentation is already correct.
The driver's device-setup sequence in our host (captured at the host API boundary):
MyDevice::CreateIoQueue(...) — secondary queue (DispatchType=Parallel), thenMyDevice::ConfigureRequestDispatching(queue, WdfRequestTypeQueryInformation, Forward=1), thenMyDevice::CreateDeviceInterface(GUID {e2b5183a-99ea-4cc3-ad6b-80ca8d715b80}, NULL)
— the biometric device interface. The driver passes its device context
(0x5555555b2a20, our crash object) as an argument here.AssignDeviceInterfaceState is called once (by the driver), with Enable=?
The host implements it as a logging no-op.Crash object analysis: [ctx+0x1a0..0x1e8] reveals an MSVC container layout
({data-ptr, ..., count=2, 0x30}), and [ctx+0x1c0] (container index 4 /
notional element) is NULL. The driver indexes into this container during its
capture ioctl dispatch and dereferences the element's vtable (+0x38).
Interpretation: this is the driver's "IOCTL handler table" / dispatch map, built during device-interface setup. In a real UMDF host, the framework's device-interface activation (AssignDeviceInterfaceState) or the io-queue creation callbacks populate this map; our host's no-op implementations leave the map's capture entry NULL.
Implement CreateDeviceInterface/AssignDeviceInterfaceState and
CreateIoQueue semantics faithfully (reserve/register the interface state and
queue entries the driver indexes), or find which single driver callback fills
the dispatch map. This is now scoped to the device-interface/queue setup path,
not general WUDF emulation.
work/debug/enroll.shwork/synaTudor/build), 12 files modifiedIWDFIoRequest method with args+results (Send,
ForwardToIoQueue, GetFileObject, MarkCancelable, UnmarkCancelable,
GetCompletionParams, SetCompletionCallback) - the capture path likely
enters one of these on objects we hand it.base+0x3414c and dumping the caller frames' arguments
(the wrapper is passed in as an argument, not returned).CreateWdfObject/
CreateWdfFile return: the missing +0x1c0 linkage is likely the
parent-object slot WDF fills at object creation.printf 'e\n1\n1\n' | TUDOR_PROBE=0 timeout 300
./cli/tudor_cli <datastore> and check for a new crash offset - each fix
moves the failure later (proven pattern this session).WUDF host (driver_wudf1.cpp):
winusb.c)tudor_devctrl_wudf1: wait for driver completion, propagate real status,
signal caller's OVERLAPPEDDeviceIoControl: correct sync-complete vs ERROR_IO_PENDING semanticsAssignContext/RetrieveContext now store/return context (6 classes)CreateWdfMemory/CreatePreallocatedWdfMemory/CreateWdfObject/
CreateWdfFile/CreateRequest return live objectswork/debug/enroll.sh - runs the interactive enroll over a pty
(init ~3-4 min, then touch the sensor when asked)Approach: rstar000's synaWudfBioUsb-sandbox (emulates the Windows Biometric
service side) + synaWudfBioUsb.dll (vendor driver, UMDF2-style WBDI) run under
a locally built uunicorn/rstar000 Wine 4.8 fork (hacking/validiy-sensor)
whose winusb.dll talks to the real sensor through libusb (live USB, not
replay).
work/synaWudfBioUsb-sandbox/
a.exe — sandbox harness (hardcoded flow: init → enroll() → identify())verify.exe — patched copy: verify-only (no re-enroll)synaWudfBioUsb.dll, MinGW runtime DLLs, usb.txt (06cb:0081)CalibrationData.blob, PairingData.blob — trust/calibration state
(persisted by the driver agent in its cwd)/tmp/opencode/wine-validity/ → installed at work/wine-build/install/
work/wine-build/install/bin/wine64work/wineprefix-48/ — dedicated Wine prefix; drive_c/usb.txt = 06cb:0081
(device path the driver opens; fake winusb maps it to VID:PID via libusb)work/fp-verify.sh — verify wrapper (sets WINEPREFIX, USB_SCRIPT, timeout)work/debug/run_aexe.sh enroll a.exe
c5698517-bcff-12e7-2496-b763ed040000,
subfactor 0xF6, payload "Unicorn" (asserted in the commit ioctl 0x442018).work/fp-verify.sh
0x4048b8 call enroll → NOP×5 (offset 0x3eae in file; signature
b9 02 00 00 00 e8 1f e4 ff ff e8 02 d8 ff ff)0x4048e1 mov $0x2710,%ecx (Sleep 10000) → mov $0,%ecx
(offset 0x3ee1; signature b9 10 27 00 00 48 8b 05 4b 9c 01 00 ff d0 e8 16 ce ff ff)aexe_enroll_VERIFY_SUCCESS.log — full enroll (10 captures, commit) +
identify match in one sessionaexe_verify2_FRESH_SESSION_SUCCESS.log — fresh session, identify returns
the enrolled "Unicorn" record (persistent enrollment)fp-verify_MATCH_SUCCESS.log — fp-verify.sh MATCH (exit 0)verify_result_SUCCESS.txt — extracted decrypt/identify evidence0x442004 returns a zeroed record with WinBio error
dword 0x8009801F (verified with a different finger; script exits 1)dlls/bcrypt/gnutls.c: pass curve not &curve to
gnutls_privkey_export_ecc_raw (API drift)dlls/bcrypt/secrets.c: const BIGNUM * for ECDSA_SIG_get0; add
declaration of get_gnutls_ecc_key_params (from gnutls.c)dlls/crypt32/crypt32_private.h: extern HINSTANCE hInstance--enable-win64 --with-gnutls --without-x --disable-tests +
disable unneeded modules; CFLAGS -fcommon -std=gnu89 -Dbool=winbool_fieldmake -j$(nproc), install to work/wine-build/installpam_exec.so seteuid work/fp-verify.sh on sudo / polkit-1
(fingerprint first, password fallback), and lock screen where applicable.(sudo uses the custom pam_fp.so module documented below instead of this.)
Files:
work/fp-pam.sh — pam_exec entry point (sets 25s touch window, fixed PATH/HOME)work/fp-verify.sh — the actual verify runRollback is instant: restore the .bak-fp files / remove the polkit override.
# 0) Safety: keep a root shell open in another terminal (sudo -s) while testing!
# 1) sudo: fingerprint first, then system-auth (password fallback)
sudo cp /etc/pam.d/sudo /etc/pam.d/sudo.bak-fp
sudo sed -i '1i auth sufficient pam_exec.so stdout quiet /home/nebulon/projects/fingerprint/work/fp-pam.sh' /etc/pam.d/sudo
# 2) polkit: create a local override of the vendor default (new file -> rollback = rm)
sudo cp /usr/lib/pam.d/polkit-1 /etc/pam.d/polkit-1
sudo sed -i '1i auth sufficient pam_exec.so stdout quiet /home/nebulon/projects/fingerprint/work/fp-pam.sh' /etc/pam.d/polkit-1
# 3) Test sudo (don't type the password; touch the sensor)
sudo -k -v
# 4) Test polkit (GUI session): pkexec true -> GNOME auth dialog -> touch sensor
# Rollback
sudo cp /etc/pam.d/sudo.bak-fp /etc/pam.d/sudo
sudo rm /etc/pam.d/polkit-1
Notes:
stdout makes the "touch the reader" hint visible; quiet suppresses the
"failed: exit code N" notice when falling back.sufficient = fingerprint match completes auth; failure/timeout (15s) falls
back to the next auth module (password). Password is always available — just
wait out the finger window or don't touch.FP_VERIFY_TIMEOUT in work/fp-pam.sh (default 15s).seteuid); fp-pam.sh then drops fully to
nebulon with setpriv --reuid/--regid/--init-groups before launching Wine.
(seteuid alone is not enough: Wine checks the real uid against the
prefix owner and refuses otherwise.) No root-owned Wine state is created.Installed state: /etc/pam.d/sudo line 1 = auth sufficient
/home/nebulon/projects/fingerprint/work/pam/pam_fp.so. Re-apply/restore with
sudo work/pam/install.sh (also writes the polkit line + the fptest service).
PAM can't race two auth methods natively, so work/pam/pam_fp.c implements it:
Fingerprint: touch the sensor or type your password:system-auth stack (pam_unix + faillock, so lockout accounting is correct);
just pressing Enter (or the finger check failing) falls back to the normal
password prompt. Echo is disabled while waiting and always restored.Build: cd work/pam && gcc -shared -fPIC -O2 -Wall -o pam_fp.so pam_fp.c -lpam
Test service (sudo):
sudo tee /etc/pam.d/fptest >/dev/null <<'PAMEOF'
#%PAM-1.0
auth sufficient /home/nebulon/projects/fingerprint/work/pam/pam_fp.so debug
auth required pam_unix.so
PAMEOF
cd work/pam && ./pamtest nebulon # touch sensor / type password / press Enter
Enable for sudo (replaces the pam_exec line):
sudo sed -i '1s|.*|auth sufficient /home/nebulon/projects/fingerprint/work/pam/pam_fp.so|' /etc/pam.d/sudo
Rollback: sudo cp /etc/pam.d/sudo.bak-fp /etc/pam.d/sudo
GNOME 51 dropped fingerprint login at the GDM login screen (re-authentication
only, see GDM 51 NEWS) and its lock-screen fingerprint support needs
fprintd, which has no 06cb:0081 support. work/fprintd-shim/ implements
the fprintd D-Bus API (net.reactivated.Fprint Manager + Device) on top of
work/fp-verify.sh, so GNOME Shell, pam_fprintd and the fprintd CLI
tools see this sensor:
fprintd-shim.py — the service (Python 3 + PyGObject; verification runs
as nebulon via setpriv, same environment as the pam_exec path)fprintd.service — installed as /etc/systemd/system/fprintd.service
(shadows the packaged unit; D-Bus activation, no boot enable)install.sh / uninstall.sh — (un)install, rollback is instantselftest.py — pam_fprintd-like smoke test (system bus or --session)apitest.py — API-semantics regression test (session bus, no touch needed)Lock-screen behaviour: touch the sensor to unlock; typing the password
stays available in parallel. A no-touch attempt ends after the pam_fprintd
timeout (30 s); failed touches are retried up to 3 times. Sudo/polkit keep
using pam_fp.so — untouched. work/fp-verify.sh now takes an flock so
concurrent verifications (sudo + lock screen) serialize on the sensor.
Tested end-to-end 2026-10-15 (session 3, Wayland): lock screen unlocked by
fingerprint in ~5 s (work/debug/fprintd_shim_lock_screen_SUCCESS.txt).
Note: several failed sudo fingerprint attempts trip pam_faillock and block
the gdm-fingerprint PAM stack; reset with
sudo faillock --user nebulon --reset.
# install / rollback (root)
sudo work/fprintd-shim/install.sh
sudo work/fprintd-shim/uninstall.sh
# smoke tests (user)
fprintd-list "$USER"
fprintd-verify -f any "$USER" # touch the sensor
python3 work/fprintd-shim/selftest.py
work/pam/pamtest3 -d work/pam/confdir -s fprintd-test "$USER" # touch
dbus-run-session -- bash -c ' # full API test, no root
python3 work/fprintd-shim/fprintd-shim.py --session &
sleep 1; python3 work/fprintd-shim/apitest.py; kill %1'
Phase 2 (mostly done): enrollment and deletion work through GNOME Settings
and the fprintd CLI. EnrollStart drives enroll.exe (fresh commits work;
see the commit caveat below) and DeleteEnrolled* runs delete.exe — a real
sensor-side delete (ioctl 0x442034). Reported fingerprints live in
/var/lib/fprintd-shim/state.json (today the sensor holds a single record —
see the multi-finger plan below; deleting the last reported finger deletes
the device record, deleting one of several only updates the reported list).
Known caveat — re-enrolling an existing record: the commit phase there
makes the device re-enumerate mid-write; the hacked winusb stub cannot
detect reconnects and exits with LIBUSB_ERROR_NO_DEVICE (visible in
/tmp/opencode/harness-*.log), which used to leave a record that matched
nothing. The shim therefore deletes any existing record first (the delete
ioctl does not reset the device) so every enrollment is a fresh write,
which has been reliable.
Today the sensor holds exactly one record because the sandbox harness
hardcodes it (hello.cc commitEnrollment() / deleteRecord():
identity GUID c5698517-… subfactor 0xF6 payload "Unicorn"; the
firmware/driver key records by identity+subfactor, i.e. one slot per
finger). Not a hardware limit — Windows enrolls each finger under its own
subfactor. Steps:
work/artifacts/make-enroll-delete.sh: locate the subfactor bytes by
signature (the 4 bytes f6 00 00 00 right after the 16-byte identity
GUID; assert uniqueness) and emit per-finger variants, e.g.
enroll-<subfactor>.exe / delete-<subfactor>.exe; or have the shim
patch a copy on the fly (1 MiB, deterministic) instead of committing 10
binaries. Keep the "Unicorn" payload for all of them.fprintd-shim.py): map finger_name -> subfactor (e.g.
left-thumb=0xF0 … right-little-finger=0xF9); run the per-finger
binary; DeleteEnrolledFinger(f) deletes only f's record,
DeleteEnrolledFingers2 loops over the enrolled set; keep the
"pre-delete the target slot" habit so each write stays a fresh commit.
Note: adding a second finger writes a different (empty) slot, so it
should behave like a fresh commit — the re-enumerate failure only hit
replacing an existing record."Unicorn" payload, so
fp-verify.sh's check keeps working ("any finger" semantics, like
fprintd). Optional refinement: parse the returned subfactor to support
VerifyStart(<specific finger>).Tracked here: scripts, patches, docs, small runtime artifacts (trust blobs,
verify.exe, MinGW runtime DLLs). Excluded (rebuildable): Wine build tree, Wine
prefixes, upstream clones, big logs — see .gitignore.
Restore after a wipe:
git clone <this repo> ~/projects/fingerprint && cd ~/projects/fingerprintwork/wine-build.sh
(prereqs: base-devel, mingw-w64-gcc, gnutls, libusb)git clone https://github.com/uunicorn/synaWudfBioUsb-sandbox work/synaWudfBioUsb-sandbox
then work/artifacts/sync-to-sandbox.sh (driver DLL, trust blobs,
verify.exe, usb.txt, MinGW DLLs)WINEPREFIX=$PWD/work/wineprefix-48 work/wine-build/install/bin/wine64 wineboot -usudo cp work/system/70-fingerprint-06cb-0081.rules /etc/udev/rules.d/ && sudo udevadm control --reloadmake -C work/pam && sudo work/pam/install.shsudo work/fprintd-shim/install.shwork/fp-verify.sh (touch the sensor) → Fingerprint matched.work/patches/uunicorn-wine-modern-toolchain.patch — build fixes for the
hacked Wine fork on a modern toolchain (gnutls 3.8 API, OpenSSL 3 const-ness,
GCC -fno-common); full configure/Cflags recipe in work/wine-build.sh.work/patches/uunicorn-sandbox-argv-dispatch.patch — enables the
<nop|identify|enroll> argv dispatch the sandbox README documents (it was
#if 0'd in the source) and adds a match exit status so verify-only runs
need no binary patching. Not compile-tested locally (needs WDK headers) —
review before opening a PR.work/patches/synaTudor-work.patch — the 12-file delta of the (blocked)
native synaTudor route; may be of interest to that project.Prepared PR branches + git bundles (wine, sandbox): see
work/contrib/README.md.
Legal note: drivers/ and driverdlls/ contain Synaptics vendor binaries
from the Microsoft Update Catalog. Check redistribution terms before making
this repository public; drop them with git rm -r --cached drivers driverdlls.