Skip to content

About

Linux driver + provisioning tools for the Synaptics 06cb:00bb fingerprint reader in the HP Spectre x360 13-ap0xxx

Topics

Resources

Stars

0 stars

Watchers

0 watching

Forks

Repository files navigation

python-validity for Synaptics 06cb:00bb (HP Spectre x360 13-ap0xxx)

Linux fingerprint support for the Synaptics/Validity 06cb:00bb sensor used in the HP Spectre x360 13-ap0xxx and likely other HP laptops built around the same module.

This is a fork of SimpleX-T/python-validity (tip 128a9eb, branch feat/sensor-type-0xd51) with the minimum changes needed to detect, re-pair and drive this sensor, plus a small read-only diagnostic and provisioning toolkit for the "sensor is paired to Windows Hello" problem.

Status (2026-10-28): verified end to end on the reference unit. The sensor was wiped and re-provisioned with the DMI-derived key, firmware 1.2 was re-uploaded, and right-index-finger was enrolled. fprintd-verify reports verify-match, and sudo -k; sudo true authenticates with the finger via pam_fprintd without asking for a password. The Windows Hello pairing on the sensor was destroyed, by design — see Safety.

Why this fork exists

The sensor is a 0x969-class Prometheus part:

property value
USB ID 06cb:00bb, USB rev 1.64
sensor type 0x969, hw id 0x88
sensor name 57K0 FM-3439-004
ROM 6.7 build 164
flash Winbond W25Q80B, 1 MiB, 4096-byte sectors
firmware 6_07f_hp_mis_qm.xpfwext (HP SoftPaq, CAB)

libfprint's Synaptics driver is the wrong protocol family: it sends BMKT commands and the device answers 0x0401 to all of them. python-validity's Prometheus path is byte-identical to the captured Windows driver traffic (01, 19, 43 02, then the 581-byte init blob).

The catch: the sensor is TLS-paired to Windows Hello, and the pairing key comes from HP's SGX/Windows driver. There is no portable way to reuse it on Linux. The sensor keeps exactly one pairing, so the usual path is to wipe the flash and create a new pairing whose key is derived from this machine's DMI strings (product_name + product_serial) — which is what set_hwkey() already assumes. This is the recipe reported by Joentja on uunicorn/python-validity#283 for the exact same machine.

If you would rather keep Windows Hello working, try the read-only no-wipe path first. It does not always succeed.

What this fork adds

file change
validitysensor/usb.py SupportedDevices.DEV_BB = (0x06cb, 0x00bb)
validitysensor/blobs.py 00bb → blobs_00cb (init blobs identical to blobs_9a, 0x969 reset blob)
validitysensor/firmware_tables.py DEV_BB → 6_07f_hp_mis_qm.xpfwext (SP138431 URI + SHA512)
validitysensor/glib_compat.py g_unix_signal_add shim for PyGObject 3.48 and older
debian/python3-validity.udev match 06cb:00bb, start the daemon on hotplug
tools/probe00bb.py read-only probe + cert-store backup
tools/checkpair.py read-only: is the sensor already paired to this machine?
tools/hwkey_probe.py read-only/offline: recover the host key of an existing pairing
tools/find_windows_guid.sh read-only: export the Windows MachineGuid from the NTFS partition
tools/dump_windows_pairing.sh read-only: dump the driver's pairing registry values (--name for survey extras)
tools/scan_hive.py dependency-free parser for the Windows registry hive used above
tools/flash00bb.py re-provisioning: preflight / wipe / provision / firmware / verify
tools/test_flash_smoke.py offline (no hardware) test of the wipe/provision flow
install-00bb.sh install driver + udev rule + systemd unit, prerequisites check

No sensor-type, capture or template code was touched: 0x969 is already fully supported at that layer by this fork.

Safety

tools/flash00bb.py --phase all and --phase wipe are destructive. They irreversibly destroy:

  • the Windows Hello pairing stored on the sensor;
  • the Windows Hello fingerprint templates stored on the sensor (partition 4, unreadable without the old pairing);
  • not anything on your disks, and not the Linux pairing afterwards.

