Skip to content

soc: apple: sep: xart_guard_pin on the M1 Air: hold the window through the first activation, pin up to three lockers (builds on #486) - #506

Draft
malik-na wants to merge 10 commits into
integration/aurorafrom
sep/xart-guard-pin-j313
Draft

malik-na wants to merge 10 commits into
integration/aurorafrom
sep/xart-guard-pin-j313

Conversation

@malik-na

@malik-na malik-na commented Nov 19, 2026 •

Copy link
Copy Markdown
Member

Tested on hardware: MacBook Air M1 (J313). This head was booted on the J313 with xart_writes=1 provision_keybag=1 xart_guard_pins=1 and the guard at level 1:

  • Setup: three pre-Linux lockers pinned, keybag provisioned, xart_guard_refusals 0.
  • Enrol and match: enrol completed, 3 of 3 matches.
  • Reboot: the enrolment restored, 2 of 2 matches, refusals 0.
  • KUnit: the SEP suites ran on the J313 itself: apple_sep_xart_guard 42 of 42, every suite passing.

Why

Touch ID on cold-boot Macs (M1 family) with the xART guard kept on. Today the only way to set it up there is xart_guard=0, which lets the enclave rewrite or delete any macOS session record.

Summary

Builds on #486, whose commit is included unchanged with its author.

#486 as posted fails on the J313. Its first setup rewrites three pre-Linux SEP-xART lockers, not one, and none at the create:

  • two at the COPY_KEYBAG after the create (tags da70de89, 140a890d);
  • one during the first activation, about 280 ms after its LOAD_KEYBAG reply (5700cc64).

All three were present in a raw copy of the iBoot System Container taken before Linux's first xART write.

This PR:

Evidence

Four attempts on the J313 led to the window design:

Attempt Kernel Result
1 #486 COPY_KEYBAG rewrote da70de89; refused, provisioning failed
2 window through provisioning da70de89 pinned, 140a890d refused
3 plus two pins keybag provisioned; 5700cc64 refused in the activation; the enclave then answered nothing more that boot
4 window to the end of the first activation, three pins all three pinned, refusals 0, ready

During the review fixes, closing the window right after sks_recover() was tried on the J313. It refused the third locker again: the LOAD_KEYBAG reply came at 12.386 s and the rewrite at 12.662 s. So the window ends when the first activation returns.

The owner reports macOS Touch ID still works after a guarded setup on this Mac. FileVault and the keychain were not checked one by one.

Verified

  • KUnit on the J313:
    • A kernel with only the two new edge-case tests fails exactly those two (39 of 41).
    • The fixed tree passes 42 of 42 apple_sep_xart_guard and every other apple_sep suite.
    • A test kernel's guard tests bump the same refusal counter the real driver reports, so the Touch ID status reads blocked on a KUnit boot. soc: apple: sep: Let a cold-boot Mac's owner pin the one shared xART locker #486's tests do this too.
  • Host suites: aurora-sep and aurora-sep-slow pass 42 of 43. The one failure, test_desktop_fixes.py, needs a commit a shallow clone lacks, and fails the same way at soc: apple: sep: Let a cold-boot Mac's owner pin the one shared xART locker #486's head.
  • Independent review: each review point and each later fix was checked by a separate agent against the code. They found a test that could not fail, a KUnit test that failed on correct code, reset-hint false positives and stale docs. All are fixed in the pushed commits.

Not tested

  • other cold-boot Macs (J293, J274, J316s, J314s), where the number of lockers and when they are rewritten is unknown;
  • a second user, deleting a print, lockout, and sleep and resume;
  • a later CREATE_KEYBAG after a Touch ID reset under the pin.

🤖 Generated with Claude Code

…locker

On a cold-boot Mac (M1 family), creating the identity keybag rewrites one
session record from before Linux. The xART guard refuses that, so Touch ID
there needs xart_guard=0, which lets the enclave rewrite or delete any
session record on the Mac in order to allow one.

Add xart_guard_pin (default 0). With it set on a cold-boot Mac at level 1,
the first-setup window opens for the install's first CREATE_KEYBAG. The
first existing kind-4 locker the enclave rewrites in it, if the enclave
read that locker since probe, is recorded in the list as pinned before the
write lands. The enclave may rewrite the pinned locker from then on, on
boots where the parameter is set and it has read the locker. The locker is
never deleted or listed as Linux's, and every other record from before
Linux stays refused. Without the parameter nothing changes: a cold-boot
Mac gets no window, and a pin in the list is not honoured.

The guard no longer has a default first-setup rule. sep.rs derives it from
the bootstrap and the parameter, and sks.rs asks the guard for the window
on every platform instead of checking the bootstrap itself.

A keybag created this way has its own record on the list, so matching
reads "unverified" on such a Mac instead of "blocked". A new shim call
moves matching without clearing the refusal count, and a refusal that
lands meanwhile still leaves "blocked". The driver logs a CRC-32 tag of
the pinned locker, and of any kind-4 locker it refuses under the
parameter, so a refusal can be compared with the pin across boots.

The pin is a new kind of list entry, which a kernel without it reads as
one unreadable entry and ignores.

Not run on hardware. Whether macOS tolerates Linux's rewrites of that
locker is as open as it is with xart_guard=0; see XART-SAFETY.md, which
also says what must hold before the first setup under the pin.

Assisted-by: LLM
Signed-off-by: Poul Guo Skov <80295985+poulguoskov@users.noreply.github.com>
Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>

@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 for running this on a J313. The tag-to-gigalocker cross-check is the kind of evidence #486 was missing. A few things before this is ready:

  1. Two host tests fail at this head. Both pass at #486's head.

    • tools/aurora-sep/tests/test_diag_sensor.py (test_the_first_setup_window_brackets_the_create, line 333) still expects store.close_first_setup() inside sks_provision_identity_keybag. It needs updating for the new close.
    • test_packaging.py fails because XART-SAFETY.md changed and the PKGBUILD sum (line 44) didn't. Running updpkgsums fixes it.
  2. The window can now stay open much longer than one setup (sks.rs:708, sbio.rs:1396).

    • The only close is the SetupWindow drop in activate_touchid, which runs on the first open of the bio device.
    • Every failure return in sks_provision_identity_keybag after open_first_setup now leaves the window open for the rest of the boot, because run_bringup returns before register_bio. That covers a missing CREATE reply, a bad status and a failed COPY_KEYBAG. Under Pin, up to three read lockers can be pinned for good in that time.
    • The change also applies to the warm-attach Macs at guard level 1 (J414s, J415, J613), by default, on their first setup. They don't need xart_guard_pin (xart_guard.rs:157). If the create doesn't use their window, it now stays open through COPY_KEYBAG and the whole first activation, and that window passes one rewrite of any existing kind-4 record, with no read check. I've only read this in the code and none of them were tested with it.
    • I'd hold the window only under Pin, close it on every failed provisioning exit, and close it right after sks_recover instead of at the end of activation.
  3. The third pin can only be taken in the provisioning boot. The window opens only on an empty list. Say activation fails before LOAD_KEYBAG (Store::open, enable_sbio, keybag::read or sks_ready), or nothing opens the device that boot. The list then holds the marker and two pins, and every later boot refuses 5700cc64 at LOAD_KEYBAG. By your attempt 3, that leaves the enclave silent for the rest of each boot. announce_pin takes the "pinned" branch, so the reset hint isn't printed either. The normal path with aurora-sep-ready avoids this, which fits your run, but it needs a recovery story or a louder log.

  4. The two #486 findings still reproduce here. With a list read that fails partway, the guard reports the list as not loaded but still lets a read, pinned locker be rewritten. A saved pin that's absent at probe gets adopted as Linux's. Both matter more with three pins.

  5. omarchy-mac can't tell this kernel from #486's. The diag abi file still says 2, and the only visible change is xart_guard_pin's help text. #162 has to check this before offering Touch ID on the J313, and the driver isn't loaded at that point. A new parameter name, or a version that modinfo shows, would let it.

Smaller: the module docs, the FirstSetup and Setup::Pin docs and XART-SAFETY.md's "Fresh installs" text still describe one locker and a create-only window. SetupWindow.open is always true.

I ran the guard's 39 tests on the host with a stand-in for the kernel crate, since I have no QEMU here, and they pass. Breaking MAX_PINS or the "Used once full" rule makes them fail, so the new tests do cover the pin logic. Nothing covers the window's lifetime in sks.rs/sbio.rs.

malik-na added a commit to omacom/omarchy-mac-pkgs that referenced this pull request Nov 19, 2026
From the review of #162:

- touchid-eligibility records unsupported:kernel on the J313 unless
  `modinfo -p apple_sep` lists xart_guard_pins (omacom/linux-aurora#506).
  A kernel with #486's xart_guard_pin pins one locker at the create and
  cannot finish the setup; a built-in driver lists no parameters and is
  refused too, so the one-time invitation never leads to a setup that
  cannot finish.
- touchid-options writes xart_guard_pins=1 on the J313.
- Before loading on the J313, touchid-enable sets aside an earlier try's
  guard list and uncommitted keybag (anything without the driver's magic
  and a committed state) in /var/lib/aurora-sep-touchid-retry-<time>/, so
  the pin window opens again after a try that failed on an older kernel.
  A committed keybag keeps its list; any failed move fails the setup.
- Tests: the kernel check against #506, #486 and parameter-less kernels;
  the set-aside for a list, a header, both, an unwritten file and a
  committed keybag; the M2 Max's options carry no pin. The manual says
  Touch ID is offered on the M1 Air only with such a kernel.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
malik-na added a commit that referenced this pull request Nov 19, 2026
…d an absent locker

Two cases from the review of #486 (matthetherington) and #506 (scottjones),
as KUnit tests through check():

- A list whose read fails partway is reported as not loaded, but the pin
  and the owned record parsed before the failure still count: the pinned
  locker and the listed record can be rewritten.
- A pin saved for a locker that is absent at probe takes the ordinary
  adoption path: the locker is listed as Linux's and can be deleted.

Both fail at this commit; the next one fixes them.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
malik-na added a commit that referenced this pull request Nov 19, 2026
…pins, hint the reset

From the review of #506:

- The first-setup window outlasts the create only under the pin rule
  (Setup::Pin). Without it, as on the warm-attach Macs at level 1, the
  window closes right after the create exchange, as in #486. Under the pin
  rule a SetupWindow closes it on every failed provisioning exit and hands a
  successful one to the first activation, which closes it on any exit before
  LOAD_KEYBAG and right after sks_recover() otherwise.
- The parameter is now xart_guard_pins, so `modinfo -p apple_sep` tells this
  rule (up to three lockers, create to first LOAD_KEYBAG) apart from #486's.
- When the guard refuses a locker the enclave read on an install whose
  window is spent and whose pins are not full, it logs that the first setup
  ended early and how to reset.
- The module, FirstSetup and Setup::Pin docs, XART-SAFETY.md and the
  parameter's help describe up to three lockers and the window's span; the
  aurora-sep package's checksums follow.
- The source-order test of the create follows the new window: held from the
  create, closed unless pinning, handed to the first activation, closed
  there after sks_recover().

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@malik-na

Copy link
Copy Markdown
Member Author

Thanks for the careful read. Addressed in 393a21f..58e20b6. Each fix was checked by a separate agent against the code, and the final tree ran on the J313: KUnit there, plus a fresh guarded setup, enrol, matches and a reboot.

1. Host tests. Both pass. test_the_first_setup_window_brackets_the_create now checks the new contract:

  • provisioning holds the window across the create and hands the decision to the guard (end_create);
  • activate_touchid takes its hold before its first fallible step and releases it only on return.

The PKGBUILD sums follow XART-SAFETY.md. The aurora-sep and aurora-sep-slow suites pass 42 of 43, the same as #486's head; test_desktop_fixes.py needs a commit a shallow clone lacks.

2. Window lifetime. Done as you suggested, with one exception that the hardware decided.

  • Only under Pin. The guard decides in Guard::end_create. Warm-attach Macs close the window right after the create exchange, as in soc: apple: sep: Let a cold-boot Mac's owner pin the one shared xART locker #486, and a KUnit test drives that decision.
  • Every failed provisioning exit closes it, through a drop guard. So does a register_bio failure, since no activation can follow.
  • Close right after sks_recover: tried on the J313, and it fails. The LOAD_KEYBAG reply came at 12.386 s, and the enclave's rewrite of the third locker (5700cc64) at 12.662 s, during the activation's next requests. The window was shut, the guard refused it, and the enclave stopped answering (DEVICE_STATE_TRANSITION, ref-key unlock, sensor registration). So the window is held until activate_touchid returns. Its drop guard closes it on every earlier exit too.
  • Still open: a bio_open that fails before reaching activate_touchid leaves the window open until the boot ends. That case is documented, and it only pins lockers the enclave read.

3. Third pin only in the provisioning boot. Kept as a louder log with a recovery. Once the window is closed with free pins, a refused read locker logs:

  • the window is spent, with N of 3 lockers pinned, so the rewrite stays refused;
  • the reset with --force, then removing the list, which the reset keeps, and what that costs.

It fires only at level 1, for a write. It does not guess the cause: on a healthy one-pin Mac it would only fire on a refusal that is real anyway. omarchy-mac (#162) now does that set-aside itself for a setup that failed for good.

4. #486's two findings.

  • A list whose read fails partway now counts for nothing: no pins, no owned records, no spent window.
  • A pinned locker is never adopted as Linux's, even when absent at probe. When recreated and read, it can be rewritten, but never listed or deleted.

Both have KUnit tests that failed on the J313 before the fix (39 of 41) and pass after.

5. Telling this kernel apart. The parameter is now xart_guard_pins. modinfo -p apple_sep shows it, and #486's xart_guard_pin doesn't match the anchored name. #162 offers Touch ID on the J313 only when it's there; a built-in driver lists no parameters and is refused too.

Smaller. The module, FirstSetup, Setup::Pin, ABI and XART-SAFETY.md docs describe up to three lockers and the window's real span, scoped to the one J313 run. SetupWindow.open now carries the create's real result. A pin past the third is logged as such, not as an unreadable entry.

malik-na and others added 9 commits November 20, 2026 00:01
…ation

On a MacBook Air M1 (J313, 13.5 sepOS), the pre-Linux lockers are not
rewritten by CREATE_KEYBAG. Two are rewritten by the COPY_KEYBAG of the new
bag that follows it, and one by the first activation's LOAD_KEYBAG. With the
window closed straight after the create exchange, the guard refused the first
of them (tag da70de89, read this boot), COPY_KEYBAG failed, and so did
provisioning.

Leave the window open when provisioning returns, and close it when the first
activate_touchid() returns. A SetupWindow drop guard closes it on every path.
The window still opens at most once per install, on an empty list.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Signed-off-by: Naeem Malik <malik2015naeem@gmail.com>
On a MacBook Air M1 (J313, 13.5 sepOS) the first Touch ID setup rewrites
three pre-Linux kind-4 lockers, all read since probe: two at COPY_KEYBAG
(tags da70de89, 140a890d) and one at the first activation's LOAD_KEYBAG
(5700cc64). All three are in a copy of the iBoot System Container taken
before Linux's first xART write. With one pin the second was refused; with
two, the third, after which the enclave stopped answering for the boot.

Hold up to three pins (MAX_PINS). Each still needs an enclave read since
probe, is never deleted and is never listed as Linux's; the window closes
once all three are used or the first activation returns. A fourth read locker
stays refused. Messages, the parameter's help, the KUnit tests and
XART-SAFETY.md say so.

With this and the previous commit, on the J313: provisioned, three pins,
xart_guard_refusals 0, enrol, 3/3 matches; after a reboot the enrolment is
restored, 2/2 matches, refusals 0, 15 of 16 session records still protected.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Signed-off-by: Naeem Malik <malik2015naeem@gmail.com>
…d an absent locker

Two cases from the review of #486 (matthetherington) and #506 (scottjones),
as KUnit tests through check():

- A list whose read fails partway is reported as not loaded, but the pin
  and the owned record parsed before the failure still count: the pinned
  locker and the listed record can be rewritten.
- A pin saved for a locker that is absent at probe takes the ordinary
  adoption path: the locker is listed as Linux's and can be deleted.

Both fail at this commit; the next one fixes them.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Signed-off-by: Naeem Malik <malik2015naeem@gmail.com>
…locker

A list whose read fails partway left the owned records and pins parsed
before the failure in the guard, while the guard reported the list as not
loaded. Clear everything load() set when it fails, so an unreadable list
protects every existing record as the warning says.

check() classified a saved pin only through decide(), so a pinned locker
that was absent at probe was adopted as Linux's. Classify a pinned locker
that is not Linux's as refused first; the pinned allowance (read since
probe) still applies to it.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Signed-off-by: Naeem Malik <malik2015naeem@gmail.com>
…pins, hint the reset

From the review of #506:

- The first-setup window outlasts the create only under the pin rule
  (Setup::Pin). Without it, as on the warm-attach Macs at level 1, the
  window closes right after the create exchange, as in #486. Under the pin
  rule a SetupWindow closes it on every failed provisioning exit and hands a
  successful one to the first activation, which closes it on any exit before
  LOAD_KEYBAG and right after sks_recover() otherwise.
- The parameter is now xart_guard_pins, so `modinfo -p apple_sep` tells this
  rule (up to three lockers, create to first LOAD_KEYBAG) apart from #486's.
- When the guard refuses a locker the enclave read on an install whose
  window is spent and whose pins are not full, it logs that the first setup
  ended early and how to reset.
- The module, FirstSetup and Setup::Pin docs, XART-SAFETY.md and the
  parameter's help describe up to three lockers and the window's span; the
  aurora-sep package's checksums follow.
- The source-order test of the create follows the new window: held from the
  create, closed unless pinning, handed to the first activation, closed
  there after sks_recover().

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Signed-off-by: Naeem Malik <malik2015naeem@gmail.com>
…ghten the docs

From independent checks of the previous commit:

- The guard, not sks.rs, decides whether the first-setup window outlasts
  the create (Guard::end_create): only under the pin rule. A KUnit test
  drives that decision: after end_create a warm-attach window refuses a
  locker rewrite, a pinning one still pins a read locker. The source-order
  test now also requires the window's release to be the statement right
  after sks_recover().
- If /dev/sep-bio cannot be published after provisioning, no activation can
  follow, so a pinning window is closed there.
- The reset hint fires only at level 1, for a rewrite (not a delete), once
  the window is closed and pins are free, and is worded as a possible cause.
  It names both steps: the reset and removing the list, which the reset keeps.
- The partial-list test also checks the spent window does not count; the
  absent-pin test covers a recreated and read pinned locker being rewritten
  but never listed or deleted.
- Docs and comments that still described one locker, a create-only window,
  or "only the first pin counts", or that claimed more than one J313 run,
  are corrected; doc comments displaced by the new helpers are restored.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Signed-off-by: Naeem Malik <malik2015naeem@gmail.com>
…e docs to the J313 run

From independent checks of the previous commit:

- only_a_pinning_window_outlasts_the_create checked a locker that was not
  in the existing set, so the guard adopted it and the test failed on
  correct code (KUnit on a J313: "Expected guard.check(&other, true) ==
  Err(EPERM)"). It now uses an existing, read locker.
- The reset hint no longer guesses the cause: it states the window is spent
  with N of 3 lockers pinned and the rewrite stays refused, and gives the
  reset with --force (the tool refuses a working keybag otherwise), removing
  the list, and what removing it costs.
- A pin entry past the first three, or repeated, is logged as such, not as
  an unreadable entry.
- The host test also requires the window holder's end_create to call the
  guard's.
- Docs: a cold-boot Mac without the parameter gets no window; T6001/T6002
  are untested against either T6000 or T8103; when the window stays open or
  closes if the first activation does not reach LOAD_KEYBAG; matches had no
  refusal (root writes are allowed and not logged), not "only those
  records"; a later create after a reset is untested; plural pins
  throughout; claims about the pin rule scoped to the one J313 run.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Signed-off-by: Naeem Malik <malik2015naeem@gmail.com>
Closing the pinning window right after sks_recover() (review suggestion,
applied in 9b5c265) failed on the J313. With the final tree booted
(7.2.11-pr506c), the LOAD_KEYBAG reply came at 12.386 s and the enclave's
rewrite of the third pre-Linux locker (tag 5700cc64) at 12.662 s, during the
activation's next requests; the window was shut, the guard refused it, and
the enclave stopped answering (DEVICE_STATE_TRANSITION, ref-key unlock,
sensor registration). The version run successfully earlier on the same Mac
(d7cbd45fe) held the window until activate_touchid() returned.

Hold it until the first activation returns; the drop guard still closes it
on every earlier exit. The comment that called LOAD_KEYBAG the last request
to rewrite a shared locker was wrong and is gone; the docs and the
source-order test follow.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Signed-off-by: Naeem Malik <malik2015naeem@gmail.com>
Scope the pin results to the one J313 run; say the reset hint and the
refused-locker tag are logged with the first eight refusals in a boot, and
the tag only for kind-4 lockers; plural pins where the code allows three;
the FirstSetup and open_first_setup docs give every case. No code change.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Signed-off-by: Naeem Malik <malik2015naeem@gmail.com>
@malik-na
malik-na force-pushed the sep/xart-guard-pin-j313 branch from 58e20b6 to 56b08fa Compare November 19, 2026 18:31

@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 covers everything I raised. And thanks for running the final tree on the J313. I re-read it at 56b08fa:

  • Both host tests pass. Removing end_create or the hand-off to activation makes the window test fail. Removing the close after a failed register_bio doesn't, so that one line is only covered by reading it.
  • On the warm-attach Macs the window still closes right after the create exchange, where integration/aurora closes it today, so the M3 Air and the M2s are unchanged there. Every failed provisioning exit closes it through the drop guard.
  • The open case is a provisioning boot that never reaches activate_touchid. It's limited the way XART-SAFETY.md says: only a rewrite of a kind-4 locker the enclave read that boot gets through, and only while pin slots are free. The window ends with the boot, but anything it pinned stays pinned. I'm fine with that given the new warning.
  • The spent-window warning fires where you describe, and the recovery steps match what --reset-touchid does.
  • I couldn't break either #486 fix without a test failing.
  • A module built from this head shows xart_guard_pins in modinfo -p.

Could you try two more things on the J313 if you get a chance? First, boot back into macOS after the Linux setup and check Touch ID still unlocks and still works for a purchase or password prompt there, since those three lockers predate Linux. Second, boot an older kernel once, then do a plain reboot back to this one, and check Touch ID matches again. Then the doc can say what actually happens in both cases.

One small doc ask, not blocking. XART-SAFETY.md says a kernel without pinning, or a boot without xart_guard_pins=1, refuses the pinned lockers. Your own run shows that's sharper on the J313: the enclave stops answering for that boot, so Touch ID is out until you boot this kernel with the parameter again. I'd expect nothing lasting, but nobody has tried a plain reboot after that. Saying so in the doc would help anyone who boots an older kernel.

Good from my side. I haven't run it on hardware.

@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 for confirming Touch ID still works in macOS and again in Linux after rebooting back. That was the big one. Approving at 56b08fa. The older kernel round trip can be a follow-up rather than a blocker: an older kernel has no pins and the companion package change just shows a message and changes nothing there, so one run on the J313 whenever it's convenient is plenty. If you want, a line in XART-SAFETY.md about what happens on an older kernel and after the reboot back would still help, but that's optional. Really nice work on this one.

@poulguoskov

Copy link
Copy Markdown

Tested 56b08fa on a MacBook Pro 16" M1 Pro (J316s). Pinning works here. Enrolment never got past the first capture, and I think that's a separate sensor bring-up problem, not the guard.

Setup

  • J316s, system firmware 27.0, OS firmware 13.5, iBoot-8422.141.2, FileVault on in macOS. Touch ID worked in macOS before the test.
  • Kernel built from this PR's head (7.2.11-pin506+), installed next to the stock linux-aurora as an extra Limine entry. The driver is loaded by hand with xart_writes=1 provision_keybag=1 xart_guard_pins=1.
  • fprintd 1.94.5, libfprint-git 1.94.100.r10.g6f9479c.
  • I backed up the iBoot System Container before the first load.

Pinning: works

First load, on a Mac that had never run Touch ID setup under Linux:

xART guard level 1: 11 session records exist, 0 created by Linux; the other 11 are protected
xART guard: xart_guard_pins is set and no locker is pinned: this install's first Touch ID setup may pin up to three
xART: ... 170 slots, 13 live records, max revision 25417, 0 malformed, 0 duplicate, 0 repaired; writes ENABLED
[963.99] xART guard: pinned the existing SEP-xART locker the enclave rewrote during this install's first Touch ID setup (tag 74716975)
[964.73] xART guard: allowed the enclave to rewrite this install's pinned SEP-xART locker (tag 74716975)
[964.91] sks: identity keybag provisioned

xart_guard_refusals stayed at 0 through everything below. After a reboot the pin held, and LOAD_KEYBAG answered with status 0:

xART guard level 1: 12 session records exist, 1 created by Linux; the other 11 are protected
xART guard: xart_guard_pins is set: the enclave may rewrite this install's pinned SEP-xART locker (tag 74716975) once it has read it

Only one locker was pinned here, where the J313 needed three. Since enrolment failed, Touch ID's first activation never ran. If the J316s rewrites more lockers during activation, as the J313's third one did, this test hasn't reached that yet.

Enrolment: the sensor drops to state 9 on the first capture

The sensor binds and comes online (CS timing 20 ns programmed in hardware, 8000000 Hz, mode 2, diag/sensor=online, touchid=ready). Every fprintd-enroll then fails the same way. Three tries had the calibration in place, one of them right after a clean reboot:

sbio: registering sensor at bring-up stage 2
sbio: identity count 0 before CLEAR_STATE for sensor re-registration
sbio: identity count 0 after CLEAR_STATE for sensor re-registration
sbio: identity count 0 after sensor serial registration
sep sensor: data-ready IRQ 142 configured for interrupt capture
enrol: after system SELECT_CONTEXT master catacomb state 0x3
enrol: after system SELECT_CONTEXT owner catacomb state 0x3
enrol: the sensor fell to state 9 during capture 0

The capture lasted 10.1 s, 2.2 s and 8.8 s before the fault. fprintd prints one enroll-stage-passed and then enroll-unknown-error. There's no sensor patch: warning in any of these bring-ups, but a successful patch logs nothing either, so the log doesn't say whether the patch was sent.

A guess at the cause, from reading the code, not tested: after the CLEAR_STATE re-registration, registration::patch_loaded decides whether to send the patch again. On a profile without a nonce session, which includes T6000, it trusts the acknowledgement at status[8] alone and ignores state 9. apply_sensor_patch already handles a sensor that reports the patch as accepted and still asks for it ("acknowledged, but the sensor still asks for a patch"). If the M1 Pro sensor keeps a stale 0x29 acknowledgement after CLEAR_STATE, the driver would skip the patch and the capture would hit state 9. That would match what I see. The J313 uses the same rule and enrols fine, so I may be wrong. Treating state 9 as "needs patch" on T6000 too would test it. I can run a build with that change or with sensor_trace on if it helps.

I can't tell whether this is specific to #506. On the stock kernel the guard refuses the keybag create, so enrolment was never reached there.

Full logs (before and after each load, and each enrolment try) are available if you want them. The test kernel stays installed, so I can rerun anything.

@slycke

slycke commented Nov 21, 2026

Copy link
Copy Markdown

J293 hardware test passed on 56b08fae. Tested on a 13-inch MacBook Pro (M1, 2020). The device tree reports apple,j293. T8103/J313 is the driver’s shared profile label.

With xart_writes=1 provision_keybag=1 xart_guard=1 xart_guard_pins=1, fresh enrollment and matching succeeded. The fingerprint restored and matched after reboot with both manual and automatic activation. xart_guard_refusals was 0 at each check. Fingerprint unlock also worked after suspend/resume.

@scottjones

Copy link
Copy Markdown
Collaborator

Hardware evidence for this on our 7.3 port, run today in the Omarchy Mac Lab on Naeem's MacBook Air M1 (J313), with Naeem at the Mac. slycke's J293 run on 56b08fa already passed separately above, so this adds the 7.3 port on J313.

The port

#486 and #506 are ported onto the edgeC 7.3 base as port/xart-pin-7.3 (7d15e09, test kernel 7.3.0-xartpin). It's a port rather than a cherry-pick because 7.3 replaced 7.2's first-setup window with per-boot windows, so the pins are rebuilt on top of those. Two changes beyond the PR: a pin saves the previous policy value before it is written, and provisioning opens the window before it writes the intent. Naeem stays the author with his Signed-off-by and a "Ported from" note, and Poul is credited as co-developer.

What we ran

The lab baseline passed first. Naeem's Linux Touch ID state was backed up with checksums before the runs and restored after.

Boot 1 (apple_sep xart_writes=1 provision_keybag=1 xart_guard=1 xart_guard_pins=1):

  • The first Touch ID setup window stayed open until the first activation returned.
  • The enclave rewrote 3 existing kind-4 lockers, and each was pinned (1, 2, 3 of 3) with its previous value saved.
  • Identity keybag provisioned, fprintd-enroll right-index-finger gave enroll-completed, fprintd-verify gave verify-match.

Boot 2:

  • Catacombs restored and the enrollment survived the reboot.
  • The guard let the enclave rewrite this install's pinned locker, which is the documented later-boot behavior.
  • fprintd-verify gave verify-match, same identity as boot 1.

No real records were refused in either boot. The other "refused" lines in dmesg are KUnit tests with synthetic ids. macOS Touch ID still worked afterwards.

Key lines from the two runs:

[   84.691979] apple_sep: xART guard: this install's first Touch ID setup window is open until the first activation returns
[   87.440527] apple_sep 242400000.sep: sks: identity keybag provisioned
[   25.871781] m1-air-omarchy kernel: apple_sep 242400000.sep: Touch ID: restored 1 enrolled identity/identities; enrolment survived reboot

Notes for anyone testing on 7.3

  1. Rust module parameters are set-once. Setting xart_guard_pins both in modprobe.d and on the kernel command line makes apple_sep fail to load, so set it in one place:

    apple_sep: `1' invalid for parameter `xart_guard_pins'
    
  2. On 7.3, M1 needs xart_guard=1 set explicitly (the default there is 0), plus xart_guard_pins=1. That matters for s2idle: Thunderbolt display on the borrowed dcpext1 route stays dark after resume (DPTX validate times out), while HDMI holds dcpext0 #162's touchid-options.

  3. 7.3's sep-bio speaks interface 5, so libfprint-git -6 is required. With -5, fprintd logs "interface version 5, expected 4" and reports "No devices available".

  4. Testing the port on a Mac that already had a Linux enrollment re-seals that enrollment: the first setup's locker rewrites mean the pre-test owner and user catacombs no longer restore on the old kernel. macOS Touch ID is unaffected. Plan on a fresh fprintd-enroll afterwards.

The branch is at scottjones/aurora-linux xart-pin-7.3-for-naeem if anyone wants to try it.

One lab check failed in both runs: omarchy-mac-touchid-activate.service reported "matching blocked". That's its readiness check running before matching was ready, and enroll and verify both worked, so I don't read it as a fault in this PR.

Thanks Naeem for lending the Air and staying with it through both boots, and Poul for the groundwork in #486.

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.

4 participants