fprintd-shim.py 44 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418419420421422423424425426427428429430431432433434435436437438439440441442443444445446447448449450451452453454455456457458459460461462463464465466467468469470471472473474475476477478479480481482483484485486487488489490491492493494495496497498499500501502503504505506507508509510511512513514515516517518519520521522523524525526527528529530531532533534535536537538539540541542543544545546547548549550551552553554555556557558559560561562563564565566567568569570571572573574575576577578579580581582583584585586587588589590591592593594595596597598599600601602603604605606607608609610611612613614615616617618619620621622623624625626627628629630631632633634635636637638639640641642643644645646647648649650651652653654655656657658659660661662663664665666667668669670671672673674675676677678679680681682683684685686687688689690691692693694695696697698699700701702703704705706707708709710711712713714715716717718719720721722723724725726727728729730731732733734735736737738739740741742743744745746747748749750751752753754755756757758759760761762763764765766767768769770771772773774775776777778779780781782783784785786787788789790791792793794795796797798799800801802803804805806807808809810811812813814815816817818819820821822823824825826827828829830831832833834835836837838839840841842843844845846847848849850851852853854855856857858859860861862863864865866867868869870871872873874875876877878879880881882883884885886887888889890891892893894895896897898899900901902903904905906907908909910911912913914915916917918919920921922923924925926927928929930931932933934935936937938939940941942943944945946947948949950951952953954955956957958959960961962963964965966967968969970971972973974975976977978979980981982983984985986987988989990991992993994995996997998999100010011002100310041005100610071008100910101011101210131014101510161017101810191020102110221023102410251026102710281029103010311032103310341035103610371038103910401041104210431044104510461047104810491050105110521053105410551056105710581059106010611062106310641065106610671068106910701071107210731074107510761077
  1. #!/usr/bin/env python3
  2. """fprintd-compatible D-Bus service backed by the Wine-sandbox driver.
  3. Drop-in replacement for fprintd's daemon for the Synaptics 06cb:0081 sensor
  4. that libfprint cannot drive yet. It serves the `net.reactivated.Fprint` bus
  5. name with the same Manager/Device API, so GNOME Shell (lock-screen
  6. re-authentication), gnome-control-center and pam_fprintd work unchanged.
  7. Verification shells out to work/fp-verify.sh (vendor driver under Wine, run
  8. as the Wine-prefix owner). Enrollment and deletion drive the harness
  9. binaries built by work/artifacts/make-enroll-delete.sh:
  10. enroll.exe - default flow trimmed to enrollment (touch ~10 times)
  11. delete.exe - default flow with enroll() redirected to deleteRecord()
  12. (real sensor-side delete, ioctl 0x442034)
  13. The sensor stores a single template (identity c5698517-.../subfactor 0xF6),
  14. so the per-user finger list in state.json is a mapping onto that one
  15. template: deleting the last reported finger deletes the sensor record,
  16. deleting one of several only updates the reported list.
  17. Run with --session for a session-bus smoke test (no root needed, see
  18. selftest.py / apitest.py).
  19. """
  20. import argparse
  21. import glob
  22. import json
  23. import logging
  24. import os
  25. import select
  26. import signal
  27. import subprocess
  28. import sys
  29. import threading
  30. import time
  31. import gi
  32. gi.require_version('Gio', '2.0')
  33. gi.require_version('GLib', '2.0')
  34. from gi.repository import Gio, GLib # noqa: E402
  35. # ---------------------------------------------------------------- constants
  36. BUS_NAME = 'net.reactivated.Fprint'
  37. MANAGER_PATH = '/net/reactivated/Fprint/Manager'
  38. DEVICE_PATH = '/net/reactivated/Fprint/Device/0'
  39. IFACE_MANAGER = 'net.reactivated.Fprint.Manager'
  40. IFACE_DEVICE = 'net.reactivated.Fprint.Device'
  41. HERE = os.path.dirname(os.path.abspath(__file__))
  42. ROOT = os.path.dirname(os.path.dirname(HERE))
  43. VERIFY_SCRIPT = os.path.join(ROOT, 'work', 'fp-verify.sh')
  44. SANDBOX = os.path.join(ROOT, 'work', 'synaWudfBioUsb-sandbox')
  45. WINE64 = os.path.join(ROOT, 'work', 'wine-build', 'install', 'bin', 'wine64')
  46. ENROLL_EXE = 'enroll.exe'
  47. DELETE_EXE = 'delete.exe'
  48. # same lock file as work/fp-verify.sh: one sensor access at a time
  49. VERIFY_LOCK = '/tmp/opencode/fp-verify.lock'
  50. RUN_USER = 'nebulon'
  51. STATE_DIR = os.environ.get('FP_SHIM_STATE_DIR', '/var/lib/fprintd-shim')
  52. STATE_FILE = os.path.join(STATE_DIR, 'state.json')
  53. DEVICE_NAME = 'Synaptics 06cb:0081'
  54. SCAN_TYPE = 'press'
  55. NUM_ENROLL_STAGES = 10
  56. # pam_fprintd's default per-attempt timeout is 30 s; end our run slightly
  57. # earlier so a no-touch attempt is a clean pam timeout instead of a bogus
  58. # "failed to match".
  59. VERIFY_TIMEOUT = int(os.environ.get('FP_SHIM_VERIFY_TIMEOUT', '26'))
  60. ENROLL_TIMEOUT = int(os.environ.get('FP_SHIM_ENROLL_TIMEOUT', '900'))
  61. DELETE_TIMEOUT = int(os.environ.get('FP_SHIM_DELETE_TIMEOUT', '180'))
  62. FINGERS = [
  63. 'left-thumb', 'left-index-finger', 'left-middle-finger', 'left-ring-finger',
  64. 'left-little-finger', 'right-thumb', 'right-index-finger',
  65. 'right-middle-finger', 'right-ring-finger', 'right-little-finger',
  66. ]
  67. # Bus errors
  68. E_ALREADY_IN_USE = 'net.reactivated.Fprint.Error.AlreadyInUse'
  69. E_CLAIM_DEVICE = 'net.reactivated.Fprint.Error.ClaimDevice'
  70. E_INTERNAL = 'net.reactivated.Fprint.Error.Internal'
  71. E_INVALID_FINGERNAME = 'net.reactivated.Fprint.Error.InvalidFingername'
  72. E_NO_ACTION = 'net.reactivated.Fprint.Error.NoActionInProgress'
  73. E_NO_ENROLLED_PRINTS = 'net.reactivated.Fprint.Error.NoEnrolledPrints'
  74. E_NO_SUCH_DEVICE = 'net.reactivated.Fprint.Error.NoSuchDevice'
  75. E_PERMISSION_DENIED = 'net.reactivated.Fprint.Error.PermissionDenied'
  76. E_PRINTS_NOT_DELETED = 'net.reactivated.Fprint.Error.PrintsNotDeleted'
  77. log = logging.getLogger('fprintd-shim')
  78. MANAGER_XML = """
  79. <node>
  80. <interface name="net.reactivated.Fprint.Manager">
  81. <method name="GetDevices">
  82. <arg type="ao" name="devices" direction="out"/>
  83. </method>
  84. <method name="GetDefaultDevice">
  85. <arg type="o" name="device" direction="out"/>
  86. </method>
  87. </interface>
  88. </node>
  89. """
  90. DEVICE_XML = """
  91. <node>
  92. <interface name="net.reactivated.Fprint.Device">
  93. <method name="ListEnrolledFingers">
  94. <arg type="s" name="username" direction="in"/>
  95. <arg type="as" name="enrolled_fingers" direction="out"/>
  96. </method>
  97. <method name="DeleteEnrolledFingers">
  98. <arg type="s" name="username" direction="in"/>
  99. </method>
  100. <method name="DeleteEnrolledFingers2"/>
  101. <method name="DeleteEnrolledFinger">
  102. <arg type="s" name="finger_name" direction="in"/>
  103. </method>
  104. <method name="Claim">
  105. <arg type="s" name="username" direction="in"/>
  106. </method>
  107. <method name="Release"/>
  108. <method name="VerifyStart">
  109. <arg type="s" name="finger_name" direction="in"/>
  110. </method>
  111. <method name="VerifyStop"/>
  112. <method name="EnrollStart">
  113. <arg type="s" name="finger_name" direction="in"/>
  114. </method>
  115. <method name="EnrollStop"/>
  116. <signal name="VerifyFingerSelected">
  117. <arg type="s" name="finger_name"/>
  118. </signal>
  119. <signal name="VerifyStatus">
  120. <arg type="s" name="result"/>
  121. <arg type="b" name="done"/>
  122. </signal>
  123. <signal name="EnrollStatus">
  124. <arg type="s" name="result"/>
  125. <arg type="b" name="done"/>
  126. </signal>
  127. <property name="name" type="s" access="read"/>
  128. <property name="num-enroll-stages" type="i" access="read"/>
  129. <property name="scan-type" type="s" access="read"/>
  130. <property name="finger-present" type="b" access="read"/>
  131. <property name="finger-needed" type="b" access="read"/>
  132. </interface>
  133. </node>
  134. """
  135. def sensor_present():
  136. """06cb:0081 attached? Mirrors fprintd's "no devices" behaviour."""
  137. try:
  138. for dev in glob.glob('/sys/bus/usb/devices/*'):
  139. try:
  140. with open(os.path.join(dev, 'idVendor')) as f:
  141. vid = f.read().strip()
  142. if vid != '06cb':
  143. continue
  144. with open(os.path.join(dev, 'idProduct')) as f:
  145. pid = f.read().strip()
  146. if pid == '0081':
  147. return True
  148. except OSError:
  149. continue
  150. except OSError:
  151. pass
  152. return False
  153. def default_fingers(user):
  154. """Before any enroll/delete through the shim the sensor already holds the
  155. template enrolled with run_aexe.sh; report it for the workstation user."""
  156. return ['right-index-finger'] if user == RUN_USER else []
  157. def load_state():
  158. try:
  159. with open(STATE_FILE, encoding='utf-8') as f:
  160. state = json.load(f)
  161. if isinstance(state, dict) and isinstance(state.get('users'), dict):
  162. return state
  163. log.warning('%s: unexpected layout, ignoring', STATE_FILE)
  164. except FileNotFoundError:
  165. pass
  166. except (OSError, ValueError) as e:
  167. log.warning('cannot read %s: %s', STATE_FILE, e)
  168. return {'users': {}}
  169. def save_state(state):
  170. os.makedirs(STATE_DIR, mode=0o700, exist_ok=True)
  171. tmp = f'{STATE_FILE}.tmp'
  172. with open(tmp, 'w', encoding='utf-8') as f:
  173. json.dump(state, f, indent=2, sort_keys=True)
  174. f.write('\n')
  175. os.replace(tmp, STATE_FILE)
  176. class ShimDevice:
  177. def __init__(self):
  178. self.conn = None
  179. self.claimed_by = None # unique bus name of the claiming client
  180. self.claimed_user = None
  181. self.lock = threading.Lock()
  182. self.verify_proc = None
  183. self.verify_thread = None
  184. self.verify_cancel = threading.Event()
  185. self.verifying = False
  186. self.enroll_proc = None
  187. self.enroll_thread = None
  188. self.enroll_cancel = threading.Event()
  189. self.enrolling = False
  190. self._enroll_commit_started = False
  191. self.delete_proc = None
  192. self.delete_cancel = threading.Event()
  193. self.deleting = False
  194. self.finger_present = False
  195. self.finger_needed = False
  196. # ------------------------------------------------------------ state
  197. def enrolled_fingers(self, user):
  198. if not user:
  199. user = RUN_USER
  200. users = load_state().get('users', {})
  201. if user in users:
  202. return list(users[user])
  203. return default_fingers(user)
  204. def _set_enrolled_fingers(self, user, fingers):
  205. state = load_state()
  206. state.setdefault('users', {})[user] = sorted(set(fingers))
  207. save_state(state)
  208. def _selected_finger(self, finger):
  209. """fprintd reports the concrete finger chosen for 'any'."""
  210. if finger != 'any':
  211. return finger
  212. fingers = self.enrolled_fingers(self.claimed_user)
  213. return fingers[0] if fingers else 'right-index-finger'
  214. def _busy(self):
  215. return self.verifying or self.enrolling or self.deleting
  216. # ------------------------------------------------------- emission
  217. def _emit(self, name, variant):
  218. GLib.idle_add(self._emit_now, name, variant)
  219. def _emit_now(self, name, variant):
  220. if self.conn is not None:
  221. try:
  222. self.conn.emit_signal(None, DEVICE_PATH, IFACE_DEVICE, name,
  223. variant)
  224. except GLib.Error as e:
  225. log.warning('cannot emit %s: %s', name, e.message)
  226. return GLib.SOURCE_REMOVE
  227. def _notify_properties(self, changed):
  228. if self.conn is None:
  229. return
  230. try:
  231. self.conn.emit_signal(
  232. None, DEVICE_PATH, 'org.freedesktop.DBus.Properties',
  233. 'PropertiesChanged',
  234. GLib.Variant('(sa{sv}as)', (IFACE_DEVICE, changed, [])))
  235. except GLib.Error as e:
  236. log.warning('cannot emit PropertiesChanged: %s', e.message)
  237. def _set_finger_present(self, value):
  238. if self.finger_present == value:
  239. return
  240. self.finger_present = value
  241. self._notify_properties({'finger-present': GLib.Variant('b', value)})
  242. def _set_finger_needed(self, value):
  243. if self.finger_needed == value:
  244. return
  245. self.finger_needed = value
  246. self._notify_properties({'finger-needed': GLib.Variant('b', value)})
  247. # ------------------------------------------------------- claim ops
  248. def _release_claim(self, shutdown=False):
  249. self._stop_verify(quiet=True)
  250. self._stop_enroll(quiet=True)
  251. # A running delete is deliberately left to finish: it mutates the
  252. # device and aborting it can leave a partially written record (the
  253. # client may already be gone; the state is updated when it completes).
  254. if shutdown:
  255. self._stop_delete(quiet=True)
  256. self.claimed_by = None
  257. self.claimed_user = None
  258. self._notify_properties({'num-enroll-stages': GLib.Variant('i', -1)})
  259. def _check_claim(self, sender, invocation):
  260. """fprintd's _fprint_device_check_claimed for STATE_CLAIMED calls."""
  261. if self.claimed_by is None:
  262. invocation.return_dbus_error(E_CLAIM_DEVICE,
  263. 'Device was not claimed before use')
  264. return False
  265. if self.claimed_by != sender:
  266. invocation.return_dbus_error(E_ALREADY_IN_USE,
  267. 'Device already in use by another user')
  268. return False
  269. return True
  270. # ------------------------------------------------------ process ops
  271. def _kill_proc(self, proc):
  272. if proc is None or proc.poll() is not None:
  273. return
  274. try:
  275. os.killpg(os.getpgid(proc.pid), signal.SIGTERM)
  276. except (ProcessLookupError, PermissionError):
  277. return
  278. try:
  279. proc.wait(timeout=5)
  280. except subprocess.TimeoutExpired:
  281. try:
  282. os.killpg(os.getpgid(proc.pid), signal.SIGKILL)
  283. except (ProcessLookupError, PermissionError):
  284. pass
  285. def _harness_env(self, binary):
  286. env = os.environ.copy()
  287. usb_script = f'/tmp/opencode/usb-{binary}-{int(time.time())}.txt'
  288. try:
  289. os.makedirs('/tmp/opencode', exist_ok=True)
  290. # The fake winusb opens USB_SCRIPT for write ("wt") *as the Wine
  291. # user* and does not check for failure - a root-owned file makes
  292. # the harness hang in init without a single message, so create it
  293. # as RUN_USER (verified: winusb.c WinUsb_Initialize).
  294. fd = os.open(usb_script, os.O_CREAT | os.O_WRONLY | os.O_TRUNC, 0o666)
  295. os.close(fd)
  296. if os.geteuid() == 0:
  297. import pwd
  298. pw = pwd.getpwnam(RUN_USER)
  299. os.chown(usb_script, pw.pw_uid, pw.pw_gid)
  300. except (OSError, KeyError) as e:
  301. log.warning('cannot prepare %s: %s', usb_script, e)
  302. env.update({
  303. 'HOME': os.path.join('/home', RUN_USER),
  304. 'WINEPREFIX': os.path.join(ROOT, 'work', 'wineprefix-48'),
  305. # keep wine quiet, but surface winusb/libfprint errors: a failed
  306. # libusb transfer makes the hacked winusb stub exit(0) silently
  307. 'WINEDEBUG': os.environ.get('FP_SHIM_WINEDEBUG', '-all,err+all'),
  308. 'USB_PLAYBACK': '',
  309. 'USB_SCRIPT': usb_script,
  310. })
  311. return env
  312. def _harness_cmd(self, binary):
  313. cmd = [WINE64, binary]
  314. if os.geteuid() == 0:
  315. cmd = ['setpriv', f'--reuid={RUN_USER}', f'--regid={RUN_USER}',
  316. '--init-groups'] + cmd
  317. # one sensor access at a time (same lock as work/fp-verify.sh)
  318. return ['flock', '-w', '60', VERIFY_LOCK] + cmd
  319. def _run_harness(self, binary, timeout, cancel, on_line, proc_slot=None,
  320. expect_markers=None, first_timeout=120):
  321. """Run the Wine harness, feed its stdout lines to on_line().
  322. Returns (status, returncode) with status in
  323. {'eof', 'cancelled', 'timeout', 'stalled'}; the process group is
  324. killed on cancel/timeout. 'stalled' means no line of
  325. expect_markers was seen within first_timeout (the winusb stub hangs
  326. silently when e.g. USB_SCRIPT is not writable by the Wine user).
  327. """
  328. env = self._harness_env(binary)
  329. harness_log = open(
  330. f'/tmp/opencode/harness-{binary}-{int(time.time())}.log',
  331. 'w', encoding='utf-8', errors='replace')
  332. log.info('%s: harness log %s', binary, harness_log.name)
  333. r, w = os.pipe()
  334. proc = subprocess.Popen(self._harness_cmd(binary), cwd=SANDBOX,
  335. env=env, stdin=subprocess.DEVNULL,
  336. stdout=w, stderr=w, start_new_session=True)
  337. os.close(w)
  338. if proc_slot is not None:
  339. proc_slot(proc)
  340. started = time.monotonic()
  341. deadline = started + timeout
  342. status = 'eof'
  343. buf = ''
  344. saw_first = not expect_markers
  345. def feed(chunk):
  346. nonlocal buf, saw_first
  347. buf += chunk
  348. while '\n' in buf:
  349. line, buf = buf.split('\n', 1)
  350. line = line.rstrip('\r')
  351. harness_log.write(line + '\n')
  352. harness_log.flush()
  353. if not saw_first and any(m in line for m in expect_markers):
  354. saw_first = True
  355. if on_line is not None:
  356. on_line(line)
  357. while True:
  358. if cancel.is_set():
  359. self._kill_proc(proc)
  360. status = 'cancelled'
  361. break
  362. if time.monotonic() > deadline:
  363. log.warning('%s: timeout after %ss', binary, timeout)
  364. self._kill_proc(proc)
  365. status = 'timeout'
  366. break
  367. if not saw_first and time.monotonic() - started > first_timeout:
  368. log.error('%s: no progress in %ss (winusb init hang?) - '
  369. 'killing; see %s', binary, first_timeout,
  370. harness_log.name)
  371. self._kill_proc(proc)
  372. status = 'stalled'
  373. break
  374. ready, _, _ = select.select([r], [], [], 0.2)
  375. if ready:
  376. try:
  377. chunk = os.read(r, 65536)
  378. except OSError:
  379. chunk = b''
  380. if not chunk:
  381. break
  382. feed(chunk.decode('utf-8', 'replace'))
  383. elif proc.poll() is not None:
  384. # child exited: drain whatever is left in the pipe
  385. while True:
  386. ready, _, _ = select.select([r], [], [], 0)
  387. if not ready:
  388. break
  389. try:
  390. chunk = os.read(r, 65536)
  391. except OSError:
  392. chunk = b''
  393. if not chunk:
  394. break
  395. feed(chunk.decode('utf-8', 'replace'))
  396. break
  397. code = proc.wait()
  398. os.close(r)
  399. harness_log.close()
  400. if proc_slot is not None:
  401. proc_slot(None)
  402. return status, code
  403. # ------------------------------------------------------ verify ops
  404. def _stop_verify(self, quiet=False):
  405. with self.lock:
  406. running = self.verifying
  407. self.verifying = False
  408. self.verify_cancel.set()
  409. proc = self.verify_proc
  410. self.verify_proc = None
  411. self._kill_proc(proc)
  412. if running and not quiet:
  413. log.info('verify stopped by client')
  414. return running
  415. def _verify_cmd(self):
  416. script = ['/bin/bash', VERIFY_SCRIPT]
  417. if os.geteuid() == 0:
  418. return ['setpriv', f'--reuid={RUN_USER}', f'--regid={RUN_USER}',
  419. '--init-groups'] + script
  420. # session-bus smoke test: we are already the prefix owner
  421. return script
  422. def _verify_worker(self, finger):
  423. try:
  424. self._emit('VerifyFingerSelected', GLib.Variant('(s)', (finger,)))
  425. env = os.environ.copy()
  426. env['FP_VERIFY_TIMEOUT'] = str(VERIFY_TIMEOUT)
  427. env['FP_VERIFY_QUIET'] = '1'
  428. env['FP_VERIFY_LOCK_WAIT'] = '20'
  429. for attempt in (1, 2): # one internal retry for flaky Wine/USB
  430. if self.verify_cancel.is_set():
  431. return
  432. started = time.monotonic()
  433. proc = subprocess.Popen(
  434. self._verify_cmd(), env=env, text=True,
  435. stdout=subprocess.PIPE, stderr=subprocess.STDOUT,
  436. start_new_session=True)
  437. with self.lock:
  438. self.verify_proc = proc
  439. try:
  440. out, _ = proc.communicate(timeout=VERIFY_TIMEOUT + 20)
  441. except subprocess.TimeoutExpired:
  442. self._kill_proc(proc)
  443. out, _ = proc.communicate()
  444. rc = 124
  445. else:
  446. rc = proc.returncode
  447. elapsed = time.monotonic() - started
  448. for line in (out or '').splitlines():
  449. log.info('verify[%d]: %s', attempt, line)
  450. with self.lock:
  451. self.verify_proc = None
  452. if self.verify_cancel.is_set():
  453. return
  454. if rc == 0:
  455. self._emit('VerifyStatus',
  456. GLib.Variant('(sb)', ('verify-match', True)))
  457. return
  458. if rc == 1:
  459. self._emit('VerifyStatus',
  460. GLib.Variant('(sb)', ('verify-no-match', True)))
  461. return
  462. # rc 2: timeout (no finger) or Wine/USB error. A quick exit
  463. # means the sandbox failed before the touch window; retry once.
  464. if attempt == 1 and elapsed < VERIFY_TIMEOUT - 5:
  465. log.warning('verify run failed early (%.1fs, rc=%d), retrying',
  466. elapsed, rc)
  467. continue
  468. log.info('no terminal status (rc=%d after %.1fs); '
  469. 'pam_fprintd will time out', rc, elapsed)
  470. return
  471. finally:
  472. with self.lock:
  473. self.verify_proc = None
  474. # NOTE: keep self.verifying set after a terminal status: fprintd's
  475. # action stays ACTION_VERIFY until VerifyStop/Release (clients like
  476. # fprintd-verify call VerifyStop after the result and expect it to
  477. # succeed).
  478. def _start_verify(self, finger):
  479. with self.lock:
  480. if self._busy():
  481. return False
  482. self.verifying = True
  483. self.verify_cancel.clear()
  484. self.verify_thread = threading.Thread(
  485. target=self._verify_worker, args=(finger,), daemon=True)
  486. self.verify_thread.start()
  487. return True
  488. # ------------------------------------------------------ enroll ops
  489. def _rotate_calibration(self):
  490. """Move saved calibration aside so the driver recalibrates.
  491. The sensor drops its enrollment record when its calibration/ownership
  492. state is reset (unexpected power loss, driver reset, firmware state
  493. change). The saved blob then no longer matches the device and the
  494. capture ioctl waits forever without ever reporting a finger, so
  495. enrollment appears to hang. With no blob present enroll.exe performs
  496. a fresh calibration and saves a new one.
  497. """
  498. for name in ('CalibrationData.blob', 'PairingData.blob'):
  499. path = os.path.join(SANDBOX, name)
  500. if not os.path.exists(path):
  501. continue
  502. backup = f'{path}.stale-{int(time.time())}'
  503. try:
  504. os.replace(path, backup)
  505. except OSError as e:
  506. log.warning('enroll: cannot move %s aside: %s', path, e)
  507. else:
  508. log.info('enroll: moved %s aside (%s); forcing recalibration',
  509. name, os.path.basename(backup))
  510. def _stop_enroll(self, quiet=False):
  511. with self.lock:
  512. running = self.enrolling
  513. commit_started = self._enroll_commit_started
  514. proc = self.enroll_proc
  515. if commit_started and proc is not None and proc.poll() is None:
  516. # The template write is in flight: let it finish instead of
  517. # risking a partially written record. The action stays "in
  518. # progress" until the worker completes.
  519. log.info('enroll: commit in progress, not aborting')
  520. return running
  521. with self.lock:
  522. self.enrolling = False
  523. self.enroll_cancel.set()
  524. self.enroll_proc = None
  525. self._kill_proc(proc)
  526. self._set_finger_needed(False)
  527. self._set_finger_present(False)
  528. if running and not quiet:
  529. log.info('enrollment stopped by client')
  530. return running
  531. def _enroll_worker(self, user, finger):
  532. """Drive `wine enroll.exe`; map the harness output to EnrollStatus.
  533. Markers (see hello.cc enroll()/commitEnrollment()):
  534. "about to Create Enrollment"
  535. "about to IOCTL_BIOMETRIC_CAPTURE_DATA" <- waiting for a touch
  536. "about to Update Enrollment" <- capture accepted
  537. "Got back 0x.. bytes: <hex>" <- response; hex[1:2] is
  538. the stage state (00 = done)
  539. "about to Check For Duplicate" / "about to Commit Enrollment"
  540. A capture marker that follows another capture marker (without an
  541. Update Enrollment in between) is a rejected scan (SensorStatus 2).
  542. """
  543. st = {'capture_open': False, 'expect': None, 'stages': 0,
  544. 'complete': False, 'committed': False}
  545. def on_line(line):
  546. if line == 'about to IOCTL_BIOMETRIC_CAPTURE_DATA':
  547. if st['capture_open']:
  548. log.info('enroll: scan rejected, retry')
  549. self._emit('EnrollStatus',
  550. GLib.Variant('(sb)', ('enroll-retry-scan', False)))
  551. self._set_finger_present(False)
  552. st['capture_open'] = True
  553. st['expect'] = None
  554. self._set_finger_needed(True)
  555. elif line == 'about to Update Enrollment':
  556. st['capture_open'] = False
  557. st['expect'] = 'update'
  558. self._set_finger_needed(False)
  559. self._set_finger_present(True)
  560. elif line == 'about to Check For Duplicate':
  561. st['expect'] = 'duplicate'
  562. elif line == 'about to Commit Enrollment':
  563. st['expect'] = 'commit'
  564. self._enroll_commit_started = True
  565. elif line.startswith('Got back 0x') and st['expect']:
  566. kind, st['expect'] = st['expect'], None
  567. hexpart = line.split(':', 1)[1].strip() if ':' in line else ''
  568. first = hexpart[:2].lower()
  569. if kind == 'update':
  570. self._set_finger_present(False)
  571. if first == '00':
  572. st['complete'] = True
  573. else:
  574. st['stages'] += 1
  575. log.info('enroll: stage %d passed', st['stages'])
  576. self._emit('EnrollStatus',
  577. GLib.Variant('(sb)', ('enroll-stage-passed', False)))
  578. self._set_finger_needed(True)
  579. elif kind == 'commit':
  580. st['committed'] = True
  581. log.info('enroll: committed')
  582. self._set_finger_present(False)
  583. self._set_finger_needed(False)
  584. def slot(proc):
  585. with self.lock:
  586. self.enroll_proc = proc
  587. try:
  588. # A commit that replaces an existing record makes the device
  589. # re-enumerate mid-write; the hacked winusb stub cannot detect
  590. # reconnects and exits with LIBUSB_ERROR_NO_DEVICE (verified
  591. # 2026-10-15 13:11-13:12, harness logs). The delete ioctl does
  592. # not reset the device, and a fresh write commits reliably, so
  593. # clear any existing record first.
  594. if self.enrolled_fingers(user):
  595. log.info('enroll: existing record for %s, deleting it first',
  596. user)
  597. del_st = {'payload': None}
  598. def on_delete_line(line):
  599. if del_st['payload'] is None and line.startswith('Got back 0x'):
  600. hexpart = line.split(':', 1)[1].strip() if ':' in line else ''
  601. del_st['payload'] = hexpart.lower()
  602. dstatus, dcode = self._run_harness(
  603. DELETE_EXE, DELETE_TIMEOUT, self.enroll_cancel,
  604. on_delete_line, slot, expect_markers=('about to 442034',))
  605. payload = del_st['payload'] or ''
  606. d_deleted = payload.startswith('01')
  607. d_none = payload.startswith('00')
  608. d_ok = (dstatus == 'eof' and dcode == 0 and (d_deleted or d_none))
  609. if d_deleted:
  610. d_text = 'deleted existing record'
  611. elif d_none:
  612. d_text = 'no record present'
  613. else:
  614. d_text = 'FAILED'
  615. log.info('enroll: pre-delete %s (harness %s rc=%s payload=%s)',
  616. d_text, dstatus, dcode, payload or '-')
  617. if d_none:
  618. # No template on the sensor means its calibration/ownership
  619. # state was reset: the saved blob is stale and capture would
  620. # hang forever. Force a fresh calibration during this enrol.
  621. self._rotate_calibration()
  622. if d_ok:
  623. # the device has no record now: report that honestly even if
  624. # the enrollment is aborted later on
  625. self._set_enrolled_fingers(user, [])
  626. if self.enroll_cancel.is_set():
  627. log.info('enroll: cancelled before start')
  628. return
  629. status, code = self._run_harness(
  630. ENROLL_EXE, ENROLL_TIMEOUT, self.enroll_cancel, on_line, slot,
  631. expect_markers=('about to setMode', 'about to Create Enrollment',
  632. 'about to IOCTL_BIOMETRIC_CAPTURE_DATA'))
  633. # A committed template is on the device even if the client went
  634. # away meanwhile: always record it and report completion.
  635. if st['committed']:
  636. self._set_enrolled_fingers(user, [finger])
  637. log.info('enroll: user %s -> %s (harness %s rc=%s)',
  638. user, finger, status, code)
  639. self._emit('EnrollStatus',
  640. GLib.Variant('(sb)', ('enroll-completed', True)))
  641. elif self.enroll_cancel.is_set():
  642. log.info('enroll: cancelled')
  643. else:
  644. log.warning('enroll: not committed (harness %s rc=%s, '
  645. '%d stages)', status, code, st['stages'])
  646. self._emit('EnrollStatus',
  647. GLib.Variant('(sb)', ('enroll-failed', True)))
  648. finally:
  649. with self.lock:
  650. self.enroll_proc = None
  651. if self.claimed_by is None or self.enroll_cancel.is_set():
  652. # no client is waiting for a stop reply any more
  653. self.enrolling = False
  654. self._set_finger_needed(False)
  655. self._set_finger_present(False)
  656. # NOTE: like verify, keep self.enrolling set (pending EnrollStop)
  657. # when the client is still connected after a terminal status.
  658. def _start_enroll(self, user, finger):
  659. with self.lock:
  660. if self._busy():
  661. return False
  662. self.enrolling = True
  663. self._enroll_commit_started = False
  664. self.enroll_cancel.clear()
  665. self.enroll_thread = threading.Thread(
  666. target=self._enroll_worker, args=(user, finger), daemon=True)
  667. self.enroll_thread.start()
  668. return True
  669. # ------------------------------------------------------ delete ops
  670. def _stop_delete(self, quiet=True):
  671. with self.lock:
  672. running = self.deleting
  673. self.deleting = False
  674. proc = self.delete_proc
  675. self.delete_proc = None
  676. self.delete_cancel.set()
  677. self._kill_proc(proc)
  678. if running and not quiet:
  679. log.info('delete cancelled')
  680. return running
  681. def _delete_worker(self, invocation, user, remove):
  682. """Remove fingers from the reported list; when the list becomes empty
  683. also delete the sensor-side template (delete.exe)."""
  684. ok, message = True, None
  685. try:
  686. fingers = self.enrolled_fingers(user)
  687. remaining = [f for f in fingers if f not in remove]
  688. if fingers and not remaining:
  689. # Optimistic state update: the client (gnome-control-center)
  690. # re-reads the list right after the call and gives up after
  691. # ~10 s - reflect the deletion immediately, restore below if
  692. # the harness fails.
  693. self._set_enrolled_fingers(user, remaining)
  694. def slot(proc):
  695. with self.lock:
  696. self.delete_proc = proc
  697. status, code = self._run_harness(
  698. DELETE_EXE, DELETE_TIMEOUT, self.delete_cancel, None, slot,
  699. expect_markers=('about to 442034',))
  700. ok = (status == 'eof' and code == 0)
  701. log.info('delete: sensor record removal %s (harness %s rc=%s)',
  702. 'ok' if ok else 'FAILED', status, code)
  703. if not ok:
  704. message = 'Could not delete the print from the device'
  705. self._set_enrolled_fingers(user, fingers) # restore
  706. elif remaining:
  707. self._set_enrolled_fingers(user, remaining)
  708. # NOTE: the state update happens even if the client released the
  709. # claim meanwhile - the device record is gone and must not be
  710. # reported as enrolled.
  711. except Exception:
  712. log.exception('delete failed')
  713. ok, message = False, 'Internal error while deleting'
  714. finally:
  715. with self.lock:
  716. self.delete_proc = None
  717. self.deleting = False
  718. GLib.idle_add(self._finish_delete, invocation, ok, message)
  719. def _finish_delete(self, invocation, ok, message):
  720. try:
  721. if ok:
  722. invocation.return_value(None)
  723. else:
  724. invocation.return_dbus_error(
  725. E_PRINTS_NOT_DELETED,
  726. message or 'Fingerprint was not deleted')
  727. except GLib.Error as e:
  728. # client already gave up / connection closed
  729. log.info('delete reply not delivered: %s', e.message)
  730. return GLib.SOURCE_REMOVE
  731. # ------------------------------------------------ D-Bus callbacks
  732. def on_method_call(self, conn, sender, path, iface, method, params, invocation):
  733. try:
  734. self._dispatch(sender, path, iface, method, params, invocation)
  735. except Exception: # never kill the service on a bug
  736. log.exception('method %s.%s failed', iface, method)
  737. invocation.return_dbus_error(E_INTERNAL, 'shim internal error')
  738. def _dispatch(self, sender, path, iface, method, params, invocation):
  739. if iface == IFACE_MANAGER:
  740. return self._dispatch_manager(method, invocation)
  741. if iface == IFACE_DEVICE:
  742. return self._dispatch_device(sender, method, params, invocation)
  743. invocation.return_dbus_error(E_INTERNAL, f'unknown interface {iface}')
  744. def _dispatch_manager(self, method, invocation):
  745. if method == 'GetDevices':
  746. devices = [DEVICE_PATH] if sensor_present() else []
  747. invocation.return_value(GLib.Variant('(ao)', (devices,)))
  748. elif method == 'GetDefaultDevice':
  749. if not sensor_present():
  750. invocation.return_dbus_error(E_NO_SUCH_DEVICE,
  751. 'No fingerprint device present')
  752. else:
  753. invocation.return_value(GLib.Variant('(o)', (DEVICE_PATH,)))
  754. else:
  755. invocation.return_dbus_error(E_INTERNAL, f'unknown method {method}')
  756. def _dispatch_device(self, sender, method, params, invocation):
  757. if method == 'ListEnrolledFingers':
  758. (user,) = params.unpack()
  759. fingers = self.enrolled_fingers(user)
  760. if not fingers:
  761. invocation.return_dbus_error(
  762. E_NO_ENROLLED_PRINTS, 'No enrolled prints for user')
  763. else:
  764. invocation.return_value(GLib.Variant('(as)', (fingers,)))
  765. elif method == 'Claim':
  766. (user,) = params.unpack()
  767. if self.claimed_by is not None:
  768. invocation.return_dbus_error(E_ALREADY_IN_USE,
  769. 'Device already in use')
  770. return
  771. self.claimed_by = sender
  772. self.claimed_user = user or RUN_USER
  773. log.info('claim by %s for user %s', sender, self.claimed_user)
  774. self._notify_properties(
  775. {'num-enroll-stages': GLib.Variant('i', NUM_ENROLL_STAGES)})
  776. invocation.return_value(None)
  777. elif method == 'Release':
  778. if not self._check_claim(sender, invocation):
  779. return
  780. self._release_claim()
  781. log.info('release by %s', sender)
  782. invocation.return_value(None)
  783. elif method == 'VerifyStart':
  784. (finger,) = params.unpack()
  785. if not self._check_claim(sender, invocation):
  786. return
  787. if finger not in FINGERS and finger != 'any':
  788. invocation.return_dbus_error(E_INVALID_FINGERNAME,
  789. f'Invalid finger name {finger}')
  790. return
  791. fingers = self.enrolled_fingers(self.claimed_user)
  792. if not fingers or (finger != 'any' and finger not in fingers):
  793. invocation.return_dbus_error(
  794. E_NO_ENROLLED_PRINTS, 'No enrolled prints for user')
  795. return
  796. if not self._start_verify(self._selected_finger(finger)):
  797. invocation.return_dbus_error(E_ALREADY_IN_USE,
  798. 'Another operation is in progress')
  799. return
  800. log.info('verify start (%s) by %s', finger, sender)
  801. invocation.return_value(None)
  802. elif method == 'VerifyStop':
  803. if not self._check_claim(sender, invocation):
  804. return
  805. if not self._stop_verify():
  806. invocation.return_dbus_error(E_NO_ACTION,
  807. 'No verification in progress')
  808. return
  809. invocation.return_value(None)
  810. elif method == 'EnrollStart':
  811. (finger,) = params.unpack()
  812. if not self._check_claim(sender, invocation):
  813. return
  814. if finger not in FINGERS:
  815. invocation.return_dbus_error(
  816. E_INVALID_FINGERNAME,
  817. f'Invalid finger name {finger} (not "any")')
  818. return
  819. if not self._start_enroll(self.claimed_user, finger):
  820. invocation.return_dbus_error(E_ALREADY_IN_USE,
  821. 'Another operation is in progress')
  822. return
  823. log.info('enroll start (%s) by %s', finger, sender)
  824. invocation.return_value(None)
  825. elif method == 'EnrollStop':
  826. if not self._check_claim(sender, invocation):
  827. return
  828. if not self._stop_enroll():
  829. invocation.return_dbus_error(E_NO_ACTION,
  830. 'No enrollment in progress')
  831. return
  832. invocation.return_value(None)
  833. elif method == 'DeleteEnrolledFinger':
  834. (finger,) = params.unpack()
  835. if not self._check_claim(sender, invocation):
  836. return
  837. if finger not in FINGERS:
  838. invocation.return_dbus_error(E_INVALID_FINGERNAME,
  839. f'Invalid finger name {finger}')
  840. return
  841. if self._busy():
  842. invocation.return_dbus_error(E_ALREADY_IN_USE,
  843. 'Another operation is in progress')
  844. return
  845. fingers = self.enrolled_fingers(self.claimed_user)
  846. if finger not in fingers:
  847. invocation.return_dbus_error(
  848. E_NO_ENROLLED_PRINTS,
  849. f'Finger {finger} is not enrolled for this user')
  850. return
  851. self._start_delete(invocation, self.claimed_user, [finger])
  852. elif method == 'DeleteEnrolledFingers2':
  853. if not self._check_claim(sender, invocation):
  854. return
  855. if self._busy():
  856. invocation.return_dbus_error(E_ALREADY_IN_USE,
  857. 'Another operation is in progress')
  858. return
  859. fingers = self.enrolled_fingers(self.claimed_user)
  860. if not fingers:
  861. invocation.return_dbus_error(
  862. E_NO_ENROLLED_PRINTS, 'No enrolled prints for user')
  863. return
  864. self._start_delete(invocation, self.claimed_user, fingers)
  865. elif method == 'DeleteEnrolledFingers':
  866. (user,) = params.unpack()
  867. user = user or self.claimed_user or RUN_USER
  868. if user != RUN_USER:
  869. invocation.return_dbus_error(
  870. E_PERMISSION_DENIED,
  871. 'Only the local user is supported by the shim')
  872. return
  873. if self.claimed_by is not None and self.claimed_by != sender:
  874. invocation.return_dbus_error(E_ALREADY_IN_USE,
  875. 'Device already in use by another user')
  876. return
  877. if self._busy():
  878. invocation.return_dbus_error(E_ALREADY_IN_USE,
  879. 'Another operation is in progress')
  880. return
  881. fingers = self.enrolled_fingers(user)
  882. if not fingers:
  883. invocation.return_dbus_error(
  884. E_NO_ENROLLED_PRINTS, 'No enrolled prints for user')
  885. return
  886. self._start_delete(invocation, user, fingers)
  887. else:
  888. invocation.return_dbus_error(E_INTERNAL, f'unknown method {method}')
  889. def _start_delete(self, invocation, user, remove):
  890. with self.lock:
  891. if self._busy():
  892. invocation.return_dbus_error(E_ALREADY_IN_USE,
  893. 'Another operation is in progress')
  894. return
  895. self.deleting = True
  896. self.delete_cancel.clear()
  897. log.info('delete start: user=%s fingers=%s', user, ','.join(remove))
  898. thread = threading.Thread(target=self._delete_worker,
  899. args=(invocation, user, remove), daemon=True)
  900. thread.start()
  901. def on_get_property(self, conn, sender, path, iface, prop):
  902. if iface != IFACE_DEVICE:
  903. return None
  904. if prop == 'name':
  905. return GLib.Variant('s', DEVICE_NAME)
  906. if prop == 'scan-type':
  907. return GLib.Variant('s', SCAN_TYPE)
  908. if prop == 'num-enroll-stages':
  909. stages = NUM_ENROLL_STAGES if self.claimed_by else -1
  910. return GLib.Variant('i', stages)
  911. if prop == 'finger-present':
  912. return GLib.Variant('b', self.finger_present)
  913. if prop == 'finger-needed':
  914. return GLib.Variant('b', self.finger_needed)
  915. return None
  916. def on_name_owner_changed(self, conn, sender, path, iface, signal_name, params):
  917. name, _old, new = params.unpack()
  918. if new:
  919. return
  920. if name == self.claimed_by:
  921. log.info('claiming client %s vanished, releasing device', name)
  922. self._release_claim()
  923. def main():
  924. parser = argparse.ArgumentParser(description=__doc__)
  925. parser.add_argument('--session', action='store_true',
  926. help='own the name on the session bus (smoke test)')
  927. parser.add_argument('--debug', action='store_true')
  928. args = parser.parse_args()
  929. logging.basicConfig(
  930. level=logging.DEBUG if args.debug else logging.INFO,
  931. format='fprintd-shim: %(levelname)s: %(message)s',
  932. stream=sys.stderr)
  933. bus_type = Gio.BusType.SESSION if args.session else Gio.BusType.SYSTEM
  934. device = ShimDevice()
  935. loop = GLib.MainLoop()
  936. manager_info = Gio.DBusNodeInfo.new_for_xml(MANAGER_XML).interfaces[0]
  937. device_info = Gio.DBusNodeInfo.new_for_xml(DEVICE_XML).interfaces[0]
  938. def on_bus_acquired(conn, _name):
  939. device.conn = conn
  940. conn.register_object(MANAGER_PATH, manager_info,
  941. device.on_method_call, device.on_get_property, None)
  942. conn.register_object(DEVICE_PATH, device_info,
  943. device.on_method_call, device.on_get_property, None)
  944. conn.signal_subscribe(
  945. 'org.freedesktop.DBus', 'org.freedesktop.DBus', 'NameOwnerChanged',
  946. '/org/freedesktop/DBus', None, Gio.DBusSignalFlags.NONE,
  947. device.on_name_owner_changed)
  948. log.info('serving %s (device %s, state %s, enroll/delete via %s)',
  949. BUS_NAME, DEVICE_PATH, STATE_FILE, SANDBOX)
  950. def on_name_lost(_conn, _name):
  951. log.warning('lost bus name %s', BUS_NAME)
  952. device._release_claim()
  953. loop.quit()
  954. def on_term(_signum, _frame):
  955. log.info('shutting down')
  956. device._release_claim()
  957. loop.quit()
  958. signal.signal(signal.SIGTERM, on_term)
  959. signal.signal(signal.SIGINT, on_term)
  960. Gio.bus_own_name(bus_type, BUS_NAME, Gio.BusNameOwnerFlags.NONE,
  961. on_bus_acquired, None, on_name_lost)
  962. loop.run()
  963. if __name__ == '__main__':
  964. main()