The sensor is one-pairing-only. Re-enrolling the fingerprint in Windows later re-pairs it with Windows and breaks the Linux pairing again.

Read-only steps (probe00bb.py, checkpair.py, hwkey_probe.py, --phase preflight, --phase verify) never write to the sensor.

Before wiping, the tooling caches the HP firmware payload outside the repo in /var/lib/python-validity/firmware/, so a wipe interrupted by power loss can still be finished offline. A sensor left with zero partitions is recoverable: re-run --phase provision.

Install

The order matters: cache the firmware before wiping, because the wipe removes the fwext partition from the sensor.

Clone this repository, or unpack the release tarball, and run everything from its root:

cd python-validity-00bb

# 1. dependencies and the open-fprintd backend
sudo apt install python3-usb cabextract
sudo add-apt-repository ppa:uunicorn/open-fprintd
sudo apt update
sudo apt install open-fprintd fprintd-clients     # replaces fprintd; keeps pam_fprintd

# 2. read-only probe (backs up the old cert-store, changes nothing)
sudo python3 tools/probe00bb.py

# 2b. read-only: is the existing pairing already bound to this machine?
sudo python3 tools/checkpair.py            # ALREADY_PAIRED -> skip step 3
#    or analyse the backup without touching the sensor:
# sudo python3 tools/checkpair.py --certstore backups/00bb-certstore-*.bin

# 3. DESTRUCTIVE - only if step 2b says PAIRED_TO_OTHER_HOST or NO_PAIRING
sudo python3 tools/flash00bb.py --phase preflight
sudo python3 tools/flash00bb.py --phase all

# 4. install the driver itself
sudo ./install-00bb.sh

# 5. let the login screen and sudo actually ask for a finger
sudo pam-auth-update --enable fprintd

# 6. enroll and test
fprintd-enroll -f right-index-finger "$USER"
sudo -k; sudo true          # touch the sensor when prompted

fprintd-clients ships pam_fprintd.so, but its PAM profile is disabled by default, so common-auth has no pam_fprintd line until you enable it. Without step 5 enrollment succeeds and fprintd-verify works, yet neither the lock screen nor sudo ever offers a finger. install-00bb.sh --check reports this explicitly and does not touch PAM itself.

tools/checkpair.py reads the cert-store (partition 1), verifies its private-key HMAC against the configured host key, and (with hardware) does a real TLS handshake. It never writes. Exit codes: 0 already paired, 1 needs re-pairing, 2 precondition missing (not root, no device, unreadable DMI).

If the firmware is not cached yet, --phase preflight downloads the pinned HP SoftPaq SP138431, verifies its SHA512 and extracts the payload. The binary is never redistributed in this repository. See firmware/README.md.

No-wipe path: reuse the existing pairing

PAIRED_TO_OTHER_HOST only means the pairing blob is encrypted with a different host secret than the DMI default. Windows encrypted it with some machine-derived secret, so it is potentially recoverable:

sudo python3 tools/hwkey_probe.py                    # DMI candidates
sudo bash tools/find_windows_guid.sh                 # read-only NTFS mount
sudo python3 tools/hwkey_probe.py --guid-file /tmp/opencode/windows-machine-guid.reg
sudo bash tools/dump_windows_pairing.sh              # driver's Pairing* values
sudo python3 tools/hwkey_probe.py --raw-file /tmp/opencode/windows-pairing.txt
sudo python3 tools/hwkey_probe.py --read-part4       # sensor's own record

All of these are read-only. If hwkey_probe.py prints MATCH FOUND, verify it against the live sensor with:

sudo PYTHON_VALIDITY_HW_KEY=<hex from the report> python3 tools/checkpair.py

ALREADY_PAIRED means Linux and Windows Hello can share the pairing. The full procedure, including how to make the override persistent and everything that was ruled out on the reference machine, is in docs/00bb-no-wipe.md.

Wipe and re-provision

tools/flash00bb.py --phase all performs preflight → wipe → provision → verify, asks you to type the sensor serial before wiping, and writes a full log plus the old cert-store backup to backups/ (git-ignored). The xpfwext is cached before anything is wiped:

sudo python3 tools/flash00bb.py --phase all

