Skip to content

Say when the xART guard broke Touch ID setup - #64

Open
maralcbr wants to merge 2 commits into
mainfrom
mac/touchid-xart-refusal
Open

maralcbr wants to merge 2 commits into
mainfrom
mac/touchid-xart-refusal

Conversation

@maralcbr

Copy link
Copy Markdown
Member

Summary

Touch ID setup now says when the xART guard broke it (omacom/linux-aurora#209) instead of the generic "/dev/sep-bio never appeared". On kernels without omacom/linux-aurora#212 it also recognises the unfinished key store record that refusal leaves, explains it and stops. It never moves or deletes that record.

 touchid-eligibility
+  keybag: unfinished (APPLE-SEP-KBAG01, v2, state 0) | refused (state 2) | present | nothing
+  unfinished record -> unsupported:unfinished-keybag   # no invitation at boot
 touchid-enable
+  unsupported:unfinished-keybag -> explain, stop before modprobe
   node never appeared
+    diag/xart_guard_refusals > 0
+      record refused (#212)   -> "safety check refused a write ... Restart, then set up again"
+      record unfinished       -> "... Setting it up again won't work: <why>"
+    no refusal, record unfinished -> same "won't work" explanation
+    status: unsupported:unfinished-keybag instead of failed when the record is unfinished
     else -> generic "never appeared; see journalctl -k"
 touchid-activate
+  touchid failed + refusals > 0 -> journal names the refusal (status stays failed)
 enable-fingerprint
+  unsupported:unfinished-keybag, or agreed Mac over an unfinished record -> explain, setup goes on with other readers
+  consent names an earlier key store only for a "present" record (a refused one holds none)

The unfinished-record handling is option B from a debate with GPT-6 Astra: explain and stop, print no move-aside command. Kernel keybag.rs treats a state-0 record as "a bag may exist unnamed", so removing it could strand a key store the enclave holds. README fingerprint-readers updated.

Evidence

  • Before: fresh M2 Max J416c, diag: keybag=failed touchid=failed xart_guard_refusals=1. Setup printed the Secure Enclave driver loaded but /dev/sep-bio never appeared; see journalctl -k for apple_sep. On aurora4 every later setup then failed with EEXIST and gave the same message.
    After: omarchy-mac/test/all in an aarch64 Arch Linux ARM container: 112 ok, 0 not ok. New cases:
    • refusal with a refused (#212) record says restart and set up again; with an unfinished record it says setting up again won't work, keeps the record and records unsupported:unfinished-keybag, which an update in the same boot keeps
    • next setup over an unfinished record stops before modprobe and leaves the record byte-identical
    • an unfinished record without a refusal gets the same explanation; no refusal and no record gets the generic message
    • eligibility: states 0/1/2/3, a short file and an empty file
    • consent: a refused record gets "creates a key store"; an agreed Mac over an unfinished record is told why and not to restart; all within 80 columns
    • activation journal names a refusal; zero refusals gives the plain failure
  • Shellcheck warning counts are unchanged from main for every touched file.
  • Grok 4.7 xhigh review: four findings (same-boot retry text, agreed-Mac path, consent wording for a state-2 record, README pointing at a skipped unit), all fixed, and the re-review found nothing.
  • Not run on hardware.

Merge Danger

Door: two-way

Messages and one new unsupported: reason only. Nothing writes or removes the keybag record. Reverting restores the old messages.

Blast Radius: Touch-ID-setup

Touch ID isn't released yet (edge only). New coupling: userspace now reads the header of /var/lib/aurora-sep-keybag.bin (magic, version 2 at 0x10, state at 0x14), which is the kernel driver's private format, and state 2 isn't merged until omacom/linux-aurora#212 lands. This needs Chris's opt-in as kernel owner before merge. A kernel that changes the format makes the check fall back to present, so it reports nothing new and never blocks setup. The runtime needs no change: the detector ignores unsupported: reasons.

…ed key store

A write the guard refuses while the key store is created leaves the enclave
unanswering until a restart, which setup reported only as a node that never
appeared. A kernel without omacom/linux-aurora#212 also leaves the creation's
intent record, so every later setup fails; setup now says so and stops, and
leaves the record alone.
…nd after an agreement

The status now records the unfinished creation instead of failed, so a second
setup that boot doesn't offer a retry, and a Mac whose agreement survived the
hung creation is told why too. A refused creation's record holds no key store,
so the consent no longer says one is reused.
@maralcbr
maralcbr requested a review from scottjones as a code owner October 25, 2026 10:22
@greptile-apps

greptile-apps Bot commented Oct 25, 2026 •

Copy link
Copy Markdown

RetriggerView in GreptileConfidence Score: 5/5

[Medium impact] The code appears safe to merge, subject to the kernel-owner approval already requested by the author.

Summary

Touch ID setup now explains when the xART guard refused a write and when an unfinished key store prevents another setup attempt.

  • Touch ID setup explains when an unfinished key store blocks another attempt.
  • Touch ID setup names xART refusals and tells owners when to restart.

Acknowledged by maralcbr: reading the kernel’s private record format requires the kernel owner’s opt-in; state-2 support awaits the related kernel change. Keeping unfinished records and offering no removal command is intentional because deletion could strand a key store.

Diagram

%%{init: {'theme': 'neutral'}}%%
flowchart TD
  A[Check key store record] --> B{Unfinished?}
  B -->|Yes| C[Explain and stop Touch ID setup]
  C --> D[Continue with other readers]
  B -->|No| E[Run existing setup]
  E --> F{Required files appeared?}
  F -->|Yes| G[Check activation result]
  F -->|No| H{Guard refused a write?}
  H -->|Yes| I[Explain refusal]
  H -->|No| J[Keep ordinary failure message]
  I --> K{Record now unfinished?}
  K -->|Yes| L[Explain why another attempt cannot work]
  K -->|No| M[Ask owner to restart and retry]
Loading

Reviews (1) · Last reviewed commit: "Keep an unfinished key store's explanati..." · Reviewed by Greptile

@scottjones scottjones left a comment

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thanks, this is a big improvement over "never appeared" for the #209 case. We ran omarchy-mac/test/all on 49c0622 (112 ok). Reverting each of touchid-eligibility, touchid-enable, touchid-activate and enable-fingerprint on its own makes a new case fail, so the tests cover each change. A committed record (state 1 or 3), a v1 or foreign header, and an empty or short file all still read present/available, so a working M2 Max like ours sees nothing new. Consent and the lock are untouched: unsupported:unfinished-keybag exits before the prompt, and touchid-enable checks it under the lock before anything loads. Three things before merge:

  1. "Won't work" may fire on a creation that's still running. omarchy-mac/lib/touchid-enable:165 waits 20 s for the node and the keybag. The driver writes the state 0 intent record before it sends CREATE_KEYBAG, so the keybag file exists as soon as the create starts, and from then on the loop just waits on the node. If the node is still missing at 20 s, lines 194-195 and 213-214 treat any state 0 record as stuck: they record unsupported:unfinished-keybag and tell the owner setting it up again won't work. A slow bring-up whose create is still running at 20 s looks exactly the same at that moment, and the test at omarchy-mac/test/touchid-consent-test.sh:498 covers that case as intended behaviour. Before this PR that case said "failed, restart before trying again", which was right if the create finished later. It isn't a stuck Mac: fail() takes the agreement back, and after a restart the record has committed and Touch ID is offered again. But the owner is told it won't work and loses a boot. Could the stuck verdict also require the driver to say the create failed? diag/keybag reads unknown until provisioning returns and failed once it gives up, so it tells the two apart. Otherwise fall back to the old restart message.

  2. The #212 wording is out of date. linux-aurora#212 merged with the retry for xART-refused creates reverted (06cf15d0f, "No retry after a refused create"). On the merged kernel, a create the guard refuses keeps its state 0 intent and stays EEXIST. State 2 only comes from an unsent create or a non-zero enclave status, and both already existed. So the comment at omarchy-mac/lib/touchid-enable:207, the test comment at omarchy-mac/test/touchid-consent-test.sh:467, the README line ("A kernel with omacom/linux-aurora#212 marks that creation retryable") and the PR body all describe something that didn't ship. The code still does the right thing, because a refusal lands on the "won't work" branch. But the "safety check refused a write while the key store was being created ... Restart, then set up again" branch at line 212 now fires only when refusals happened and the record isn't state 0. That isn't the case it describes. Could we reword it, or narrow it to the state 2 case?

  3. Minor: an agreed Mac over an unfinished record stays turned on. At omarchy-mac/entrypoints/enable-fingerprint:49-52 the agreement and options stay, so omarchy-mac-touchid-load.service keeps loading apple-sep with xart_writes=1 provision_keybag=1 at every boot, and it can never come up. The message says Touch ID is turned on but can't come up, but not how to turn it off: removing the fingerprint (disable-fingerprint) drops the options so the driver stops loading. A line saying so would help. This only reaches a Mac whose agreement outlived the failed create, since touchid-enable takes a new agreement back when it fails.

On merge order: this merges cleanly with main and with #61, but it conflicts with #69 in touchid-eligibility (both add a check just before echo available) and in touchid-consent-test.sh. Both conflicts are mechanical. We'd land #61, then this, and have #69 rebase. This PR also asks for Chris's opt-in on reading the kernel's keybag header, and we agree that should come first.

@audreyt

audreyt commented Nov 5, 2026

Copy link
Copy Markdown

Prepared a merge of current main (7e50e93) into this branch: audreyt/omarchy-mac-pkgs branch mac/touchid-xart-refusal-main-refresh, commit f95d837d0321d48ba8a6797ecd6096b91a8f492b.

I cannot push to this PR's omacom-owned source branch (GitHub returned 403). A maintainer can fast-forward mac/touchid-xart-refusal to that commit: it descends from this PR's unchanged head 49c0622. No history rewrite is needed.

The resolution keeps main's short Touch ID warning and the detailed manual, while retaining this PR's unfinished-keybag checks and diagnostics. The prompt tests now follow the short warning. The keybag fixture remains behind the eligibility helper; the display-only path is no longer rewritten to a long temporary path that falsely trips the 80-column check.

Checks on the resulting tree:

  • bash omarchy-mac/test/all: 115 ok, exit 0.
  • OMARCHY_TEST_RUNTIME=<81fd2d23> bash test/integration/all: 59 ok, exit 0.
  • Scope and architecture gates, Bash syntax, and whitespace check against main: pass.

This update resolves the main conflicts only. It does not address the existing review points about a still-running create at the timeout, the outdated #212 retry explanation, or removal advice for an already-agreed Mac with an unfinished record. The requested opt-in on reading the keybag header is also still outstanding. No hardware qualification or release is claimed.

@audreyt

audreyt commented Nov 16, 2026

Copy link
Copy Markdown

Refreshed again onto current main 76d8b72. Fast-forward commit: c4d5c9bb54eb16232beb0252e7572ead79d7bfd2 on audreyt/omarchy-mac-pkgs, branch mac/touchid-xart-refusal-main-refresh. It descends from f95d837 and from this PR's head 49c0622.

Pushing to omacom's mac/touchid-xart-refusal returned 403 again. A maintainer can fast-forward that branch to c4d5c9b. No history rewrite.

The merge was clean. It keeps this PR's unfinished-keybag checks together with main's current display-wait and boot-check tests.

Local checks, all exit 0:

  • scope and architecture gates
  • git diff --check against main
  • bash omarchy-mac/test/all: 122 ok
  • integration suite: 59 ok, against omacom/omarchy@81fd2d23

Same limits as the 2026-11-05 note: this does not answer the open review points, and it claims no hardware qualification.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants