From 5d5030051538de66dcb92de1d15f3f2d88c15e0c Mon Sep 17 00:00:00 2001 From: Poul Guo Skov <80295985+poulguoskov@users.noreply.github.com> Date: Sun, 15 Nov 2026 23:30:26 +0100 Subject: [PATCH] soc: apple: sep: Let a cold-boot Mac's owner pin the one shared xART 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 --- .../ABI/testing/sysfs-driver-apple-sep | 26 +- drivers/soc/apple/diag.rs | 18 +- drivers/soc/apple/diag_shim.c | 17 + drivers/soc/apple/profile.rs | 3 +- drivers/soc/apple/sep.rs | 22 +- drivers/soc/apple/shim.h | 1 + drivers/soc/apple/sks.rs | 33 +- drivers/soc/apple/xarm.rs | 4 + drivers/soc/apple/xart_guard.rs | 630 +++++++++++++++++- drivers/soc/apple/xart_store.rs | 22 +- tools/aurora-sep/XART-SAFETY.md | 114 +++- tools/aurora-sep/aurora-sep-ready | 2 +- .../packaging/arch/aurora-sep/PKGBUILD | 4 +- tools/aurora-sep/tests/test_diag_sensor.py | 33 +- 14 files changed, 858 insertions(+), 71 deletions(-) diff --git a/Documentation/ABI/testing/sysfs-driver-apple-sep b/Documentation/ABI/testing/sysfs-driver-apple-sep index b11ef8f266150c..aa9b803c0e6090 100644 --- a/Documentation/ABI/testing/sysfs-driver-apple-sep +++ b/Documentation/ABI/testing/sysfs-driver-apple-sep @@ -341,10 +341,13 @@ Description: ========== ========================================== usable xART writes are enabled and no guard runs. - unverified A guard runs with its list loaded on a - warm-attach Mac (boot "warm") and has refused - nothing yet. Whether every record a match - rewrites is on the list is not known until a + unverified A guard runs with its list loaded and has + refused nothing yet, on a warm-attach Mac + (boot "warm") or on a cold-boot Mac (boot + "cold") whose keybag was created under the + guard with xart_guard_pin=1. Whether every + record a match rewrites is on the list, or + is the pinned locker, is not known until a match is tried. blocked A match's write is refused or known to be: xART writes are disabled (xart "disabled"), @@ -352,15 +355,18 @@ Description: (xart_guard_refusals above 0), the guard has no list (xart_guard_list "unavailable"), or a guard runs on a - cold-boot Mac (boot "cold"). On a cold-boot - Mac, creating the keybag needs xart_guard=0, - so the records a match rewrites are not on - the list. + cold-boot Mac (boot "cold") whose keybag + was not created under it. Creating the + keybag there needs xart_guard=0, which + leaves the records a match rewrites off the + list, or xart_guard_pin=1. ========== ========================================== For the guard cases the documented opt-out is xart_guard=0, which lets the enclave rewrite session records that another OS on the Mac may have created; see tools/aurora-sep/XART-SAFETY.md. During a boot the value - can only move from "unverified" to "blocked", once the guard - refuses a write. + moves from "unverified" to "blocked" once the guard refuses + a write. On a cold-boot Mac with xart_guard_pin=1 it also + moves from "blocked" to "unverified" when the first keybag + creation is sent under the guard, and nowhere else. diff --git a/drivers/soc/apple/diag.rs b/drivers/soc/apple/diag.rs index 288c92a3cd94c3..a83cc4c1434359 100644 --- a/drivers/soc/apple/diag.rs +++ b/drivers/soc/apple/diag.rs @@ -41,6 +41,7 @@ extern "C" { fn sep_diag_set_sensor_attach(state: c_int); fn sep_diag_set_restore(state: c_int); fn sep_diag_set_xart_guard(level: c_uint, list_loaded: bool, matching: c_int); + fn sep_diag_set_matching(matching: c_int); fn sep_diag_xart_guard_refused(matching: c_int); fn sep_diag_bringup_ended(); } @@ -70,12 +71,15 @@ pub(crate) enum Restore { /// group goes away when the driver unbinds. /// /// `guard` is the xART guard as the store opened it: its effective level and -/// whether Linux's list loaded, or `None` when no guard runs. +/// whether Linux's list loaded, or `None` when no guard runs. `guarded_setup` +/// is whether that list says this install's first keybag creation was sent +/// under the guard. pub(crate) fn register( dev: &device::Device, profile: &profile::PlatformProfile, xart_writable: bool, guard: Option<(u8, bool)>, + guarded_setup: bool, ) -> Result { // Exhaustive, so a new bootstrap or key store fails to build here until // the ABI has a value for it. @@ -91,6 +95,7 @@ pub(crate) fn register( // Probe runs before the guard can refuse anything. XART_WRITABLE.store(xart_writable, Relaxed); COLD.store(cold, Relaxed); + GUARDED_SETUP.store(guarded_setup, Relaxed); let (level, list_loaded) = guard.unwrap_or((0, false)); GUARD_LEVEL.store(u32::from(level), Relaxed); GUARD_LIST.store(list_loaded, Relaxed); @@ -178,6 +183,7 @@ pub(crate) fn restore(state: Restore) { static XART_WRITABLE: Atomic = Atomic::new(false); static COLD: Atomic = Atomic::new(false); +static GUARDED_SETUP: Atomic = Atomic::new(false); static GUARD_LEVEL: Atomic = Atomic::new(0); static GUARD_LIST: Atomic = Atomic::new(false); static REFUSALS: Atomic = Atomic::new(0); @@ -189,6 +195,7 @@ fn matching() -> crate::xart_guard::Matching { MatchFacts { xart_writable: XART_WRITABLE.load(Relaxed), cold: COLD.load(Relaxed), + guarded_setup: GUARDED_SETUP.load(Relaxed), guard: (level != 0).then(|| { ( u8::try_from(level).unwrap_or(u8::MAX), @@ -200,6 +207,15 @@ fn matching() -> crate::xart_guard::Matching { .matching() } +/// The xART guard opened this install's first-setup window and recorded it in +/// its list, so the keybag creation about to be sent runs under the guard. +pub(crate) fn xart_guard_setup_recorded() { + GUARDED_SETUP.store(true, Relaxed); + // SAFETY: no preconditions; stores one word. The refusals counted since + // probe stand, which `sep_diag_set_xart_guard` would clear. + unsafe { sep_diag_set_matching(matching() as c_int) }; +} + /// The xART guard refused one of the enclave's writes or deletes. pub(crate) fn xart_guard_refused() { REFUSALS.fetch_add(1, Relaxed); diff --git a/drivers/soc/apple/diag_shim.c b/drivers/soc/apple/diag_shim.c index 5c54d5d8410b32..af3e4544e8f7ef 100644 --- a/drivers/soc/apple/diag_shim.c +++ b/drivers/soc/apple/diag_shim.c @@ -487,6 +487,23 @@ void sep_diag_set_xart_guard(unsigned int level, bool list_loaded, atomic_set(&sep_diag.matching, matching); } +/* + * After probe, when a fact matching is derived from changes without a + * refusal: the guard recorded this install's first-setup window. The level, + * the list and the refusals counted so far stand. + * + * The caller derived matching before this call, and a refusal may have + * landed since. A refusal always leaves "blocked", so the count is read + * after the store: either this sees the refusal and restores "blocked", or + * the refusal's own store comes later. + */ +void sep_diag_set_matching(int matching) +{ + atomic_set(&sep_diag.matching, matching); + if (atomic_read(&sep_diag.xart_refusals)) + atomic_set(&sep_diag.matching, SEP_DIAG_MATCHING_BLOCKED); +} + /* With matching as the refusal leaves it. */ void sep_diag_xart_guard_refused(int matching) { diff --git a/drivers/soc/apple/profile.rs b/drivers/soc/apple/profile.rs index 6803c1464652e0..efd31c7264591a 100644 --- a/drivers/soc/apple/profile.rs +++ b/drivers/soc/apple/profile.rs @@ -260,7 +260,8 @@ pub(crate) const T6000: PlatformProfile = PlatformProfile { nonce_session: false, // As T8103. On J316s, creating the identity keybag also rewrites a // session record that predates Linux. The guard refuses that, so the - // keybag can only be created there with xart_guard=0. + // keybag can only be created there with xart_guard=0, or under the + // guard with xart_guard_pin=1, which pins that one record. xart_guard: 1, }; diff --git a/drivers/soc/apple/sep.rs b/drivers/soc/apple/sep.rs index 87b90a7d986ee6..26a3be028cc5a6 100644 --- a/drivers/soc/apple/sep.rs +++ b/drivers/soc/apple/sep.rs @@ -849,10 +849,15 @@ impl SepData { let xart_start = *module_parameters::xart_start_sector.value(); let xart_guard = xart_guard::level(*module_parameters::xart_guard.value(), profile.xart_guard); + let cold = match profile.bootstrap { + profile::Bootstrap::Boot => true, + profile::Bootstrap::WarmRegister => false, + }; + let xart_setup = xart_guard::setup(cold, *module_parameters::xart_guard_pin.value()); let store = match xart_store::Store::open_owner(xart_writes, xart_start) { Ok(mut store) => { match xart_guard { - Some(level) if store.writes_enabled() => store.set_guard(level)?, + Some(level) if store.writes_enabled() => store.set_guard(level, xart_setup)?, None if store.writes_enabled() => dev_info!( dev, "xART guard off: the enclave may rewrite any session record\n" @@ -2656,7 +2661,16 @@ impl platform::Driver for SepDriver { // As soon as the fixed facts are known, so a tool can watch the attach // from "pending" on. Diagnostics are not worth failing the probe for. let guard = data.with_store(|store| store.guard_state()).flatten(); - if let Err(e) = diag::register(dev, data.profile, data.xart_writable(), guard) { + let guarded_setup = data + .with_store(|store| store.guarded_setup()) + .unwrap_or(false); + if let Err(e) = diag::register( + dev, + data.profile, + data.xart_writable(), + guard, + guarded_setup, + ) { dev_warn!(dev, "diag: could not add the sysfs attributes ({:?})\n", e); } @@ -2752,6 +2766,10 @@ module! { default: -1, description: "-1: the platform's level, 1 on M1, M2 and M3 Macs and 0 on the MacBook Neo; 0: off; 1: refuse the enclave's writes and deletes of xART session records this Linux install did not create; 2: also refuse writes to the shared root records", }, + xart_guard_pin: u8 { + default: 0, + description: "On a Mac that cold-boots its SEP (M1 family) at xart_guard=1: 1 lets the enclave rewrite the one SEP-xART locker from before Linux that this install's first keybag creation rewrites, then and afterwards, while every other record stays guarded; 0: that rewrite is refused", + }, os_uuid_hi: u64 { default: 0, description: "High 64 bits of an explicit xART OS UUID", diff --git a/drivers/soc/apple/shim.h b/drivers/soc/apple/shim.h index 0425bf2cdaa6ed..6ae053f5ac2322 100644 --- a/drivers/soc/apple/shim.h +++ b/drivers/soc/apple/shim.h @@ -191,6 +191,7 @@ void sep_diag_set_sensor_attach(int state); void sep_diag_set_restore(int state); void sep_diag_set_xart_guard(unsigned int level, bool list_loaded, int matching); +void sep_diag_set_matching(int matching); void sep_diag_xart_guard_refused(int matching); void sep_diag_bringup_ended(void); diff --git a/drivers/soc/apple/sks.rs b/drivers/soc/apple/sks.rs index bbc6c723c9cd20..a8384758763f21 100644 --- a/drivers/soc/apple/sks.rs +++ b/drivers/soc/apple/sks.rs @@ -670,24 +670,25 @@ impl SepData { } }; // A cold-boot Mac's create rewrites a pre-Linux record for its own - // reasons (XART-SAFETY.md), so only warm attach gets the window. - let first_setup = if self.profile.bootstrap == profile::Bootstrap::WarmRegister { - match self.with_store(|store| store.open_first_setup()) { - Some(Ok(open)) => open, - None => false, - // Unsent, so the intent is dropped as retryable. - Some(Err(e)) => { - dev_err!( - self.dev, - "sks: cannot record the xART guard's first-setup window ({:?}); not creating the keybag this boot\n", - e - ); - return false; - } + // reasons (XART-SAFETY.md), so the guard gives it a window only under + // xart_guard_pin, and then pins that record. + let first_setup = match self.with_store(|store| store.open_first_setup()) { + Some(Ok(open)) => open, + None => false, + // Unsent, so the intent is dropped as retryable. + Some(Err(e)) => { + dev_err!( + self.dev, + "sks: cannot record the xART guard's first-setup window ({:?}); not creating the keybag this boot\n", + e + ); + return false; } - } else { - false }; + if first_setup { + // The create is sent under the guard: matching follows. + crate::diag::xart_guard_setup_recorded(); + } intent.sending(); let exchanged = self.sks_exchange(request.name, request.msg, &request.img); if first_setup { diff --git a/drivers/soc/apple/xarm.rs b/drivers/soc/apple/xarm.rs index 3e34b34c8951b0..9e0917602d731a 100644 --- a/drivers/soc/apple/xarm.rs +++ b/drivers/soc/apple/xarm.rs @@ -174,6 +174,10 @@ pub(crate) fn service( }; } inbound[..value.len()].copy_from_slice(&value); + // Only a read that hands the enclave the record counts, + // for the lockers the guard lets it rewrite under + // xart_guard_pin. + store.note_enclave_read(&key); Serviced { reply: Reply::ok(req, value.len() as u16), reply_bytes: value.len(), diff --git a/drivers/soc/apple/xart_guard.rs b/drivers/soc/apple/xart_guard.rs index 6efb2a8609330f..70a06f7fd3d979 100644 --- a/drivers/soc/apple/xart_guard.rs +++ b/drivers/soc/apple/xart_guard.rs @@ -44,6 +44,22 @@ //! nothing identifies that locker as the pending one. It does not list the //! locker as Linux's, and the list records the window as consumed before it //! opens, so no later create on this install gets it again. +//! +//! A cold-boot Mac cannot stay inside the rule. Its `CREATE_KEYBAG` rewrites +//! one session record from before Linux, one of the records the enclave +//! reads at every attach and no single OS's (seen on a J316s), and a match +//! rewrites session records that existed before it. The guard refuses the +//! first, so such a Mac needs the guard off, which leaves every record open +//! to the enclave. With `xart_guard_pin=1` the owner accepts that one record +//! instead, if it is a SEP-xART locker ([`Setup::Pin`]). The same +//! first-setup window then opens on a cold-boot Mac, and the first existing +//! kind-4 locker the enclave rewrites in it, provided the enclave read that +//! locker since probe, is recorded in the list as pinned before the write +//! lands. From then on the enclave may rewrite the pinned locker on any boot +//! on which the parameter is set and it has read the locker. The locker is +//! never deleted and never listed as Linux's, and every other record from +//! before Linux stays refused. Without the parameter a cold-boot Mac gets no +//! window and its pin is not honoured. use crate::shim::StoreFile; use crate::xart_store::{crc32_ieee, Key}; @@ -61,6 +77,14 @@ const ENTRY_MAGIC: &[u8; 4] = b"AXGO"; const MAX_ENTRIES: usize = 4096; /// Refusals are logged individually up to this count, then only counted. const LOGGED_REFUSALS: usize = 8; +/// Marks a list entry as the pinned locker's. It sits in the first of the +/// three bytes an owned entry keeps zero, so a kernel without pinning reads +/// the entry as unreadable and lists nothing by it. +const ENTRY_PINNED: u8 = 1; +/// SEP-xART lockers the enclave read since probe that a pinning guard +/// remembers. The gigalocker has at most a few hundred slots; a locker past +/// the bound counts as unread. +const MAX_READ: usize = 512; /// What the guard does with one enclave write or delete. #[derive(Clone, Copy, Debug, PartialEq, Eq)] @@ -108,6 +132,37 @@ pub(crate) fn first_setup_allows(level: u8, window: FirstSetup, key: &Key, write level == 1 && window == FirstSetup::Open && write && key.kind == 4 } +/// What an install's first keybag creation may do to a locker from before +/// Linux, which depends on how the platform's enclave boots. +#[derive(Clone, Copy, Debug, PartialEq, Eq)] +pub(crate) enum Setup { + /// Warm attach: commit one pending SEP-xART locker. + Commit, + /// Cold boot: nothing. The create's rewrite is refused. + Refuse, + /// Cold boot with `xart_guard_pin=1`: pin the one SEP-xART locker the + /// create rewrites, which the enclave may then rewrite again. + Pin, +} + +/// The first-setup rule for a platform that cold-boots its enclave (`cold`) +/// or attaches to a running one, with `xart_guard_pin=pin`. The parameter +/// changes nothing on a warm-attach Mac. +pub(crate) fn setup(cold: bool, pin: u8) -> Setup { + match (cold, pin) { + (false, _) => Setup::Commit, + (true, 0) => Setup::Refuse, + (true, _) => Setup::Pin, + } +} + +/// A short tag for one locker in the log, so that a refusal can be compared +/// with the locker this install pinned. It is not the session id, which the +/// log never carries. +fn tag(key: &Key) -> u32 { + crc32_ieee(&key.uuid) +} + /// The guard level for `xart_guard=param` on a platform whose profile /// defaults to `platform`, or `None` for no guard. A negative value takes the /// platform's level; a level above 2 is treated as 2, the strictest. @@ -139,6 +194,9 @@ pub(crate) struct MatchFacts { pub(crate) xart_writable: bool, /// The platform cold-boots its enclave. pub(crate) cold: bool, + /// This install's first keybag creation was sent under the guard, as far + /// as the guard's list says (see [`Guard::guarded_setup`]). + pub(crate) guarded_setup: bool, /// The guard's effective level and whether its list loaded, or `None` /// when no guard runs. pub(crate) guard: Option<(u8, bool)>, @@ -150,19 +208,23 @@ impl MatchFacts { /// A match rewrites session records that existed before it (seen on a /// T6000). It is blocked when xART is read-only, once the guard has /// refused anything, when the guard has no list to allow Linux's records - /// by, and on a cold-boot Mac: creating the keybag there needs the guard - /// off, so the records a match rewrites were never listed. + /// by, and on a cold-boot Mac whose keybag was not created under the + /// guard: creating it there needs the guard off unless the owner set + /// `xart_guard_pin`, and with the guard off the records a match rewrites + /// were never listed. /// /// Nothing else proves an unguarded setup. An empty list in particular /// does not: a guarded keybag creation on an M2 writes no record, and a /// rollback can empty the list. So a guarded warm-attach Mac is - /// unverified until a refusal says otherwise. + /// unverified until a refusal says otherwise, and so is a cold-boot Mac + /// set up under `xart_guard_pin`: which records a match rewrites there + /// has not been established either. pub(crate) fn matching(&self) -> Matching { match self.guard { _ if !self.xart_writable || self.refusals != 0 => Matching::Blocked, None => Matching::Usable, Some((_, false)) => Matching::Blocked, - Some(_) if self.cold => Matching::Blocked, + Some(_) if self.cold && !self.guarded_setup => Matching::Blocked, Some(_) => Matching::Unverified, } } @@ -189,18 +251,46 @@ pub(crate) fn setup_consumed() -> [u8; ENTRY_SIZE] { entry_bytes(0, b"first setup used") } -/// Decodes one list entry; `None` for a torn or foreign one. -pub(crate) fn decode(entry: &[u8]) -> Option { - if entry.len() != ENTRY_SIZE || &entry[..4] != ENTRY_MAGIC || entry[5..8] != [0; 3] { +/// Encodes the entry that pins `key`, a SEP-xART locker from before Linux. +/// [`decode`] reads it as no record, so it lists nothing as Linux's. +pub(crate) fn encode_pin(key: &Key) -> [u8; ENTRY_SIZE] { + let mut entry = entry_bytes(key.kind, &key.uuid); + entry[5] = ENTRY_PINNED; + let crc = crc32_ieee(&entry[..24]); + entry[24..28].copy_from_slice(&crc.to_le_bytes()); + entry +} + +/// The kind, the three bytes after it and the session id of a whole entry +/// with the list's magic and a good CRC; `None` for a torn or foreign one. +fn parse(entry: &[u8]) -> Option<(u8, [u8; 3], [u8; 16])> { + if entry.len() != ENTRY_SIZE || &entry[..4] != ENTRY_MAGIC { return None; } let crc = u32::from_le_bytes([entry[24], entry[25], entry[26], entry[27]]); - if crc != crc32_ieee(&entry[..24]) || !(3..=4).contains(&entry[4]) { + if crc != crc32_ieee(&entry[..24]) { return None; } let mut uuid = [0u8; 16]; uuid.copy_from_slice(&entry[8..24]); - Some(Key::new(entry[4], uuid)) + Some((entry[4], [entry[5], entry[6], entry[7]], uuid)) +} + +/// Decodes a pin entry; `None` for anything else, a pin of a record that is +/// not a SEP-xART locker included. +pub(crate) fn decode_pin(entry: &[u8]) -> Option { + match parse(entry)? { + (4, [ENTRY_PINNED, 0, 0], uuid) => Some(Key::new(4, uuid)), + _ => None, + } +} + +/// Decodes one list entry; `None` for a torn or foreign one. +pub(crate) fn decode(entry: &[u8]) -> Option { + match parse(entry)? { + (kind @ 3..=4, [0, 0, 0], uuid) => Some(Key::new(kind, uuid)), + _ => None, + } } /// The file that holds Linux's list: the host file, or memory in the tests. @@ -246,24 +336,39 @@ pub(crate) struct Guard { existed: KVec, refused: usize, first_setup: FirstSetup, + /// What the first-setup window may do on this platform. + setup: Setup, + /// The list holds the first-setup window's record, from this boot or an + /// earlier one. + setup_recorded: bool, + /// The SEP-xART locker from before Linux that the list pins. It is + /// honoured only under [`Setup::Pin`]. + pinned: Option, + /// Rewrites of the pinned locker let through since probe. + pinned_writes: usize, + /// The SEP-xART lockers the enclave read since probe, kept only under + /// [`Setup::Pin`]. + read: KVec, } impl Guard { /// Opens Linux's list in the host file and records which keys `existing` - /// holds now. Never fails: a list that cannot be read protects every - /// existing record. - pub(crate) fn open(level: u8, existing: KVec) -> Guard { - Guard::with_file( + /// holds now. `setup` is the platform's first-setup rule. Never fails: a + /// list that cannot be read protects every existing record. + pub(crate) fn open(level: u8, existing: KVec, setup: Setup) -> Guard { + Guard::new( level, existing, StoreFile::open_host(OWNED_PATH).map(|(file, _created)| file), + setup, ) } } impl Guard { - /// As [`Guard::open`], with the list in `file`. - pub(crate) fn with_file(level: u8, existing: KVec, file: Result) -> Guard { + /// As [`Guard::open`], with the list in `file`. There is no default + /// first-setup rule: every guard is told its platform's. + fn new(level: u8, existing: KVec, file: Result, setup: Setup) -> Guard { let mut guard = Guard { level, file: None, @@ -272,6 +377,11 @@ impl Guard { existed: existing, refused: 0, first_setup: FirstSetup::Closed, + setup, + setup_recorded: false, + pinned: None, + pinned_writes: 0, + read: KVec::new(), }; // A list created this boot (or by a crashed one) is only safe to adopt // into once its name is durable: fsync() of the file alone does not @@ -313,9 +423,46 @@ impl Guard { sessions - own, roots ); + guard.announce_pin(); guard } + /// Whether the list loaded and holds no entry, torn ones included: what a + /// first-setup window needs. + fn list_empty(&self) -> bool { + self.file + .as_ref() + .is_some_and(|file| file.size().is_ok_and(|size| size == 0)) + } + + /// Says what `xart_guard_pin` and a pinned locker come to on this boot. + fn announce_pin(&self) { + let honoured = self.setup == Setup::Pin && self.level == 1; + match (honoured, self.pinned) { + (true, Some(key)) => pr_info!( + "xART guard: xart_guard_pin is set: the enclave may rewrite this install's pinned SEP-xART locker (tag {:08x}) once it has read it\n", + tag(&key) + ), + (true, None) if self.list_empty() => pr_info!( + "xART guard: xart_guard_pin is set and no locker is pinned: this install's first keybag creation may pin one\n" + ), + // The window that pins a locker opens only on an empty list, so + // an earlier guarded attempt on this install shuts it for good. + (true, None) => pr_warn!( + "xART guard: xart_guard_pin is set, but no locker is pinned and the list of Linux's records is not empty or did not load: the first-setup window stays shut and a keybag creation's rewrite is refused. Reset Touch ID with the list removed to set up under xart_guard_pin\n" + ), + (false, Some(key)) => pr_info!( + "xART guard: this install pinned a SEP-xART locker (tag {:08x}), which counts only with xart_guard_pin=1 at level 1: rewrites of it are refused\n", + tag(&key) + ), + (false, None) if self.setup == Setup::Pin => pr_info!( + "xART guard: xart_guard_pin has no effect at level {}\n", + self.level + ), + (false, None) => {} + } + } + fn load(&mut self, file: &F) -> Result<()> { let size = file.size()?; let whole = (size as usize / ENTRY_SIZE).min(MAX_ENTRIES + 1); @@ -329,8 +476,13 @@ impl Guard { match decode(&entry) { Some(key) if !self.owned.contains(&key) => self.owned.push(key, GFP_KERNEL)?, Some(_) => {} - None if entry == setup_consumed() => {} - None => torn += 1, + None if entry == setup_consumed() => self.setup_recorded = true, + None => match decode_pin(&entry) { + // One locker per install: the first-setup window pins it, + // and that window opens once. + Some(key) if self.pinned.is_none() => self.pinned = Some(key), + _ => torn += 1, + }, } } if torn != 0 { @@ -351,14 +503,39 @@ impl Guard { self.file.is_some() } + /// Whether this install's first keybag creation was sent under the guard, + /// as far as the list says: the list loaded and records the first-setup + /// window, on a platform that has one. A cold-boot Mac has one only + /// under `xart_guard_pin`, so without the parameter this is `false` there + /// whatever the list holds. + pub(crate) fn guarded_setup(&self) -> bool { + self.file.is_some() && self.setup_recorded && self.setup != Setup::Refuse + } + + /// Notes that the enclave was handed the record under `key` since probe. + /// Only SEP-xART lockers are kept, and only under [`Setup::Pin`], whose + /// allowances ask for it. A locker that cannot be kept counts as unread, + /// which they refuse. + pub(crate) fn note_read(&mut self, key: &Key) { + if self.setup != Setup::Pin + || key.kind != 4 + || self.read.contains(key) + || self.read.len() >= MAX_READ + { + return; + } + let _ = self.read.push(*key, GFP_KERNEL); + } + /// Opens the first-setup window for one keybag creation, only at level 1 /// on a fresh install: the list loaded and holding no entry, torn ones - /// included. The window is recorded as consumed in the list, durably, - /// before it opens, so it opens at most once per install whatever becomes - /// of the keybag. `Ok(false)` when the install is not eligible; an error, - /// with the window shut, when the record could not be made durable. + /// included. A cold-boot Mac has no window unless the owner set + /// `xart_guard_pin`. The window is recorded as consumed in the list, + /// durably, before it opens, so it opens at most once per install whatever + /// becomes of the keybag. `Ok(false)` when the install is not eligible; an + /// error, with the window shut, when the record could not be made durable. pub(crate) fn open_first_setup(&mut self) -> Result { - if self.level != 1 { + if self.level != 1 || self.setup == Setup::Refuse { return Ok(false); } let Some(file) = self.file.as_ref() else { @@ -375,6 +552,7 @@ impl Guard { file.write_all(0, &setup_consumed())?; file.sync()?; self.end = ENTRY_SIZE as u64; + self.setup_recorded = true; self.first_setup = FirstSetup::Open; Ok(true) } @@ -406,6 +584,37 @@ impl Guard { Ok(()) } + /// Records `key` as this install's pinned locker, durably, before the + /// enclave's rewrite of it is let through. + fn pin(&mut self, key: &Key) -> Result<()> { + let file = self.file.as_ref().ok_or(ENOENT)?; + // As in adopt(): the file's length is what load() accepts. + if usize::try_from(self.end).map_or(true, |end| end / ENTRY_SIZE >= MAX_ENTRIES) { + return Err(ENOSPC); + } + file.write_all(self.end, &encode_pin(key))?; + file.sync()?; + // Only now that the entry is written and flushed. A failed write or + // flush leaves the end unchanged, so the next entry overwrites the + // slot, and a pin that survives there names the locker the owner's + // parameter was about to allow. + self.pinned = Some(*key); + self.end += ENTRY_SIZE as u64; + Ok(()) + } + + /// Whether a request the guard would refuse passes as the enclave's + /// rewrite of this install's pinned locker: under `xart_guard_pin` at + /// level 1, a rewrite (not a delete) of the locker the list pins, once + /// the enclave has read it since probe. + fn pinned_allows(&self, key: &Key, write: bool) -> bool { + self.setup == Setup::Pin + && self.level == 1 + && write + && self.pinned == Some(*key) + && self.read.contains(key) + } + /// Checks one enclave write (`write`) or delete before it reaches the /// gigalocker. An error refuses the request. pub(crate) fn check(&mut self, key: &Key, write: bool) -> Result<()> { @@ -422,7 +631,41 @@ impl Guard { e ) }), - Verdict::Refuse if first_setup_allows(self.level, self.first_setup, key, write) => { + Verdict::Refuse if self.pinned_allows(key, write) => { + self.pinned_writes += 1; + if self.pinned_writes == 1 { + pr_info!( + "xART guard: allowed the enclave to rewrite this install's pinned SEP-xART locker (tag {:08x})\n", + tag(key) + ); + } + Ok(()) + } + // Under xart_guard_pin the window passes only a locker the + // enclave read since probe, and pins it before the write lands. + Verdict::Refuse + if self.setup == Setup::Pin + && first_setup_allows(self.level, self.first_setup, key, write) + && self.read.contains(key) => + { + self.pin(key).inspect_err(|e| { + crate::diag::xart_guard_refused(); + pr_warn!( + "xART guard: could not record the SEP-xART locker to pin ({:?}); refusing to rewrite it\n", + e + ) + })?; + self.first_setup = FirstSetup::Used; + pr_info!( + "xART guard: pinned the existing SEP-xART locker the enclave rewrote during this install's first keybag creation (tag {:08x})\n", + tag(key) + ); + Ok(()) + } + Verdict::Refuse + if self.setup == Setup::Commit + && first_setup_allows(self.level, self.first_setup, key, write) => + { self.first_setup = FirstSetup::Used; pr_info!( "xART guard: allowed the enclave to commit an existing kind-{} locker during this install's first keybag creation\n", @@ -440,6 +683,21 @@ impl Guard { action, key.kind ); + // Under xart_guard_pin, which locker and whether the + // enclave had read it tell the refusals apart: the + // pinned locker before a read, or another one. + if self.setup == Setup::Pin && key.kind == 4 { + let read = if self.read.contains(key) { + "read" + } else { + "had not read" + }; + pr_info!( + "xART guard: the refused locker has tag {:08x}; the enclave {} it this boot\n", + tag(key), + read + ); + } } Err(EPERM) } @@ -453,6 +711,22 @@ mod tests { use super::*; use core::cell::{Cell, RefCell}; + /// The tests' shorthand: a warm-attach Mac's guard, as every guard was + /// before a cold-boot Mac had a rule of its own. The driver itself has no + /// default and always names the rule. + impl Guard { + fn with_file(level: u8, existing: KVec, file: Result) -> Guard { + Guard::new(level, existing, file, Setup::Commit) + } + + /// The same guard on a platform with the rule `setup`. + fn with_setup(mut self, setup: Setup) -> Guard { + self.setup = setup; + self.announce_pin(); + self + } + } + fn session(byte: u8) -> Key { Key::new(4, [byte; 16]) } @@ -466,6 +740,24 @@ mod tests { MatchFacts { xart_writable, cold, + guarded_setup: false, + guard, + refusals, + } + .matching() + } + + /// As [`facts`], on a Mac whose first keybag creation ran under the guard. + fn facts_after_setup( + xart_writable: bool, + cold: bool, + guard: Option<(u8, bool)>, + refusals: u32, + ) -> Matching { + MatchFacts { + xart_writable, + cold, + guarded_setup: true, guard, refusals, } @@ -487,9 +779,36 @@ mod tests { assert_eq!(facts(true, false, Some((2, true)), 0), Matching::Unverified); } + #[test] + fn matching_on_a_cold_boot_mac_follows_its_setup() { + // Set up under the guard with xart_guard_pin: unverified, as a + // warm-attach Mac is. + assert_eq!( + facts_after_setup(true, true, Some((1, true)), 0), + Matching::Unverified + ); + // The fact changes nothing on a warm-attach Mac, or without a guard. + assert_eq!( + facts_after_setup(true, false, Some((1, true)), 0), + Matching::Unverified + ); + assert_eq!(facts_after_setup(true, true, None, 0), Matching::Usable); + // What blocks any Mac still blocks this one. + assert_eq!( + facts_after_setup(true, true, Some((1, true)), 1), + Matching::Blocked + ); + assert_eq!( + facts_after_setup(true, true, Some((1, false)), 0), + Matching::Blocked + ); + assert_eq!(facts_after_setup(false, true, None, 0), Matching::Blocked); + } + #[test] fn matching_is_blocked_where_it_is_known_to_be() { - // A cold-boot M1-family Mac under the default level 1. + // A cold-boot M1-family Mac under the default level 1, not set up + // under the guard: its keybag was created with the guard off. assert_eq!(facts(true, true, Some((1, true)), 0), Matching::Blocked); // No list: nothing that existed at probe is Linux's. assert_eq!(facts(true, false, Some((1, false)), 0), Matching::Blocked); @@ -790,6 +1109,269 @@ mod tests { Ok(()) } + #[test] + fn the_setup_rule_follows_the_boot_and_the_parameter() { + assert_eq!(setup(false, 0), Setup::Commit); + // The parameter changes nothing on a warm-attach Mac. + assert_eq!(setup(false, 1), Setup::Commit); + assert_eq!(setup(true, 0), Setup::Refuse); + assert_eq!(setup(true, 1), Setup::Pin); + assert_eq!(setup(true, u8::MAX), Setup::Pin); + } + + #[test] + fn pin_entries_round_trip_and_list_no_record() { + let locker = session(7); + let pin = encode_pin(&locker); + assert_eq!(decode_pin(&pin), Some(locker)); + // To the list of Linux's records, and to a kernel without pinning, + // a pin is no entry at all. + assert_eq!(decode(&pin), None); + // An owned entry and the consumed marker pin nothing. + assert_eq!(decode_pin(&encode(&locker)), None); + assert_eq!(decode_pin(&setup_consumed()), None); + // Nor does a damaged pin, a short one, or one of a USER-xART locker. + let mut damaged = pin; + damaged[9] ^= 1; + assert_eq!(decode_pin(&damaged), None); + assert_eq!(decode_pin(&pin[..31]), None); + assert_eq!(decode_pin(&encode_pin(&Key::new(3, [7; 16]))), None); + } + + /// The lockers the list in `bytes` pins, entry by entry. + fn pins(bytes: &RefCell>) -> KVec> { + let mut entries = KVec::new(); + for entry in bytes.borrow().chunks(ENTRY_SIZE) { + if entries.push(decode_pin(entry), GFP_KERNEL).is_err() { + break; + } + } + entries + } + + #[test] + fn a_cold_boot_mac_gets_no_window_by_default() -> Result<()> { + let bytes = RefCell::new(KVec::new()); + let locker = session(1); + let mut guard = + Guard::with_file(1, keys(&[locker])?, Ok(mem(&bytes))).with_setup(Setup::Refuse); + // Reads are not kept, the window stays shut and nothing is recorded. + guard.note_read(&locker); + assert!(guard.read.is_empty()); + assert_eq!(guard.open_first_setup(), Ok(false)); + assert_eq!(bytes.borrow().len(), 0); + assert_eq!(guard.check(&locker, true), Err(EPERM)); + assert!(!guard.guarded_setup()); + Ok(()) + } + + #[test] + fn a_pinning_first_create_pins_the_locker_the_enclave_rewrites() -> Result<()> { + let bytes = RefCell::new(KVec::new()); + let shared = session(1); + let unread = session(2); + let other = session(4); + let user = Key::new(3, [3; 16]); + let mut guard = Guard::with_file(1, keys(&[shared, unread, other, user])?, Ok(mem(&bytes))) + .with_setup(Setup::Pin); + guard.note_read(&shared); + guard.note_read(&other); + guard.note_read(&user); + // Reading a locker allows nothing by itself. + assert_eq!(guard.check(&shared, true), Err(EPERM)); + assert_eq!(guard.open_first_setup(), Ok(true)); + // A locker the enclave never read, a delete and a USER-xART locker + // stay refused and do not use the window. + assert_eq!(guard.check(&unread, true), Err(EPERM)); + assert_eq!(guard.check(&shared, false), Err(EPERM)); + assert_eq!(guard.check(&user, true), Err(EPERM)); + assert_eq!(pins(&bytes)[..], [None]); + // The first locker the create rewrites is pinned, after the marker, + // and is not listed as Linux's. + assert_eq!(guard.check(&shared, true), Ok(())); + assert_eq!(pins(&bytes)[..], [None, Some(shared)]); + assert_eq!(listed(&bytes)[..], [None, None]); + // One locker only: another one the enclave read stays refused. + assert_eq!(guard.check(&other, true), Err(EPERM)); + // A record the create adds is listed, as on any Mac. + let created = session(9); + assert_eq!(guard.check(&created, true), Ok(())); + assert_eq!(listed(&bytes)[..], [None, None, Some(created)]); + guard.close_first_setup(); + // After the create the pinned locker stays writable, for a match's + // rewrite, and is still never deleted. + assert_eq!(guard.check(&shared, true), Ok(())); + assert_eq!(guard.check(&shared, true), Ok(())); + assert_eq!(guard.pinned_writes, 2); + assert_eq!(guard.check(&shared, false), Err(EPERM)); + assert_eq!(guard.check(&other, true), Err(EPERM)); + assert_eq!(guard.check(&created, true), Ok(())); + assert_eq!(guard.refused, 7); + assert!(guard.guarded_setup()); + Ok(()) + } + + #[test] + fn a_pinning_window_passes_a_locker_only_once_it_is_read() -> Result<()> { + let bytes = RefCell::new(KVec::new()); + let locker = session(1); + let mut guard = + Guard::with_file(1, keys(&[locker])?, Ok(mem(&bytes))).with_setup(Setup::Pin); + assert_eq!(guard.open_first_setup(), Ok(true)); + assert_eq!(guard.check(&locker, true), Err(EPERM)); + // Read during the create, it passes: the refusal left the window open. + guard.note_read(&locker); + assert_eq!(guard.check(&locker, true), Ok(())); + assert_eq!(guard.pinned, Some(locker)); + Ok(()) + } + + #[test] + fn the_pin_survives_a_reboot_and_needs_the_parameter() -> Result<()> { + let bytes = RefCell::new(KVec::new()); + let shared = session(1); + let other = session(2); + let mut guard = + Guard::with_file(1, keys(&[shared, other])?, Ok(mem(&bytes))).with_setup(Setup::Pin); + guard.note_read(&shared); + assert_eq!(guard.open_first_setup(), Ok(true)); + assert_eq!(guard.check(&shared, true), Ok(())); + guard.close_first_setup(); + drop(guard); + + // The next boot, with the parameter: the pin holds once the enclave + // has read the locker, and the window does not open again. + let mut guard = + Guard::with_file(1, keys(&[shared, other])?, Ok(mem(&bytes))).with_setup(Setup::Pin); + assert_eq!(guard.pinned, Some(shared)); + assert!(guard.guarded_setup()); + assert_eq!(guard.open_first_setup(), Ok(false)); + assert_eq!(guard.check(&shared, true), Err(EPERM)); + guard.note_read(&shared); + guard.note_read(&other); + assert_eq!(guard.check(&shared, true), Ok(())); + assert_eq!(guard.check(&other, true), Err(EPERM)); + drop(guard); + + // Without the parameter the pin is not honoured, and matching is + // blocked as on any cold-boot Mac. + let mut guard = + Guard::with_file(1, keys(&[shared, other])?, Ok(mem(&bytes))).with_setup(Setup::Refuse); + guard.note_read(&shared); + assert_eq!(guard.check(&shared, true), Err(EPERM)); + // Even with the read on record, which note_read() does not keep here. + guard.read.push(shared, GFP_KERNEL)?; + assert_eq!(guard.check(&shared, true), Err(EPERM)); + assert!(!guard.guarded_setup()); + drop(guard); + + // Nor at level 2, which refuses the shared roots as well. + let mut guard = + Guard::with_file(2, keys(&[shared, other])?, Ok(mem(&bytes))).with_setup(Setup::Pin); + guard.note_read(&shared); + assert_eq!(guard.check(&shared, true), Err(EPERM)); + Ok(()) + } + + #[test] + fn a_pin_that_cannot_be_recorded_refuses_the_rewrite() -> Result<()> { + let bytes = RefCell::new(KVec::new()); + let faults = Faults::default(); + let locker = session(1); + let mut guard = Guard::with_file(1, keys(&[locker])?, Ok(faulty(&bytes, &faults))) + .with_setup(Setup::Pin); + guard.note_read(&locker); + assert_eq!(guard.open_first_setup(), Ok(true)); + faults.sync.set(true); + // The flush fails: the rewrite is refused and nothing is pinned. + assert_eq!(guard.check(&locker, true), Err(EIO)); + assert_eq!(guard.pinned, None); + faults.sync.set(false); + // The window is still open, and the same slot takes the pin. + assert_eq!(guard.check(&locker, true), Ok(())); + assert_eq!(pins(&bytes)[..], [None, Some(locker)]); + Ok(()) + } + + #[test] + fn only_the_first_pin_in_the_list_counts() -> Result<()> { + let first = session(1); + let second = session(2); + let mut list = KVec::new(); + list.extend_from_slice(&setup_consumed(), GFP_KERNEL)?; + list.extend_from_slice(&encode_pin(&first), GFP_KERNEL)?; + list.extend_from_slice(&encode_pin(&second), GFP_KERNEL)?; + let bytes = RefCell::new(list); + let mut guard = + Guard::with_file(1, keys(&[first, second])?, Ok(mem(&bytes))).with_setup(Setup::Pin); + guard.note_read(&first); + guard.note_read(&second); + assert_eq!(guard.check(&first, true), Ok(())); + assert_eq!(guard.check(&second, true), Err(EPERM)); + // Neither pin made its locker Linux's. + assert!(guard.owned.is_empty()); + Ok(()) + } + + #[test] + fn only_a_pinning_guard_remembers_reads() -> Result<()> { + let bytes = RefCell::new(KVec::new()); + let locker = session(1); + // A warm-attach Mac's window never asks, so nothing is kept. + let mut guard = Guard::with_file(1, keys(&[locker])?, Ok(mem(&bytes))); + guard.note_read(&locker); + assert!(guard.read.is_empty()); + let mut guard = guard.with_setup(Setup::Pin); + // Not a USER-xART locker or a root. + guard.note_read(&Key::new(3, [3; 16])); + guard.note_read(&Key::root(1)); + assert!(guard.read.is_empty()); + // Once each. + guard.note_read(&locker); + guard.note_read(&locker); + assert_eq!(guard.read.len(), 1); + // Past the bound a locker counts as unread. + for i in 0..MAX_READ { + guard.note_read(&numbered(i)); + } + assert_eq!(guard.read.len(), MAX_READ); + assert!(!guard.read.contains(&numbered(MAX_READ - 1))); + Ok(()) + } + + #[test] + fn a_guarded_setup_is_read_from_the_list() -> Result<()> { + let bytes = RefCell::new(KVec::new()); + let mut guard = Guard::with_file(1, KVec::new(), Ok(mem(&bytes))); + assert!(!guard.guarded_setup()); + assert_eq!(guard.open_first_setup(), Ok(true)); + assert!(guard.guarded_setup()); + guard.close_first_setup(); + drop(guard); + let guard = Guard::with_file(1, KVec::new(), Ok(mem(&bytes))); + assert!(guard.guarded_setup()); + drop(guard); + + // A list of Linux's records alone, as a keybag created before the + // window existed leaves, records no setup. + let own = session(4); + let older = RefCell::new(list_of(&[own])?); + let guard = Guard::with_file(1, keys(&[own])?, Ok(mem(&older))); + assert!(!guard.guarded_setup()); + + // Nor does a list that could not be loaded, or a window whose record + // could not be made durable. + let guard = Guard::>::with_file(1, KVec::new(), Err(ENOENT)); + assert!(!guard.guarded_setup()); + let unsynced = RefCell::new(KVec::new()); + let faults = Faults::default(); + let mut guard = Guard::with_file(1, KVec::new(), Ok(faulty(&unsynced, &faults))); + faults.sync.set(true); + assert_eq!(guard.open_first_setup(), Err(EIO)); + assert!(!guard.guarded_setup()); + Ok(()) + } + #[test] fn a_guard_allows_a_listed_record() -> Result<()> { let own = session(2); diff --git a/drivers/soc/apple/xart_store.rs b/drivers/soc/apple/xart_store.rs index 9901912d8d4ddd..df02c008e24803 100644 --- a/drivers/soc/apple/xart_store.rs +++ b/drivers/soc/apple/xart_store.rs @@ -427,10 +427,11 @@ impl Store { } /// From now on, refuses the enclave's writes to records Linux did not - /// create. See [`crate::xart_guard`]. - pub(crate) fn set_guard(&mut self, level: u8) -> Result<()> { + /// create. `setup` is the platform's first-setup rule. See + /// [`crate::xart_guard`]. + pub(crate) fn set_guard(&mut self, level: u8, setup: crate::xart_guard::Setup) -> Result<()> { let keys = self.live_keys()?; - self.guard = Some(crate::xart_guard::Guard::open(level, keys)); + self.guard = Some(crate::xart_guard::Guard::open(level, keys, setup)); Ok(()) } @@ -442,6 +443,21 @@ impl Store { .map(|guard| (guard.effective_level(), guard.list_loaded())) } + /// Whether this install's first keybag creation was sent under the guard, + /// as far as the guard's list says; `false` when no guard runs. + pub(crate) fn guarded_setup(&self) -> bool { + self.guard + .as_ref() + .is_some_and(|guard| guard.guarded_setup()) + } + + /// Tells the guard that the enclave was handed the record under `key`. + pub(crate) fn note_enclave_read(&mut self, key: &Key) { + if let Some(guard) = self.guard.as_mut() { + guard.note_read(key); + } + } + /// Opens the guard's first-setup window (see [`crate::xart_guard`]). /// `Ok(false)` without a guard or once this install has listed anything. pub(crate) fn open_first_setup(&mut self) -> Result { diff --git a/tools/aurora-sep/XART-SAFETY.md b/tools/aurora-sep/XART-SAFETY.md index b8282abc5250e6..7d149b08496b01 100644 --- a/tools/aurora-sep/XART-SAFETY.md +++ b/tools/aurora-sep/XART-SAFETY.md @@ -22,7 +22,10 @@ two shared root records. A refused write fails the enclave's request the way a read-only gigalocker does: Touch ID may then be unavailable, but no other OS's record changes. The one exception is a fresh install's first keybag creation on a warm-attach Mac at level 1, which may rewrite one existing -SEP-xART locker (see "Fresh installs" below). +SEP-xART locker (see "Fresh installs" below). On a cold-boot Mac the owner +can accept one more with `xart_guard_pin=1`: rewrites of the one shared +locker its keybag creation reaches (see "Cold-boot Macs: pinning the shared +locker" below). The default, `xart_guard=-1`, takes the platform's level: @@ -61,15 +64,19 @@ records are allowed only if they are on Linux's list: records the enclave created while the guard was on. Which records they are has not been established, so: -- On a Mac whose Touch ID was set up with `xart_guard=0` (every cold-boot - Mac, see below, and any Mac that used Touch ID before the guard existed), - none of Linux's records are on the list. A guarded boot restores the +- On a Mac whose Touch ID was set up with `xart_guard=0` (a cold-boot Mac + set up without `xart_guard_pin`, see below, and any Mac that used Touch ID + before the guard existed), none of Linux's records are on the list. A guarded boot restores the fingerprints and then refuses the match's write ("xART guard: refused to rewrite a kind-4 record this Linux install did not create"), and the verify fails. Such a Mac needs `xart_guard=0` to use Touch ID, not only to set it up. - On a warm-attach Mac set up under the guard, whether every record a match rewrites is on the list has not been tested. +- On a cold-boot Mac set up under the guard with `xart_guard_pin=1`, the + record the create added is on the list and the shared locker it rewrote + is pinned. Whether those are the two records a match rewrites has not + been tested. ### Setting up Touch ID: creating the keybag @@ -79,7 +86,7 @@ another finger into an existing keybag does not create one. | Platform | Bootstrap | Keybag creation under level 1 | | --- | --- | --- | -| M1 (T8103), M1 Pro/Max (T6000/T6001) | cold boot | Refused: it rewrites a pre-Linux session record (seen on T6000; T8103 and T6001 untested). Needs `xart_guard=0`. | +| M1 (T8103), M1 Pro/Max (T6000/T6001) | cold boot | Refused: it rewrites a pre-Linux session record (seen on T6000; T8103 and T6001 untested). Needs `xart_guard=0`, or `xart_guard_pin=1`, which is not yet tested on hardware. | | M2 (T8112) | warm attach | No xART writes (J413), so the guard does not affect it. | | M2 Max (T6021, J416c) | warm attach | On a fresh install, commits one pending SEP-xART locker; allowed once (see "Fresh installs"). Otherwise no xART writes. | | M2 Pro (T6020), M3 (T8122) | warm attach | Untested. | @@ -98,6 +105,14 @@ the kernel log names the refused kind. What to do depends on the case: only once the rewrite of the shared, pre-Linux record has been accepted for that Mac (see the next section), and treat macOS Touch ID as unverified until it has been checked there. +- A cold-boot Mac that has never tried to create its keybag under the guard: + `options apple_sep xart_guard_pin=1` keeps the guard on and accepts the + rewrite of that one record only (see "Cold-boot Macs: pinning the shared + locker"). The same caution about macOS applies. A Mac that has tried, or + that already has a keybag, must reset Touch ID and remove + `/var/lib/aurora-sep-xart-owned.bin` first: the window that pins the + locker opens only on an empty list, and a reset alone keeps the list. The + driver says at probe which of the two it found. - A warm-attach Mac set up under the guard whose verify is refused: report the log line. `xart_guard=0` restores use at the cost of the protection. - A list that could not be read: every record that existed at boot is @@ -122,8 +137,8 @@ and from those `matching`: | `matching` | When | `aurora-sep-ready` | | --- | --- | --- | | `usable` | xART writes enabled, no guard | ready | -| `unverified` | guard on a warm-attach Mac, list loaded, nothing refused yet | restored, matching UNVERIFIED (not called ready; exit 0) | -| `blocked` | xART writes disabled, a refusal seen, no list, or a guard on a cold-boot Mac | NOT ready (exit 1), with the reason and the `xart_guard=0` opt-out | +| `unverified` | guard with its list loaded and nothing refused yet, on a warm-attach Mac or on a cold-boot Mac whose keybag was created under it with `xart_guard_pin=1` | restored, matching UNVERIFIED (not called ready; exit 0) | +| `blocked` | xART writes disabled, a refusal seen, no list, or a guard on a cold-boot Mac whose keybag was not created under it | NOT ready (exit 1), with the reason and the `xart_guard=0` opt-out | | absent | a kernel that does not report it | restored, matching UNVERIFIED (exit 0) | The diag ABI stays at version 2: these attributes were added to it, and a @@ -157,13 +172,18 @@ it: then looks like another OS's. Copy the file back from the old install if you have it. Without it, those records stay protected; resetting Touch ID (`install-aurora-sep.sh --reset-touchid`) creates a new keybag, which on a - cold-boot Mac needs `xart_guard=0` as above. + cold-boot Mac needs `xart_guard=0` or `xart_guard_pin=1` as above. - A torn last entry, from a crash while appending, is ignored at the next probe and overwritten by the next new record. - The first entry may be a marker instead of a record: it says this install's first-setup window (see "Fresh installs") has been used. It lists no record. Resetting Touch ID keeps the list, so the new keybag gets no window; a reinstall or deleting the file gives the next create one. +- On a cold-boot Mac set up with `xart_guard_pin=1`, one entry is a pin + instead of a record: it names the shared SEP-xART locker the enclave may + rewrite, and lists no record as Linux's. Only the first pin in the list + counts. A kernel without pinning reports it as one unreadable entry and + ignores it, so that kernel refuses the locker as before. The file holds only record kinds and session ids, no key material, and it can be backed up and copied like any other file. @@ -195,6 +215,79 @@ unverified until macOS Touch ID unlock and keychain access have been checked there. The other cold-boot SoCs (T8103, T6001, T6002) probably behave the same way; that is untested. +## Cold-boot Macs: pinning the shared locker (`xart_guard_pin`) + +Not yet run on hardware. The rule below is built from the J316s +measurements above and is covered by KUnit tests only. + +Until now a cold-boot Mac had two choices: no Touch ID, or `xart_guard=0`, +which lets the enclave rewrite or delete any session record on the Mac. +The J316s measurement says the create needs far less: one new record, a +shared root, and one existing session record that the enclave reads at +every attach. `xart_guard_pin=1` (default 0) lets the owner accept exactly +that record, if it is a SEP-xART locker (kind 4), and keep the guard on for +everything else. It has an effect only on a cold-boot Mac at level 1. + +- The first-setup window, which cold-boot Macs otherwise never get, opens + for the first `CREATE_KEYBAG` of an install whose list is loaded and + empty. The marker is written first, as on a warm-attach Mac. +- In the window the guard passes one rewrite of an existing kind-4 locker, + and only of a locker the enclave read since probe (the driver notes each + `OP_SESSION_READ` it answers with a record). Before the write reaches the + gigalocker, the guard appends a pin entry naming that locker to the list + and flushes it. If the pin cannot be made durable, the rewrite is refused. +- From then on the enclave may rewrite the pinned locker, on any boot where + the parameter is set and the enclave has read the locker. That covers a + match, if the locker is one of the two records a match rewrites, and a + later `CREATE_KEYBAG` after a Touch ID reset. +- The pinned locker is never deleted and never listed as Linux's. Every + other record from before Linux, kind 3 or 4, stays refused. Level 2 gets + none of this. +- Without the parameter the pin stays in the list and is not honoured, so + the Mac is back to refusing that locker. +- The record the create adds is listed as Linux's, as on any guarded Mac, + so a match's rewrite of it passes. `matching` then reads `unverified` + rather than `blocked`. + +Before the first setup under the pin: + +- Boot macOS once after installing, so that macOS's enclave commits any + SEP-xART locker the install left pending (see "Fresh installs" below). + The window pins the first existing locker the create rewrites. On a Mac + where that is the pending locker, the shared one is refused afterwards and + the create fails. +- Start with no list. An earlier guarded attempt leaves entries in it, and + the window does not open on a list that is not empty. + +What the pin does not establish: + +- That the record the create rewrites is a SEP-xART locker. The refusals + logged on J316s and J314s name kind 4, but the ledger above does not give + the kind. A kind-3 record is refused in the window as anywhere else, and + the create then fails as it does today. +- That macOS is unaffected by Linux's rewrites of that locker. The locker + is not tied to an OS identity and macOS reads it too. This is the same + open question as with `xart_guard=0` on these Macs; the pin narrows which + records Linux can change, not what a change to this one does. Treat macOS + Touch ID as unverified until unlock and keychain access have been checked + after a Linux keybag creation and after Linux matches. +- That a match rewrites only the listed record and the pinned locker. If it + rewrites another record from before Linux, the guard refuses it and logs + the refused locker's tag and whether the enclave had read it, next to the + pinned locker's tag in the earlier log lines, so the two can be compared. +- That the locker keeps its session id. If another OS replaces it under a + new id, the pin names a record that no longer exists and the new locker + is refused; the tags in the log show the difference. The window does not + open twice, so recovering means resetting Touch ID with the list removed. +- That the pin survives a driver reload. The allowance needs the enclave's + reads of the locker since probe. If the driver is bound again while the + enclave keeps running and does not repeat its attach reads, the pinned + locker is refused until a restart. +- That T8103 and T6001 behave as T6000 does. + +The tags in those log lines are a CRC-32 of the session id. They identify a +locker across boots in the log without printing its id. + ## Fresh installs: the pending SEP-xART locker (2026-10-25) Measured on an M2 Max (T6021, J416c, system firmware 26.6.2) installed with @@ -232,8 +325,9 @@ the first existing kind-4 locker it writes (`FirstSetup` in `xart_guard.rs`). Nothing identifies that locker as the pending one: no record says which OS or bless it belongs to, and a size test would not prove it. Deletes, kind-3 lockers and a second rewrite are refused as before. -Level 2 gets no window, and neither do cold-boot Macs: their create -rewrites a pre-Linux record for a different reason (above). +Level 2 gets no window, and neither do cold-boot Macs unless their owner +set `xart_guard_pin=1`: their create rewrites a pre-Linux record for a +different reason, and the window then pins that record instead (above). The window is used once while the install keeps its list. Before the create is sent, the driver writes a marker as the list's first entry and diff --git a/tools/aurora-sep/aurora-sep-ready b/tools/aurora-sep/aurora-sep-ready index a00c9be3e20199..40cbe67a8dea28 100644 --- a/tools/aurora-sep/aurora-sep-ready +++ b/tools/aurora-sep/aurora-sep-ready @@ -112,7 +112,7 @@ blocked_reason() { elif [ "$(attr xart_guard_list)" = unavailable ]; then echo "the xART guard could not load its list of Linux's records, so it refuses every session write. $optout" elif [ "$(attr boot)" = cold ]; then - echo "on this cold-boot Mac the keybag can only be created with the xART guard off, so the session records a match rewrites are not on the guard's list. $optout" + echo "on this cold-boot Mac no keybag was created under the xART guard, which takes xart_guard_pin=1, so the session records a match rewrites are not on the guard's list. $optout" else echo "the xART guard refuses a match's write. $optout" fi diff --git a/tools/aurora-sep/packaging/arch/aurora-sep/PKGBUILD b/tools/aurora-sep/packaging/arch/aurora-sep/PKGBUILD index b2254d7098fc56..9b548161176853 100644 --- a/tools/aurora-sep/packaging/arch/aurora-sep/PKGBUILD +++ b/tools/aurora-sep/packaging/arch/aurora-sep/PKGBUILD @@ -34,14 +34,14 @@ source=(load-driver sha256sums=('abea60bb264ced349f7cf671d8d26e1609a81a60ea4c34d66ec6f7f73b847dbb' '447f99cc3c7e683134f31b993aa825fadde24e4854954a3035c96e6631d4d4d0' 'f8d0c4b9385e6716d5ac5dd9941a57459fbc551a8238383bcde36cd929d0523f' - '40f0d21446a85bab3e3800b31342e94e553af0fcde2c985503147519737e011d' + '23528a9ac66a74be9a5d2a57a2ffd47d1e6b3c350c1c37824c60cefde2343045' 'f38421360c2f885bb102bc5076d81006d352d03d12b5fb35b4da8a5132f4ccc0' '8d8df0ba2a6861b2edb2110e606906d84ca4848617621ad3cb48493a1522971d' '0695bd9ce4c207241db13c3ea07819a032d8213417021378f5015ab9317cde12' '5936eb76db666496a8700dade7ac6bcb3785b517958dcea10685690f1822c86f' 'ffab97b20bfd5f0eb1ab641179a131843349cf16890fff0cf2d893f0b5681b37' 'dbcf59cecd62c0245cf39c3c8ee41e3088e2890da89288e91d1c53ee3f02cba4' - '393bd394471e33706253027c48c19d9c1c8a4f6c0d9891bad1bd1364f7081a16') + '89ad11e02cf1234eff604664c4155e84f688cc570b577e6bb2c4587230d6be10') # A unit and the helper it runs ($1, installed as $3), pointed at the # packaged helper. diff --git a/tools/aurora-sep/tests/test_diag_sensor.py b/tools/aurora-sep/tests/test_diag_sensor.py index b5c88e5f193fe2..a62d1b5766d92a 100644 --- a/tools/aurora-sep/tests/test_diag_sensor.py +++ b/tools/aurora-sep/tests/test_diag_sensor.py @@ -245,7 +245,10 @@ return "absent"; } -/* argv: level list matching-at-probe refusals matching-after-refusal */ +/* + * argv: level list matching-at-probe refusals matching-after-refusal + * [matching-after-first-setup] + */ int main(int argc, char **argv) { struct device dev; @@ -255,6 +258,8 @@ sep_diag_register(&dev, "TEST", 4, false, false, true); while (refusals--) sep_diag_xart_guard_refused(atoi(argv[5])); + if (argc > 6) + sep_diag_set_matching(atoi(argv[6])); /* attr() returns one static buffer: print each before the next. */ printf("%s ", attr("abi")); printf("%s ", attr("xart_guard")); @@ -295,12 +300,19 @@ def test_matching_follows_the_guard(self): usable, unverified, blocked = 1, 2, 3 # SEP_DIAG_MATCHING_* in shim.h cases = [ # level, list, matching at probe, refusals, matching after them + # and, where given, matching once the first setup is recorded ((0, 0, usable, 0, 0), '2 0 none 0 usable'), # Neo, M1 Pro (pinned 0) ((1, 1, unverified, 0, 0), '2 1 loaded 0 unverified'), # M2 under the guard ((1, 1, unverified, 2, blocked), '2 1 loaded 2 blocked'), # ... after refusals ((2, 1, unverified, 0, 0), '2 2 loaded 0 unverified'), ((1, 0, blocked, 0, 0), '2 1 unavailable 0 blocked'), # no list ((1, 1, blocked, 0, 0), '2 1 loaded 0 blocked'), # cold boot, level 1 + # ... with xart_guard_pin, once its first keybag creation is sent + ((1, 1, blocked, 0, 0, unverified), '2 1 loaded 0 unverified'), + # ... and the refusals counted before that stand, and win over a + # matching value that was derived before they landed + ((1, 1, blocked, 2, blocked, blocked), '2 1 loaded 2 blocked'), + ((1, 1, blocked, 2, blocked, unverified), '2 1 loaded 2 blocked'), ((0, 0, 0, 0, 0), '2 0 none 0 unknown'), # never set ((0, 0, 7, 0, 0), '2 0 none 0 unknown'), # out of range ] @@ -311,6 +323,25 @@ def test_matching_follows_the_guard(self): capture_output=True, text=True, check=True) self.assertEqual(done.stdout.strip(), want, args) + def test_the_first_setup_window_brackets_the_create(self): + # sks.rs asks the guard for the window on every platform (the guard + # decides which get one), tells diag once it opens, sends the create + # and shuts the window again, in that order and once each. + source = (APPLE / 'sks.rs').read_text() + create = function(source, 'pub(crate) fn sks_provision_identity_keybag(&self) -> bool') + steps = ['store.open_first_setup()', 'crate::diag::xart_guard_setup_recorded()', + 'intent.sending()', 'self.sks_exchange(request.name', 'store.close_first_setup()'] + places = [create.find(step) for step in steps] + self.assertNotIn(-1, places, steps) + self.assertEqual(places, sorted(places), steps) + for step in steps: + self.assertEqual(create.count(step), 1, step) + # Nothing else in the key store opens, reports or shuts the window. + for step in (steps[0], steps[1], steps[4]): + self.assertEqual(source.count(step), 1, step) + # The bootstrap no longer decides here: xart_guard.rs (Setup) does. + self.assertNotIn('Bootstrap', create[:places[2]]) + def test_probe_and_remove_report_the_bind(self): source = (APPLE / 'sensor_shim.c').read_text() probe = function(source, 'static int sep_sensor_probe(struct spi_device *spi)')