--firmware /path/to/6_07f_hp_mis_qm.xpfwext skips the download; otherwise the tool fetches the pinned SoftPaq.

If step 3 stops after the wipe (power loss, unplugged cable), the sensor is left with zero partitions but is not bricked. Re-run sudo python3 tools/flash00bb.py --phase provision; the firmware is already in /var/lib/python-validity/firmware/.

--phase provision formats and re-pairs, then hands over to --phase firmware in a fresh TLS session. Run --phase firmware on its own to repair a sensor that is provisioned but has no xpfwext (or a half-written one).

Verify the result

systemctl status python3-validity     # active (running)
fprintd-list "$USER"                  # lists the device + enrolled fingers
fprintd-verify                        # touch the sensor, expect verify-match
journalctl -u python3-validity -n 50

tools/flash00bb.py --phase verify separately proves the link by reading the new cert-store back and completing a TLS 1.2 handshake with the sensor.

Troubleshooting

symptom cause / fix
No devices available daemon not running or udev rule missing: sudo systemctl start python3-validity, systemctl status python3-validity
reset blob -> status 0x0404 wrong sensor. Nothing was changed; do not try other reset blobs. Check lsusb -d 06cb:00bb.
Failed: 0401 at 4f during --phase provision something was sent between the factory reset_blob and 4f. The 0x969 leaves the reset/factory state on any commit (0x1a), and 4f is then illegal. The accepted order is reset blob → register preflight (0x8000205c = 7, read 0x80002080 ∈ {2,3}) → 4f; no 0x75 identify and no 0x1a in between. Re-run --phase provision (it re-sends the reset blob first).
--phase firmware aborts at 0x80002080 unexpected sensor state; do not force it. Re-run --phase provision, and report the value on issue #283.
python3-validity fails with status=203/EXEC /usr/lib/python-validity/dbus-service is missing. Older versions of install-00bb.sh ran plain setup.py install, which falls back to easy_install and silently skips data_files. Re-run sudo ./install-00bb.sh; it now installs the Debian layout and verifies dbus-service, the D-Bus policy and the importable module.
AttributeError: 'gi.repository.GLibUnix' object has no attribute 'signal_add' PyGObject 3.48 renamed the binding (only GLibUnix.signal_add_full remains, and GLib.unix_signal_add is still present). validitysensor/glib_compat.py now picks whichever exists; the installed copy is refreshed by re-running sudo ./install-00bb.sh.
fwext missing from cache run sudo python3 tools/flash00bb.py --phase preflight with network access, or pass --softpaq /path/spXXXXXX.exe
firmware rejected with 044f signature mismatch; pass the SoftPaq matching your region, e.g. SP106161, via --softpaq
dry-run the flow python3 tools/test_flash_smoke.py (no hardware, no root)

Uninstall the driver files with sudo ./install-00bb.sh --uninstall (keeps /etc/python-validity and /var/lib/python-validity).

Tests

PYTHONPYCACHEPREFIX=/tmp/opencode/pyc python3 -m unittest discover -s tests -t tests
PYTHONPYCACHEPREFIX=/tmp/opencode/pyc python3 tools/test_flash_smoke.py

The suite needs no sensor and no root; the smoke test simulates the entire wipe/provision sequence against a fake device.

How this was made

The code, tools and documentation in this repository were written with the help of an AI coding assistant (OpenCode), working from the upstream sources and from live output pasted back from the reference laptop. The hardware steps — flashing, re-provisioning, enrollment and the authentication tests — were executed by the machine's owner, and every change was checked against the running device rather than accepted on trust.

Credits and license

  • Upstream driver: uunicorn/python-validity, the 0xd51 sensor-type work comes from SimpleX-T/python-validity branch feat/sensor-type-0xd51.
  • Joentja's report on issue #283 is the original recipe for this exact machine.
  • Firmware and Windows driver binaries remain HP's property and are not redistributed here.

Licensed under the MIT license, same as upstream. See LICENSE. The upstream README is kept as README-upstream.md.

About

Linux driver + provisioning tools for the Synaptics 06cb:00bb fingerprint reader in the HP Spectre x360 13-ap0xxx

Topics

Resources

Stars

0 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages