# Fingerprint reader bring-up: 06cb:0081 on Lenovo YOGA 720-13IKB ## STATUS (2026-10-13): WORKING via the Wine sandbox route ✅ 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: - Enroll (touch sensor ~10 times): `work/debug/run_aexe.sh enroll a.exe` - Verify: `work/fp-verify.sh` → exit 0 = MATCH, 1 = no match, 2 = timeout/error - Template is stored in the sensor's flash → survives reboots/sessions. - PAM (active): sudo uses custom `pam_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`. The native synaTudor route below remains blocked (driver-internal NULL in the capture ioctl path); the Wine route is the pragmatic working solution. ## Device - USB ID: **06cb:0081** Synaptics (Validity family, "Prometheus"-era) - No kernel driver; libfprint ships no support for this ID (supported list starts at 06cb:00bd) - Endpoints: bulk 64B in/out (0x01/0x81/0x82), interrupt in (0x83/0x84) ## Approach used 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 driver ## What works - Driver init: `Attach` -> `Reset` -> `QueryStatus` (returns real device status; `0x5` = NOT_CALIBRATED until calibration runs) - CLI (`build/cli/tudor_cli`) reaches its interactive command loop and can save/load its datastore - USB protocol, TLS handshake, firmware handshake all function ## Fixes applied to the fork (all in work/synaTudor) 1. `winbio.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. 2. `driver_wudf1.cpp`: - Restore the whole 15-slot sensor table from the pristine file RVAs (runtime state clobbered slots in .data). - `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. 3. `winusb.c`: re-acquire the device across re-enumeration cycles instead of exiting; graceful failure on lost devices. 4. Remove author-hardcoded paths (`/home/rstar000/...`), GCC15 build fixes. ## UMDF generation: why the homemade host is the only correct one 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. ## Current blocker (final state after WUDF interface audit) 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): - Our emulated interface vtables match the official method counts/orders (MyDevInit=IWDFDeviceInitialize 8 methods, MyDriver=IWDFDriver 6, MyRequest=IWDFIoRequest 22, MyMem=IWDFMemory 5) - no vtable-order bug. - The driver's own ioctl sequence (`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. - The driver's device state field `[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. ## Final findings (host-API trace) The driver's device-setup sequence in our host (captured at the host API boundary): - `MyDevice::CreateIoQueue(...)` — secondary queue (DispatchType=Parallel), then - `MyDevice::ConfigureRequestDispatching(queue, WdfRequestTypeQueryInformation, Forward=1)`, then - `MyDevice::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. ### Remaining work 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. ## Working state - Init + command loop + datastore round-trip: WORKING (init now ~20-30s) - Enrollment harness ready: `work/debug/enroll.sh` - All patches build clean (`work/synaTudor/build`), 12 files modified ## Continuation checklist (next session) 1. Instrument every `IWDFIoRequest` method with args+results (Send, ForwardToIoQueue, GetFileObject, MarkCancelable, UnmarkCancelable, GetCompletionParams, SetCompletionCallback) - the capture path likely enters one of these on objects we hand it. 2. The crash object is the driver's host-wrapper; find which host call creates it by breaking at `base+0x3414c` and dumping the caller frames' arguments (the wrapper is passed in as an argument, not returned). 3. Compare the wrapper's expected layout against what our `CreateWdfObject`/ `CreateWdfFile` return: the missing `+0x1c0` linkage is likely the parent-object slot WDF fills at object creation. 4. After each fix: `printf 'e\n1\n1\n' | TUDOR_PROBE=0 timeout 300 ./cli/tudor_cli ` and check for a new crash offset - each fix moves the failure later (proven pattern this session). ## What was fixed this session (detail) WUDF host (`driver_wudf1.cpp`): - V1 sensor interface table (legacy 15-slot layout, no PipelineInit/Activate) - Whole-table restore from pristine file RVAs (runtime clobbering) - CalibrationData PROPVARIANT well-formedness - Device re-acquire across re-enumeration (`winusb.c`) - `tudor_devctrl_wudf1`: wait for driver completion, propagate real status, signal caller's OVERLAPPED - `DeviceIoControl`: correct sync-complete vs ERROR_IO_PENDING semantics - ~30 output-pointer fixes (all Create*/Get* WUDF methods) - `AssignContext`/`RetrieveContext` now store/return context (6 classes) - `CreateWdfMemory`/`CreatePreallocatedWdfMemory`/`CreateWdfObject`/ `CreateWdfFile`/`CreateRequest` return live objects - Init sleeps reduced (50s -> 2s critical path) - Debug aids: TUDOR_LOAD base print, TUDOR_WUDF_TRACE, TUDOR_NO_ENGINE ## Enrollment harness - `work/debug/enroll.sh` - runs the interactive enroll over a pty (init ~3-4 min, then touch the sensor when asked) --- ## Wine sandbox route — WORKING (enroll + verify) 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). ### Components - `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/` - Wine 4.8 fork built locally (see "Wine build fixes" below) - binary: `work/wine-build/install/bin/wine64` - `work/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) ### Usage - **Enroll**: `work/debug/run_aexe.sh enroll a.exe` - Touch the sensor for each of the ~10 captures, then it commits. - Committed record: identity GUID `c5698517-bcff-12e7-2496-b763ed040000`, subfactor `0xF6`, payload `"Unicorn"` (asserted in the commit ioctl 0x442018). - **Verify**: `work/fp-verify.sh` - exit 0 = MATCH (returns the enrolled record from ioctl 0x442004), 1 = no match, 2 = timeout/error. - Warm init to "waiting for finger" ≈ **3.6 s**; whole verify ≈ 5-10 s. - Re-run after USB re-enumeration or a crashed run may "fail the first couple of times" (fake winusb doesn't detect reconnects) — just re-run. ### verify.exe patch (from a.exe, which has symbols) - `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`) ### Proof logs (work/debug/) - `aexe_enroll_VERIFY_SUCCESS.log` — full enroll (10 captures, commit) + identify match in one session - `aexe_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 evidence - No-match behaviour: `0x442004` returns a zeroed record with WinBio error dword `0x8009801F` (verified with a different finger; script exits 1) ### Wine build fixes (old Wine 4.8 on GCC 16 / modern gnutls/openssl) - `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` - configure: `--enable-win64 --with-gnutls --without-x --disable-tests` + disable unneeded modules; CFLAGS `-fcommon -std=gnu89 -Dbool=winbool_field` - Build: `make -j$(nproc)`, install to `work/wine-build/install` ### Next steps for "use it" (auth integration) - PAM: `pam_exec.so seteuid work/fp-verify.sh` on `sudo` / `polkit-1` (fingerprint first, password fallback), and lock screen where applicable. - Optionally a small systemd user unit or daemon mode later to keep Wine warm. ### PAM integration (pam_exec) — used for polkit (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 run Rollback is instant: restore the `.bak-fp` files / remove the polkit override. ```sh # 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. - The window is `FP_VERIFY_TIMEOUT` in `work/fp-pam.sh` (default 15s). - The PAM line runs as root (no `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. - If the fake winusb needs retries (USB re-enumeration), the run fails fast and the password prompt appears — no lockout risk. ### fingerprint OR password instantly (custom pam_fp.so) — ACTIVE for sudo 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: - opens the terminal, starts the fingerprint check in the background and immediately shows `Fingerprint: touch the sensor or type your password: ` - a sensor match -> success; a typed password is validated through the normal `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. - non-terminal contexts (polkit GUI) fall back to a sequential finger check. Build: `cd work/pam && gcc -shared -fPIC -O2 -Wall -o pam_fp.so pam_fp.c -lpam` Test service (sudo): ```sh 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): ```sh 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` ## Persistence / restore (2026-10-13) 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: 1. `git clone ~/projects/fingerprint && cd ~/projects/fingerprint` 2. Rebuild Wine: `work/wine-build.sh` (prereqs: base-devel, mingw-w64-gcc, gnutls, libusb) 3. Sandbox: `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) 4. Prefix: `WINEPREFIX=$PWD/work/wineprefix-48 work/wine-build/install/bin/wine64 wineboot -u` 5. udev: `sudo cp work/system/70-fingerprint-06cb-0081.rules /etc/udev/rules.d/ && sudo udevadm control --reload` 6. PAM: `make -C work/pam && sudo work/pam/install.sh` 7. Test: `work/fp-verify.sh` (touch the sensor) → `Fingerprint matched.` ## Contributing back - `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 `` 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. 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`.