From 8e7a27096ebba1f33850d106e7a8451380566bba Mon Sep 17 00:00:00 2001
From: Satya Benson <satya@benson.earth>
Date: Mon, 9 Nov 2026 08:35:47 -0500
Subject: [PATCH 1/2] tools/aurora-sep: XART-SAFETY.md: arm --expect before a
 Stage 1 change

The boot policy window covers the first unlock of the identity keybag.
When Touch ID brings the keybag up before any trusted key is unsealed,
its first use under a new policy is the DESIGNATE_KEYBAG in
activate_touchid() instead, and the enclave asks for its one rewrite
there. On a MacBook Air M3 (J613) that offers Touch ID at the login
screen, the first boot of integration/aurora 11eccbed after a change from
a raw m1n1 Stage 1 to a Mach-O one logged, after LOAD_KEYBAG answered:

  xART guard: refused to rewrite kind-4 record <id>, which this Linux install did not create
  sks: DESIGNATE_KEYBAG got no reply after 2037 ms
  sks: DESIGNATE_KEYBAG did not complete; enrolment will refuse
  hwrng: read produced nothing (ETIMEDOUT)

This is what https://github.com/aurora-silicon/linux/issues/1190 reports on a J616s. aurora-sep-policy-change with no
arguments armed the refused record, and the next boot rewrote it and
restored the enrolment.

A planned change does not need the lost boot. Say how to avoid it: arm
--expect before the change, on whatever kernel is running, then make the
first boot afterwards a kernel with the allowance code. A kernel without
that code does not read the allowance; with the guard on it refuses the
rewrite and leaves the allowance for a later boot. On a second Stage 1
change on the same J613, armed this way from a kernel without the
allowance code, Touch ID survived the first boot with no refusal.

Also say that the tool finds nothing to allow on a kernel whose refusal
line has no session id, and that the keybag's first use can be the
designate.

Link: https://github.com/aurora-silicon/linux/issues/1190
Signed-off-by: Satya Benson <satya@benson.earth>
---
 tools/aurora-sep/XART-SAFETY.md           | 61 ++++++++++++++++++++++-
 tools/aurora-sep/aurora-sep-policy-change | 16 ++++--
 2 files changed, 70 insertions(+), 7 deletions(-)

diff --git a/tools/aurora-sep/XART-SAFETY.md b/tools/aurora-sep/XART-SAFETY.md
index d500fe86d0027..c65d968f6a3fb 100644
--- a/tools/aurora-sep/XART-SAFETY.md
+++ b/tools/aurora-sep/XART-SAFETY.md
@@ -135,6 +135,26 @@ The same kernel, under the old policy, unlocked the keybag without any
 session record write. Linux had never created a record there: the guard
 ran from Linux's first boot and its list stayed empty.
 
