Skip to content

soc: apple: sep: Let a cold-boot Mac's owner pin the one shared xART locker - #486

Draft
poulguoskov wants to merge 1 commit into
omacom:integration/aurorafrom
poulguoskov:sep/xart-guard-pin
Draft

poulguoskov wants to merge 1 commit into
omacom:integration/aurorafrom
poulguoskov:sep/xart-guard-pin

Conversation

@poulguoskov

Copy link
Copy Markdown

Draft, for review of the approach before anything else. Not run on
hardware
: I have no Mac I can risk on it, so this needs a tester who
already runs a cold-boot Mac with xart_guard=0, or a decision that the
approach is wrong. The patch was written with an LLM (Claude) and reviewed and
tested off-device as listed under "Evidence". Against integration/aurora at
39d5f88ab4e5.

Summary

On a cold-boot Mac (M1 family), creating Linux's identity keybag rewrites one
session record from before Linux, and the xART guard refuses it. Today the only
way to use Touch ID there is xart_guard=0, which lets the enclave rewrite or
delete every session record on the Mac in order to allow one
(XART-SAFETY.md, "Cold-boot SEP Macs rewrite a pre-Linux record";
#269).

This patch adds xart_guard_pin (default 0). It changes nothing unless set,
and has an effect only on a cold-boot Mac at guard level 1:

  • The window opens. The first-setup window from soc: apple: sep: let a fresh install create its Touch ID keybag #212, which cold-boot Macs
    never get, opens for the first CREATE_KEYBAG of an install whose list is
    loaded and empty. The marker is written first, as on warm-attach Macs. An
    earlier guarded attempt leaves the list non-empty, and the driver says so at
    probe instead of promising a pin.
  • One locker is pinned. In the window the guard passes one rewrite of an
    existing kind-4 locker, and only of a locker the enclave read since probe
    (xarm.rs now tells the guard about each OP_SESSION_READ it answers with
    a record). Before the write reaches the gigalocker, a pin entry naming that
    locker is appended to the list and flushed. If the pin can't be made
    durable, the rewrite is refused.
  • The pin holds afterwards. The enclave may rewrite the pinned locker on
    any later boot where the parameter is set and it has read the locker. That
    is meant to cover a match and a later CREATE_KEYBAG after a Touch ID reset.
  • Everything else stays guarded. The pinned locker is never deleted and
    never listed as Linux's. Every other record from before Linux is refused as
    before. Level 2 gets none of this, and without the parameter the pin in the
    list is not honoured.
  • matching follows. The record the create adds is listed as on any
    guarded Mac, so on a cold-boot Mac set up this way matching reads
    unverified instead of blocked. A new shim call updates it without
    clearing the refusal count.
  • Refusals can be compared with the pin. The driver logs a CRC-32 tag of
    the pinned locker, and of any kind-4 locker it refuses under the parameter
    together with whether the enclave had read it. The session id itself is
    never logged.

The pin is a new kind of list entry (flag in byte 5, which owned entries keep
zero). A kernel without this patch reads it as one unreadable entry, warns,
and ignores it.

The guard no longer has a default first-setup rule. Guard::new takes the
platform's rule, and sep.rs derives it from the bootstrap and the parameter,
so a caller cannot get the warm-attach window by leaving something out.
sks.rs asks the guard for the window on every platform and the guard
decides.

Why this shape

Not addressed: the intermittent sensor attach failures on J316s
(#42), and Macs whose keybag was already created with the
guard off (their records are not on the list; they need a Touch ID reset with
the list removed, or xart_guard=0 as today).

Evidence

All of it is off-device.

Check Result
Kernel build with tools/aurora-ci/aurora.kunitconfig (APPLE_SEP=y, APPLE_SEP_KUNIT_TEST=y), LLVM 23.1.3, Rust 1.85.0, bindgen 0.72.1 builds; no warning from drivers/soc/apple
tools/aurora-ci/run-kunit.py under QEMU 11.1.2 (arm64, 16K pages), compared with kunit-expected.json 147 suites, 1779 cases: 1776 pass, 0 fail, the 3 expected skips, 0 kernel splats; no difference from the expected results
apple_sep_xart_guard in that run 39 of 39 pass (28 existing, 11 new)
The other nine apple_sep_* suites in that run 94 of 94 pass
xart_guard.rs (with its KUnit tests), xart_store.rs and xarm.rs built with rustc 1.100, warnings denied, against stand-ins for the kernel crate builds
The 28 existing guard tests, with their assertions unchanged pass
11 new guard tests (in the patch) pass
3 end-to-end tests (host harness, not in the patch): xART requests through xarm::service() into the real Store and Guard, over in-memory files, across three boots pass
19 deliberate breakages, one rule each (16 in Rust, 2 in diag_shim.c, 1 reordered call in sks.rs) each fails at least one test
Module build with a shipped kernel's config (APPLE_SEP=m, from a running 7.2.11.aurora14 kernel) and CLIPPY=1 builds and links apple-sep; Clippy reports nothing in the lines the patch changes
scripts/checkpatch.pl on the patch 0 errors, 1 warning (a long string line)
rustfmt --check over the driver, before and after same findings per file; the patch adds none
tools/aurora-ci/host-tests.py, groups aurora-sep and aurora-sep-slow (43 suites) 42 pass and the tree is left unchanged; test_desktop_fixes.py fails because it reads commit 05d6db, which a shallow clone lacks
Among those: test_packaging (4), test_sep_ready (22), test_diag_sensor (4, builds diag_shim.c with -Wall -Werror) pass
git apply --check on 39d5f88ab4e5, git diff --check clean

The KUnit run used upstream's script unchanged, loaded through a wrapper that
replaces only its two Ubuntu LLVM 18 path functions (LLVM=1 and Arch's
libclang instead). bindgen is 0.72.1 rather than the 0.71.1 CI pins, because
the kernel's rustavailable check warns that bindgen before 0.72.1 is broken
with libclang 22 and later.

The host-side harness (three small files: stand-ins for the kernel crate and
the sibling modules, and the end-to-end tests) is not in this pull request. I
can add it under tools/ or post it if it is useful.

The end-to-end test builds a gigalocker image with both roots, four "attach"
lockers, one more locker and a USER-xART record, then replays the create as
XART-SAFETY.md measured it on a J316s (a root write, one new session record,
one rewrite of an attach locker) followed by a match, a reboot, and a boot
without the parameter. It checks every reply status and what is left in the
store and in the list.

Not tested

  • Hardware. No Mac has run this. In particular no cold-boot Mac, which is
    the only kind it changes.
  • Loading it. The driver was built both built-in (KUnit config) and as a
    module (a shipped kernel's config), but it only ever ran in QEMU, which has
    no Secure Enclave. The new code in sep.rs, sks.rs and diag.rs compiled
    and is pinned by a source-order test, but never executed. CI with ci:build
    would cover the package build and the boot test.
  • Warm-attach Macs. Their path is meant to be unchanged, and the existing
    tests plus one end-to-end test say so, but sks.rs now always asks the
    guard for the window instead of checking the bootstrap itself.
  • macOS. Whether macOS Touch ID and keychain survive Linux rewriting the
    pinned locker.

Assumptions the pin makes, each of which fails closed if wrong:

  1. The record the create rewrites is kind 4. The refusals logged on J316s and
    J314s name kind 4; the ledger doesn't give the kind. A kind-3 record is
    refused and the create fails as today.
  2. The enclave reads that locker before it rewrites it.
  3. A match rewrites only records on the list and the pinned locker. If it
    rewrites another record from before Linux, the verify is refused and the
    log shows both tags.
  4. The locker keeps its session id across macOS boots. If not, the new locker
    is refused, and recovery is a Touch ID reset with the list removed.
  5. The first existing locker the create rewrites is the shared one. On a
    fresh install that macOS has not booted since, it could be the pending
    locker from "Fresh installs" in XART-SAFETY.md instead; the pin then goes
    to the wrong locker and the create fails. Booting macOS once before the
    first setup avoids it, and XART-SAFETY.md now says so.
  6. The enclave repeats its attach reads whenever the driver probes. After a
    driver reload without an enclave restart the pinned locker counts as
    unread and is refused until a reboot.

A lower-risk way to get M1 evidence

Assumptions 1 to 3 and 5 could be settled without anyone running the new
mode, from a record of what the enclave asks for on a cold-boot Mac that
already uses Touch ID with xart_guard=0. No such record has been posted, and
xarm_trace=1 cannot supply one today: it logs each request's opcode, length
and status, but not which record it names. A trace line that added the kind
and the same CRC-32 tag would change nothing the enclave may do, and a log of
one attach, one keybag creation and one match could then be replayed against
the guard in the host harness. That change is not in this patch; I can send it
separately if it is wanted.

What a hardware run would need to show

On a cold-boot Mac whose macOS data is backed up, that has booted macOS at
least once since Linux was installed, starting with no Linux keybag and no
/var/lib/aurora-sep-xart-owned.bin, with
options apple_sep xart_guard_pin=1 and the default xart_guard:

  1. First boot: pinned the existing SEP-xART locker ... (tag X),
    sks: identity keybag provisioned, xart_guard_refusals 0, matching
    unverified.
  2. Enrol, then verify with the enrolled finger and another one. Refusals stay
    0. If a verify is refused, the two tags and "read / had not read" are the
    result to report.
  3. Reboot: Touch ID: restored N, verify again.
  4. Boot macOS: bioutil -c unchanged, Touch ID unlock, login keychain
    unlocked. Then back in Linux: restored, verify.
  5. Remove the parameter and boot: the pinned locker is refused again, and
    nothing else changes.

The risk on that Mac is the one XART-SAFETY.md already states for
xart_guard=0: if macOS rejects the rewritten locker, FileVault volumes may
not unlock and recovery is a DFU restore.

Merge danger

Door: two-way. Default 0 is the current behaviour for every Mac. Reverting
leaves at most a marker and a pin entry in the list, which the old code
ignores as one consumed window and one unreadable entry.

Blast radius: cold-boot Macs whose owner sets xart_guard_pin=1. For
everyone else: one extra call per OP_SESSION_READ that returns at once, and
sks.rs asking the guard for the window on every profile.

Files

  • drivers/soc/apple/xart_guard.rs: Setup, the pin entry, the pinned
    allowance, the read set, guarded_setup, tests.
  • drivers/soc/apple/xart_store.rs, xarm.rs: pass the setup rule in, report
    enclave reads to the guard.
  • drivers/soc/apple/sep.rs: the xart_guard_pin parameter.
  • drivers/soc/apple/sks.rs: let the guard decide whether the create gets a
    window; tell diag when it does.
  • drivers/soc/apple/diag.rs, diag_shim.c, shim.h: guarded_setup as a
    fact behind matching; sep_diag_set_matching().
  • Documentation/ABI/testing/sysfs-driver-apple-sep,
    tools/aurora-sep/XART-SAFETY.md, aurora-sep-ready (one message),
    PKGBUILD (the two checksums), tests/test_diag_sensor.py (three cases
    and a source-order test of the create).

🤖 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>
@matthetherington

matthetherington commented Nov 16, 2026 •

Copy link
Copy Markdown

Thanks for documenting the unknowns explicitly. I have a J316C/T6001 (16-inch
M1 Max) on Fedora Asahi Remix 45, kernel
7.2.12-402.asahi.fc45.aarch64+16k, m1n1 v1.9.9, boot-reported OS firmware
13.5 and system firmware 26.6.2. SEP is currently disabled here; no Linux keybag
provisioning or fingerprint matching has been performed yet.
This is not a hardware test or evidence for macOS safety.

An AI-assisted, hardware-free review of head
5d5030051538de66dcb92de1d15f3f2d88c15e0c reproduced two policy edge cases in
the actual xart_guard.rs, using std/kernel adapters and in-memory files.
All 39 original guard tests pass in that harness; three added restrictive
regression tests fail:

  1. Failed list load retains a parsed pin. A list contains a valid setup
    marker and pin, then read_exact() returns injected EIO on the next entry.
    Guard::new() leaves the list unavailable, but retains the pin parsed by
    load(). After note_read() for that existing locker, check(key, true)
    returns Ok(()) despite list_loaded() == false. pinned_allows() does not
    require a successfully loaded list. Could loading commit authorization
    state only on complete success, or clear it on failure? The inherited
    partial loading of owned also seems worth inspecting.

  2. A saved pin absent at probe can become Linux-owned. With a valid saved
    marker/pin but the pinned key absent from the current existing set, a
    subsequent write to that same key takes the generic Verdict::Adopt path.
    It gains an ordinary owned entry even under Setup::Refuse, with no enclave
    read or setup window. In a separate Setup::Pin case, recreation followed
    by deletion is allowed. That seems inconsistent with “never listed as
    Linux's / never deleted.” Could the saved pinned key be classified before
    ordinary adoption, including when missing at probe?

The second case is a synthetic defensive-policy input, not an observation
that firmware reuses a disappeared locker's UUID; it should not be confused
with proof of your macOS/new-UUID assumption failing. The first also uses an
injected I/O error, not an observed Mac failure. These tests exercise guard
authorization only, not real APFS I/O or the SEP.

The accompanying report/package contains the exact extra Rust tests, small
host adapters, pinned public sources/hashes and full output. No driver,
firmware, SEP device, keybag, enrollment or match operation was run, and no
boot configuration or real xART state was changed.

I cannot provide the useful attach/create/match locker trace from this setup
without crossing into the operations I am avoiding. Would you publish your
three-file host/end-to-end harness so these cases and future trace replays can
be independently reproduced off-device?

J316C-PR486-safe-report-2026-11-16.zip

malik-na added a commit to omacom/omarchy-mac-pkgs that referenced this pull request Nov 19, 2026
touchid-options now gives the J313 xart_guard_pin=1 (omacom/linux-aurora#486)
in place of xart_guard=0. On the J313 the first setup rewrites three
pre-Linux kind-4 lockers, two at the keybag's COPY_KEYBAG and one at the first
activation's LOAD_KEYBAG; with the window held through the first activation
and room for three pins, setup, enrol, match and a reboot restore pass with
xart_guard_refusals 0, and the guard keeps every other macOS record. #486 as
posted pins one locker around CREATE_KEYBAG only and fails on the J313; the
changes it needs are reported there.

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

Copy link
Copy Markdown
Member

I ran this on a cold-boot Mac: a MacBook Air M1 (J313) with macOS 13.5 firmware, xart_guard_pin=1 at the default level 1, no keybag and no list. As posted, provisioning fails there:

  • (a) The rewrite comes later than the create. The pre-Linux lockers aren't rewritten during CREATE_KEYBAG. Two are rewritten by the COPY_KEYBAG that follows it, and one by the first activation's LOAD_KEYBAG.
  • (b) It's three lockers, not one. All three were read since probe, and all three were present before Linux's first xART write.

With the window held through the first activation and up to three pins, it works:

  • Setup: provisioned, enrolled, 3 of 3 matches, with xart_guard_refusals 0.
  • After a reboot: the enrolment was restored, 2 of 2 matches, and 15 of 16 session records still protected.
  • macOS: the owner reports macOS Touch ID still works afterwards.

The logs, the evidence that the three lockers are macOS's, and the two commits are in #506. It's stacked on this PR's commit, which it keeps unchanged with your authorship. Fold them in here if you prefer.

One more finding: after the guard refuses one of these rewrites mid-request, the enclave answers nothing more that boot.

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 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>
Signed-off-by: Naeem Malik <malik2015naeem@gmail.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>
Signed-off-by: Naeem Malik <malik2015naeem@gmail.com>
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