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
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