+Touch ID can use the keybag first instead. When fprintd opens the sensor
+before any trusted key is unsealed (a login screen that offers Touch ID,
+for example), the first use of the keybag under the new policy is the
+`DESIGNATE_KEYBAG` in `activate_touchid` (`sbio.rs`), and the enclave asks
+for the rewrite there, after LOAD_KEYBAG has answered. The guard refuses
+it, and the designate is never answered:
+
+    xART guard: refused to rewrite kind-4 record <id>, which this Linux install did not create
+    sks: DESIGNATE_KEYBAG got no reply after 2037 ms
+    sks: DESIGNATE_KEYBAG did not complete; enrolment will refuse
+    hwrng: read produced nothing (ETIMEDOUT)
+    matching unavailable this boot: ...
+
+Touch ID and the enclave's RNG stay down for that boot, and the refusal
+repeats on every boot until the record is allowed. This was seen on the
+MacBook Air M3 (T8122, J613) on 2026-11-07, after a change from a raw
+m1n1 Stage 1 to a Mach-O one, and on a J616s after every Recovery
+enrolment of a Stage 1 that day (https://github.com/aurora-silicon/linux/issues/1190). The window below opens only for
+the unlock, so this case needs `aurora-sep-policy-change`.
+
 Under an unchanged policy that first unlock rewrites no session record at
 all (every J616s boot before the change). So the driver treats a rewrite
 inside it as the policy change and lets exactly one through, by itself, on
@@ -160,8 +180,12 @@ boot:
   run it with no arguments. It takes the session id from the refusal.
 - Before a planned change, run it with `--expect`. The record cannot be
   named in advance, so the allowance covers the first existing kind-4
-  record the enclave asks to rewrite. The identity unlock is the first
-  thing that asks.
+  record the enclave asks to rewrite. The keybag's first use, Touch ID's
+  designate or the first unlock, is the first thing that asks. See
+  "Changing Stage 1 on purpose" below.
+- On a kernel whose refusal line names no session id (one from before the
+  allowance code), the tool with no arguments finds nothing to allow. Use
+  `--expect` there, and boot a kernel with the allowance code next.
 
 Either way it first copies the whole 6 MiB gigalocker extent, the driver's
 host files and `/var/lib/fprint` to
@@ -174,6 +198,30 @@ log names the record either way. `--status`
 shows what is armed and what this boot refused; `--cancel` removes an
 allowance that was not used yet.
 
+#### Changing Stage 1 on purpose
+
+Arm the allowance before the change, so the first boot under the new
+policy keeps Touch ID:
+
+1. On the Linux install, run `aurora-sep-policy-change --expect` as root.
+   The running kernel only has to load the driver, which logs where the
+   gigalocker is; it need not have the allowance code.
+2. Change Stage 1 (for example, enrol it from 1TR).
+3. Make the first boot afterwards a kernel with the allowance code, the
+   one that reads `/var/lib/aurora-sep-xart-allow-once.bin`. It empties
+   the file at probe and logs "this boot may rewrite the first existing
+   kind-4 record the enclave asks for, once", then "allowed one rewrite of
+   kind-4 record ... for a boot policy change" when the enclave asks.
+   A kernel without that code does not read the file. With the guard on,
+   it refuses the rewrite as above and leaves the allowance for a later
+   boot; with the guard off, it lets the rewrite through without saving
+   the previous value.
+4. Later boots under the same policy need nothing, on either kernel.
+
+If the first boot was the wrong kernel, Touch ID is down for that boot
+only: boot one with the allowance code next, and it uses the allowance
+still in the file.
+
 `aurora-sep-load` recognises a refusal and stops at once with a message
 that points here, instead of retrying for two minutes.
 
@@ -182,6 +230,15 @@ rewrote one kind-4 record and one shared root. The other six kind-4
 records and the kind-3 record kept their revisions, Ryan's enrolled
 finger matched afterwards, and it kept matching across later reboots.
 
+On the J613 (2026-11-07) the tool with no arguments armed the record the
+designate refusal named. The next boot logged "allowed one rewrite of
+kind-4 record ... for a boot policy change", restored the Catacomb and the
+enrolment ("Touch ID: restored 1 enrolled identity/identities; enrolment
+survived reboot"), and a kernel without the allowance code brought Touch
+ID up on later boots. A second Stage 1 change on that Mac (2026-11-08),
+armed beforehand as in "Changing Stage 1 on purpose", kept Touch ID on
+the first boot with no refusal.
+
 The copy of the gigalocker is evidence and a last resort, not an undo:
 writing an old copy back does not roll back the enclave's anti-replay
 counters, and the enclave may refuse it.
diff --git a/tools/aurora-sep/aurora-sep-policy-change b/tools/aurora-sep/aurora-sep-policy-change
index be53a352d92fd..fc9aab126e0d6 100755
--- a/tools/aurora-sep/aurora-sep-policy-change
+++ b/tools/aurora-sep/aurora-sep-policy-change
@@ -4,11 +4,12 @@
 
 A new Stage 1, another boot object or a boot mode conversion changes the
 Mac's boot policy for Linux. The first time Linux's identity keybag is
-unlocked under the new policy, the enclave rewrites one session record in
-the shared xART gigalocker. Linux did not create that record, so the
-driver's xART guard refuses the write, the machine ref-key stays down and
-Touch ID is unavailable. The keybag, the ref-key and the enrolled
-fingerprints are all intact: the refused write changed nothing.
+used under the new policy (unlocked, or designated for Touch ID), the
+enclave rewrites one session record in the shared xART gigalocker. Linux
+did not create that record, so the driver's xART guard refuses the write,
+the enclave stops answering and Touch ID is unavailable. The keybag, the
+ref-key and the enrolled fingerprints are all intact: the refused write
+changed nothing.
 
 This lets the enclave make that one write on the next boot:
 
@@ -20,6 +21,11 @@ This lets the enclave make that one write on the next boot:
   aurora-sep-policy-change --status   what is armed, and this boot's refusals
   aurora-sep-policy-change --cancel   remove an allowance not used yet
 
+Only a kernel with the xART guard's allowance code reads the allowance.
+After a planned change, make the first boot such a kernel; any other
+kernel leaves the allowance for a later boot. See "Changing Stage 1 on
+purpose" in XART-SAFETY.md.
+
 Before it arms anything it backs up the whole gigalocker extent, the
 driver's host files and the fingerprint store to
 /var/lib/aurora-rollback/sep-policy-change-<time>/, with SHA256SUMS.

From 0f3fda00623bd77b6b0a28e9805ca8f16fda0e94 Mon Sep 17 00:00:00 2001
From: Satya Benson <satya@benson.earth>
Date: Mon, 9 Nov 2026 08:37:38 -0500
Subject: [PATCH 2/2] soc: apple: sep: open the boot policy window for Touch
 ID's designate

After a boot policy change the enclave rewrites one existing kind-4
session record the first time Linux's identity keybag is used under the
new policy. Commit e89d4a291bee ("soc: apple: sep: let a boot policy
change update its xART record") lets that rewrite through in a window
around the first unlock, CHANGE_LOCK_STATE in refkey.rs. When Touch ID
comes up before any trusted key is unsealed, the keybag's first use is
the DESIGNATE_KEYBAG in activate_touchid() instead, which runs outside
the window. The guard refuses the rewrite, the designate is never
answered, and Touch ID stays off on every boot until
aurora-sep-policy-change is run.

This happened on a J616s (https://github.com/aurora-silicon/linux/issues/1190) and on a MacBook Air M3 (J613), each
after a Recovery enrolment of a new Stage 1. On both, the refusal comes
after LOAD_KEYBAG has answered and before DESIGNATE_KEYBAG times out:

  xART guard: refused to rewrite kind-4 record <id>, which this Linux install did not create
  sks: DESIGNATE_KEYBAG got no reply after 2037 ms
  sks: DESIGNATE_KEYBAG did not complete; enrolment will refuse

Both use the variant-5 key store, where activate_touchid() is the only
sender of DESIGNATE_KEYBAG.

Run that designate in policy_window() too. The window itself is
unchanged: one per boot, opened by whichever comes first of that
designate and the first unlock of an identity keybag that already
existed, and kept shut by a keybag or ref-key created earlier in the
boot. activate_touchid() designates before it can create the machine
ref-key. Inside the window the guard still lets through one rewrite of
one kind-4 record that existed at probe, never a delete or a shared
root, only once its previous value is saved, and without adding it to
Linux's list.

Under an unchanged policy that designate rewrites no existing record.
The guard is on by default on both Macs, and a refused write there
leaves the designate unanswered, yet every Touch ID boot without a
policy change brings the enrolment up.

A host test checks that activate_touchid() designates a keybag it
recovered, inside the window, before the machine ref-key, and that the
only other designate runs in a ref-key path that holds the window or has
closed it. Run it in the SEP source checks.

Fixes: e89d4a291bee ("soc: apple: sep: let a boot policy change update its xART record")
Link: https://github.com/aurora-silicon/linux/issues/1190
Signed-off-by: Satya Benson <satya@benson.earth>
---
 .github/workflows/sep-source.yml             |   1 +
 drivers/soc/apple/sbio.rs                    |   8 +-
 drivers/soc/apple/xart_guard.rs              |  26 +++--
 tools/aurora-sep/XART-SAFETY.md              |  23 ++--
 tools/aurora-sep/tests/test_policy_window.py | 109 +++++++++++++++++++
 5 files changed, 144 insertions(+), 23 deletions(-)
 create mode 100644 tools/aurora-sep/tests/test_policy_window.py

diff --git a/.github/workflows/sep-source.yml b/.github/workflows/sep-source.yml
index 51ce8828d55ab..6c90e5675c51f 100644
--- a/.github/workflows/sep-source.yml
+++ b/.github/workflows/sep-source.yml
@@ -41,6 +41,7 @@ jobs:
           python3 -m unittest tools/aurora-sep/tests/test_orphan_delete.py -v
           python3 -m unittest tools/aurora-sep/tests/test_enrol_admission.py -v
           python3 -m unittest tools/aurora-sep/tests/test_owner_preparation.py -v
+          python3 -m unittest tools/aurora-sep/tests/test_policy_window.py -v
           python3 -m unittest discover -s tools/aurora-sep/tests -p test_packaging.py -v
 
   rust-build:
diff --git a/drivers/soc/apple/sbio.rs b/drivers/soc/apple/sbio.rs
index 8d977de6a1cda..2c40415481287 100644
--- a/drivers/soc/apple/sbio.rs
+++ b/drivers/soc/apple/sbio.rs
@@ -2388,7 +2388,13 @@ impl SepData {
             EIO
         })?;
         diag::keybag(diag::Keybag::Present);
-        self.sks_designate_user_keybag(handle, stored.secret());
+        // When Touch ID comes up before a trusted key is unsealed, this is
+        // the keybag's first use this boot, and after a boot policy change
+        // the enclave rewrites one session record here; see
+        // crate::xart_guard.
+        crate::xart_guard::policy_window(|| {
+            self.sks_designate_user_keybag(handle, stored.secret())
+        });
         self.sks_machine_refkey(handle, stored.secret());
         let prepared = self.cold_match_continue(handle, uuid, stored.uuid_provenance());
         self.ensure_restored_after(prepared);
diff --git a/drivers/soc/apple/xart_guard.rs b/drivers/soc/apple/xart_guard.rs
index 5fe73719e3e33..f14a40e150ca2 100644
--- a/drivers/soc/apple/xart_guard.rs
+++ b/drivers/soc/apple/xart_guard.rs
@@ -37,14 +37,15 @@
 //!
 //! A boot policy change (a new Stage 1, a different boot object) makes the
 //! enclave rewrite one existing session record the first time Linux's
-//! identity keybag is unlocked under the new policy. Linux did not create
-//! that record. On a boot under an unchanged policy that unlock rewrites no
-//! session record at all, so a rewrite inside it is the sign of a policy
+//! identity keybag is used under the new policy: its first unlock, or
+//! Touch ID's `DESIGNATE_KEYBAG` when that comes first. Linux did not create
+//! that record. On a boot under an unchanged policy neither rewrites an
+//! existing session record, so a rewrite inside them is the sign of a policy
 //! change. The guard lets exactly one kind-4 rewrite through in that window
-//! ([`policy_window`]): the first unlock of an identity keybag that already
-//! existed, at most once per boot, never a delete, and only once the
-//! record's previous value is saved in a host file ([`PREVIOUS_PATH`]).
-//! The record is not added to Linux's list.
+//! ([`policy_window`]): the first unlock or designate of an identity keybag
+//! that already existed, at most once per boot, never a delete, and only
+//! once the record's previous value is saved in a host file
+//! ([`PREVIOUS_PATH`]). The record is not added to Linux's list.
 //!
 //! For a policy change the window did not cover, `aurora-sep-policy-change`
 //! backs up the gigalocker and leaves a one-time allowance in a host file
@@ -122,9 +123,9 @@ fn with_window<T>(why: Rewrite, f: impl FnOnce() -> T) -> T {
     result
 }
 
-/// Runs `unlock`, the unlock of an identity keybag that already existed,
-/// with the boot policy window open if it is this boot's first. Later
-/// unlocks run with it closed.
+/// Runs `unlock`, the unlock or Touch ID designate of an identity keybag
+/// that already existed, with the boot policy window open if it is this
+/// boot's first. Later ones run with it closed.
 pub(crate) fn policy_window<T>(unlock: impl FnOnce() -> T) -> T {
     with_window(Rewrite::PolicyChange, unlock)
 }
@@ -326,8 +327,9 @@ pub(crate) enum Allowance {
     Record(Key),
     /// The first existing record of this kind the enclave asks to rewrite.
     /// An installer that changes the boot policy cannot know the record's
-    /// session id beforehand; the first identity unlock under the new policy
-    /// comes before anything else can rewrite a session record.
+    /// session id beforehand; the keybag's first use under the new policy
+    /// (an unlock or Touch ID's designate) comes before anything else can
+    /// rewrite a session record.
     FirstOfKind(u8),
 }
 
diff --git a/tools/aurora-sep/XART-SAFETY.md b/tools/aurora-sep/XART-SAFETY.md
index c65d968f6a3fb..362612e0dff79 100644
--- a/tools/aurora-sep/XART-SAFETY.md
+++ b/tools/aurora-sep/XART-SAFETY.md
@@ -152,16 +152,19 @@ Touch ID and the enclave's RNG stay down for that boot, and the refusal
 repeats on every boot until the record is allowed. This was seen on the
 MacBook Air M3 (T8122, J613) on 2026-11-07, after a change from a raw
 m1n1 Stage 1 to a Mach-O one, and on a J616s after every Recovery
-enrolment of a Stage 1 that day (https://github.com/aurora-silicon/linux/issues/1190). The window below opens only for
-the unlock, so this case needs `aurora-sep-policy-change`.
-
-Under an unchanged policy that first unlock rewrites no session record at
-all (every J616s boot before the change). So the driver treats a rewrite
-inside it as the policy change and lets exactly one through, by itself, on
-the first boot after the change:
-
-- only during the first unlock of an identity keybag that already existed,
-  once per boot; a keybag or ref-key created this boot closes the window;
+enrolment of a Stage 1 that day (https://github.com/aurora-silicon/linux/issues/1190). Kernels from before that
+designate ran in the window below need `aurora-sep-policy-change` for this
+case.
+
+Under an unchanged policy neither that first unlock nor that designate
+rewrites an existing session record (every J616s boot before the change,
+and every guarded Touch ID boot on the J613 and J616s). So the driver
+treats a rewrite inside them as the policy change and lets exactly one
+through, by itself, on the first boot after the change:
+
+- only during the first unlock or Touch ID designate of an identity keybag
+  that already existed, whichever comes first, once per boot; a keybag or
+  ref-key created this boot closes the window;
 - only one kind-4 session record, only a rewrite, never a delete or a
   shared root, and the record is not added to Linux's list;
 - only once the record's previous value is durable in
diff --git a/tools/aurora-sep/tests/test_policy_window.py b/tools/aurora-sep/tests/test_policy_window.py
new file mode 100644
index 0000000000000..fda87d68a3f0c
--- /dev/null
+++ b/tools/aurora-sep/tests/test_policy_window.py
@@ -0,0 +1,109 @@
+# SPDX-License-Identifier: GPL-2.0-only
+"""The first use of an existing identity keybag runs in the boot policy window.
+
+After a boot policy change the enclave rewrites one existing session record
+at the keybag's first use: the first unlock, or Touch ID's DESIGNATE_KEYBAG
+when Touch ID comes up first (https://github.com/aurora-silicon/linux/issues/1190). The xART guard lets that rewrite
+through only inside crate::xart_guard::policy_window, so every designate of
+a keybag that already existed has to run in it.
+"""
+from pathlib import Path
+import re
+import unittest
+
+APPLE = Path(__file__).resolve().parents[3] / "drivers/soc/apple"
+DESIGNATE = "sks_designate_user_keybag("
+PREPARE = "sks_prepare_identity_refkey("
+
+
+def function(text, name):
+    """The source of `fn name`, from its signature to its closing brace."""
+    match = re.search(rf"\bfn {name}\b", text)
+    if match is None:
+        raise AssertionError(f"fn {name} not found")
+    opening = text.index("{", match.end())
+    depth, end = 1, opening + 1
+    while depth:
+        depth += (text[end] == "{") - (text[end] == "}")
+        end += 1
+    return text[match.start():end]
+
+
+def functions(text):
+    """(name, start, end) of every fn with a body."""
+    found = []
+    for match in re.finditer(r"\bfn (\w+)\b[^;{]*\{", text):
+        depth, end = 1, match.end()
+        while depth:
+            depth += (text[end] == "{") - (text[end] == "}")
+            end += 1
+        found.append((match.group(1), match.start(), end))
+    return found
+
+
+def calls(name):
+    """(file, caller, caller's source, offset of the call in it) per call."""
+    found = []
+    for path in sorted(APPLE.glob("*.rs")):
+        text = path.read_text()
+        spans = functions(text)
+        for match in re.finditer(re.escape(name), text):
+            if text[max(0, match.start() - 3):match.start()] == "fn ":
+                continue
+            # The innermost function around the call.
+            caller, start, end = max(
+                (s for s in spans if s[1] < match.start() < s[2]),
+                key=lambda s: s[1])
+            found.append((path.name, caller, text[start:end],
+                          match.start() - start))
+    return found
+
+
+def statement(body, at):
+    """The statement around offset `at`: from the previous `;`, `{` or `}`."""
+    start = max(body.rfind(c, 0, at) for c in ";{}")
+    # A closure opened inside the statement does not end it.
+    while body[start] == "{" and body[start - 3:start].strip().endswith("||"):
+        start = max(body.rfind(c, 0, start) for c in ";{}")
+    return body[start + 1:at]
+
+
+class PolicyWindowTests(unittest.TestCase):
+    def setUp(self):
+        self.sbio = (APPLE / "sbio.rs").read_text()
+        self.activate = function(self.sbio, "activate_touchid")
+
+    def test_touchid_designates_inside_the_window(self):
+        at = self.activate.index(DESIGNATE)
+        self.assertIn("crate::xart_guard::policy_window(", statement(self.activate, at))
+
+    def test_touchid_designates_before_the_ref_key_can_be_created(self):
+        # Creating the machine ref-key closes the window for the boot.
+        self.assertLess(self.activate.index(DESIGNATE),
+                        self.activate.index("sks_machine_refkey("))
+
+    def test_touchid_designates_a_keybag_that_already_existed(self):
+        recovered = self.activate.index("sks_recover(&stored)")
+        self.assertLess(recovered, self.activate.index(DESIGNATE))
+        self.assertNotIn("sks_provision_identity_keybag(", self.activate)
+
+    def test_no_other_path_designates_outside_a_window(self):
+        # A new designate of an existing keybag needs the window too; add it
+        # here once it runs in one.
+        sites = {(f, outer) for f, outer, _body, _at in calls(DESIGNATE)}
+        self.assertEqual(sites, {("sbio.rs", "activate_touchid"),
+                                 ("refkey.rs", "sks_prepare_identity_refkey")})
+        # The ref-key path designates inside its own unlock's window, or
+        # after a ref-key create has closed the window for the boot.
+        callers = calls(PREPARE)
+        self.assertTrue(callers)
+        for f, outer, body, at in callers:
+            with self.subTest(caller=outer):
+                before = body[:at]
+                self.assertTrue("crate::xart_guard::policy_window(" in before
+                                or "crate::xart_guard::close_policy_window(" in before,
+                                f"{f}: {outer}")
+
+
+if __name__ == "__main__":
+    unittest.main()