|
|
преди 3 седмици | |
|---|---|---|
| driverdlls | преди 1 месец | |
| drivers | преди 1 месец | |
| work | преди 3 седмици | |
| .gitignore | преди 1 месец | |
| README.md | преди 3 седмици |
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.
Known caveat — stale calibration after the sensor loses its record: when the
sensor's calibration/ownership state is reset (unexpected power loss, driver
reset, firmware state change), the template disappears and the saved
CalibrationData.blob no longer matches. Capture then hangs forever at
"about to IOCTL_BIOMETRIC_CAPTURE_DATA" without a SensorStatus, so Settings
enrollment never progresses and the client eventually cancels (leaving no
print at all). Since 2026-10-24 the shim checks the pre-enroll delete.exe
status: a 00 payload means "no record", so it moves CalibrationData.blob /
PairingData.blob aside as .stale-<epoch> before enrolling. enroll.exe
then recalibrates and saves a fresh blob, so recovery is automatic on the
next enrollment attempt (the moved files are kept for diagnosis).
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.