Repository navigation
soc: apple: sep: Touch ID in each user's own domain - #2050
cameroncooper wants to merge 17 commits into
Conversation
…he create variant userbag_ioctl refused per-user key bags unless profile.key_store was the variant-5 create encoding. That encoding describes how the identity key bag is created, not whether the enclave can create a NEW per-user bag. T8112 (M2) and T8122 (M3) are warm-register platforms whose SEP is handed over running and shared with macOS; their identity bag uses the variant-5 form, so they passed the Variant5 check, yet their enclave never replies to a user-bag DESIGNATE_KEYBAG. A single unanswered DESIGNATE condemns the SKS endpoint for the rest of the boot (sks_wedged), taking the whole key store down: the log shows "DESIGNATE_KEYBAG got no reply" followed by every later SKS request reporting "endpoint gone for this boot". Per-user bag create and designate are proven only on T8140 (J700) and the T6040 (J616s / M4 Pro) enclave family. Add an explicit PlatformProfile capability, per_user_keybags, true only on those, and gate userbag_ioctl and the per-user-bag ref-key / FDE paths on it instead of on the create-encoding variant. The unsupported platforms now return EOPNOTSUPP before any enclave request, so the SKS endpoint is never wedged. Touch ID and the identity bag are unaffected: neither uses userbag_ioctl. The sep KUnit suite passes (598 run, 596 passed, 2 skipped, 0 failed). Assisted-by: LLM Signed-off-by: Ryan Murray <ryan@aurorasilicon.org>
ac1d3bc to
a5d642f
Compare
a5d642f to
a7e1f3e
Compare
On the 13.5 key store, sks_req_refkey always substituted the configured Linux user's designation for the target handle. That is right for the identity bag's source handles, but it also redirected an explicitly designated user bag, so a key meant for a per-user bag was made and used under the identity bag instead. Factor the choice into refkey_target(): source handles keep the identity mapping, and an explicit user designation keeps its own bag. Variant 5 is unchanged. The KUnit cases cover the identity fallback, the user-designation boundaries and variant 5. Assisted-by: LLM [Claude Code, claude-opus-5-5] Signed-off-by: Cameron Cooper <c@meron.cc>
The per-user bag path hard-coded designate variant 1 and its flags trailer, the variant-5 form. The 13.5 key store takes variant 0 with the body ending after the empty blob, as the identity-bag path already sends it. Move the variant choice into sks::designate_variant(), shared by both paths, and encode and decode the user-bag designation with it. The variant-5 layout is unchanged; the user-bag ioctls stay gated by per_user_keybags. The KUnit golden test gains a 13.5 case for the shorter body and its reply, and checks that each store rejects the other's form. Assisted-by: LLM [Claude Code, claude-opus-5-5] Signed-off-by: Cameron Cooper <c@meron.cc>
The user-bag ioctls refused every request on the 13.5 key store of M1/M2-generation Macs. Add that store's backend for create, import, export, unlock and lock: - create uses the generic DeviceBag constructor (version 1); - unlock first unlocks the loaded bag with the version-0 CHANGE_LOCK_STATE, which has no flags trailer, then runs the designated-session device-state transition. Neither alone lets a key under the bag run; - lock runs the transition with state Locked and the loaded-bag lock, then sends grace-timer fires, as the Mac's kernel does, until the store names the bag locked. The store locks only on a fire, about 10 s after an immediate lock on M1. The bag lock is not held while it waits. A screen lock with a grace period is not captured on this store and is refused with EOPNOTSUPP; - import of a bag the user's designation already names (a repeated login) keeps that bag rather than designating it twice. Variant 5 keeps a designation after its temporary handle is unloaded. The 13.5 loaded-bag unlock needs the handle, so the bag stays loaded from import or create until logout, which locks and unloads it. Password change, state query and FDE sealing stay EOPNOTSUPP on the 13.5 store. KUnit golden layouts cover the 13.5 create and its reply, the loaded-bag unlock and lock, the timer fire, and the loaded-bag registry. Assisted-by: LLM [Claude Code, claude-opus-5-5] Signed-off-by: Cameron Cooper <c@meron.cc>
The 13.5 key store refused CHANGE with EOPNOTSUPP, so a user's bag could not follow a password change. Its change-secret request is version 1 of the variant-5 one, as macOS 13 sends it: client, handle, the old and new secrets, two further blobs and two words (a u8 flag and the generation option), without variant 5's last word. Send it with the two blobs empty, the flag 0xff and the generation option 0, as the variant-5 path does, and accept the version-1 reply. KUnit adds the golden layout. Not yet run on hardware. Assisted-by: LLM [Claude Code, claude-opus-5-5] Signed-off-by: Cameron Cooper <c@meron.cc>
CREATE_USER refused on the 13.5 key store because user_key_create_in_bag made only variant 5's EC key type 5. The 13.5 store makes EC type 4 ref-keys, as it already does under the identity bag. Choose the key type from the key store, and advertise SEP_KEY_FEATURE_PASSWORD wherever per_user_keybags allows user bags. Sign and unseal under a user bag already address the designation's special handle on either store. On J293, keys created under a user's bag signed with an enclave-checked password. Assisted-by: LLM [Claude Code, claude-opus-5-5] Signed-off-by: Cameron Cooper <c@meron.cc>
The 13.5 key store paths for per-user bags (create, designate, import/export, unlock, lock, password change) and for user-bag keys are in place, so turn the per_user_keybags capability on for T8103. On J293 (MacBook Pro 13-inch, M1, cold-boot SEP) the userbag ioctls created, exported, imported, unlocked and locked (logout and suspend) a user's bag, and user-bag keys signed with an enclave-checked password. Password change is implemented but not yet run on hardware; a screen lock with a grace period stays refused on this store. T6000 and the 13.5 J414s profile are unchanged: nothing has run there. Assisted-by: LLM [Claude Code, claude-opus-5-5] Signed-off-by: Cameron Cooper <c@meron.cc>
A password-authorized sign or unseal creates an unlock evaluation in the enclave and deletes it afterwards. The deletion's answer was ignored, so a result could be returned while the credential context it was authorized by might still be live. Confirm the deletion before a result leaves the driver, and discard the result if it fails. An unconfirmed deletion latches key operations off until the driver restarts (a reboot or a module reload), so nothing later runs against a context that may still hold the credential; capability queries and cancellation stay available meanwhile. The KUnit cases and the host test run the production guard for success, early exits and a failed deletion, checking that the result is destroyed and that deletion is attempted exactly once. Assisted-by: LLM [Claude Code, claude-opus-5-5] Signed-off-by: Cameron Cooper <c@meron.cc>
A touch-gated SIGN or UNSEAL on a key under a user's bag matched the configured user's templates. The enclave refuses such a key unless the match is against the bag user's own catacomb, as macOS matches the logged-in user, so the call could never succeed on the 13.5 store. Add a biometric subject: while a touch-gated call on a user-bag key waits, the verify path addresses the bag's designation instead of the configured user. That covers the unlock evaluation, the match, the lockout and template-update persistence, and the check that a matched identity is known. Each bag user's catacomb lives in its own file, /var/lib/apple-sep-catacomb-bag-<uid>.bin, through a new catacomb Slot. Fixed machine components keep their existing files. On the 13.5 store, a password unlock now also loads that user's catacomb and makes the Touch ID preparation: an SCRD context verified with the bag's password and found TouchIdEnrollment-satisfied. Only its handle is kept, never the password, and it is deleted when the bag locks or logs out. A touch-gated call on that bag's key without one is refused with EACCES before the sensor is armed, so Touch ID needs the password once after every lock, as on macOS. Unlock never takes user_bags while it prepares, keeping the catacomb_writer-before-user_bags order of a touch. On J293: after a password unlock, one touch signed a user-presence key under the bag (verified), and the template update was saved to the user's file. After a lock the same call was refused at once. Assisted-by: LLM [Claude Code, claude-opus-5-5] Signed-off-by: Cameron Cooper <c@meron.cc>
A v5 enrolment carries the resolved Unix account, but it always went into the configured user's domain, whose templates cannot satisfy keys under that account's own bag. When the account's bag is loaded on the 13.5 store, run the enrolment with that bag user as the biometric subject: - its first enrolment selects a context scoped to that user alone, proved by zero identities, and never SYSTEM, which would also reselect the shared master; later ones activate the component the unlock restored; - BEGIN_ENROL is authorized by the credential the user's own password unlock prepared, not the identity bag's material; - the user's catacomb is saved first, then any other dirty user, the shared master and the lockout record. Success is reported only once nothing is save-pending; - the identity is not filed in the shared index, which is reconciled against the configured user. Matches check it against the enclave's list for that user. A bag that is loaded but locked refuses the enrolment, as macOS asks for the password to add a finger. An account with no loaded bag keeps the configured user, as before. A password unlock now prepares the credential for a user with no templates yet, so their first enrolment can run. On J293, an ENROL_START for the account completed into the bag user's domain (two identities), saved its catacomb file, and one touch of the new finger then signed a user-presence key under the bag. The configured user's enrolments were unchanged. Assisted-by: LLM [Claude Code, claude-opus-5-5] Signed-off-by: Cameron Cooper <c@meron.cc>
SEP_BIO_VERIFY_START carried no account, so every verify matched the built-in Linux user, even for an account whose fingers live in its own key bag's domain. Add SEP_BIO_VERIFY_ACCOUNT. With it, the request's account_uid (the word that was reserved) is the resolved Unix account: - while that account's bag is loaded and unlocked by its password, the match runs in that user's own domain, and the configured user's after-boot and lockout gates do not apply; - while it is loaded but locked, the verify fails without a capture with the lockout status, so pam_fprintd asks for the password; - with no loaded bag, the built-in user matches as before. The after-boot and lockout gates track the configured user: an account's own domain is used only once that account's bag has been unlocked by its password since boot, which the after-boot gate asks for, and the lockout record kept here is the configured user's. A verify that names an account is not short-circuited by the configured user's empty index. Where per_user_keybags allows user bags, GET_INFO advertises the flag in reserved[0] (SEP_BIO_INFO_VERIFY_ACCOUNT); elsewhere the flag is refused with EINVAL. The interface version stays 5, so existing libfprint keeps working, and older kernels refuse the flag with EINVAL. On J293, an account verify with a finger enrolled only in that user's domain matched; after the bag locked it was refused at once with status 8; a plain verify with a configured finger still matched. Assisted-by: LLM [Claude Code, claude-opus-5-5] Signed-off-by: Cameron Cooper <c@meron.cc>
A lock screen runs its password and fingerprint prompts at once. While fprintd waited for a finger, the user-bag ioctls refused everything but STATE with EBUSY. A password unlock would also have waited on the waiting verify's catacomb_writer to load the user's catacomb. So a password at the lock screen created a bag that could not then be exported or unlocked. Create, import, export, unlock and lock do not touch the Touch ID session, so they no longer require it to be idle; password change and FDE sealing still do. The user's catacomb is loaded once per load of their bag. Loading it resets the enclave's biometry lockout for that user, which invalidates a Touch ID credential made before it, so the first password after the bag loads loads the catacomb before making the credential. If a fingerprint wait holds catacomb_writer then, that capture is ended as a cancel ends it (fprintd sees a failure it may retry), and the lock is awaited for at most WORKER_EXIT_WAIT_MS. A key's touch is not ended. Without this, the first touch at a lock screen after boot found the credential stale and needed the password again. Every accepted password renews the credential. One that is replaced or ends is deleted in the enclave and its handle wiped. Assisted-by: LLM [Claude Code, claude-opus-5-5] Signed-off-by: Cameron Cooper <c@meron.cc>
A verify naming a Unix account matches in that account's own key bag, but SEP_BIO_LIST returned only the shared Linux index. fprintd treats a storage device's list as complete: after the first failed match it deletes every stored print the list lacks, so a single miss deleted the prints of fingers enrolled in an account's domain, which the next match still answered and fprintd could no longer place. List the identities of every account bag the enclave holds after the index's, once each and without a label (fprintd compares identities). The enclave is queried outside the session and index locks, as the live-count query is. The list now names every loaded account's identities to whoever opens /dev/sep-bio, which is root-only. KUnit covers the ordering and deduplication. On J293, the lock screen kept matching a finger enrolled in the user's domain after misses. Assisted-by: LLM [Claude Code, claude-opus-5-5] Signed-off-by: Cameron Cooper <c@meron.cc>
a7e1f3e to
fd8c3c5
Compare
Lead with what Keychain is and does, a light/dark screenshot of the desktop app, highlights, a how-it-works diagram, an honest status table and a short quick start. The full command-line reference moves, intact, to docs/USAGE.md. Point the kernel driver at aurora-silicon/linux#2050. The smoke test no longer forces a focus ring before its screenshots. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…tore The variant-5 key store (T8140, T6040 and its inheritors) has per-user bags too, but Touch ID followed them only on the 13.5 store. Variant 5 unloads a bag once it is designated, so the bag never entered `user_bags`: a touch for one of its user-presence keys matched in the configured owner domain, and the enclave refused that credential for the key (status -8). Password authorization was unaffected. Track a designated variant-5 bag under its designation at create and import, prepare its Touch ID after each password unlock, end the preparation at every lock (with or without a grace period) and drop the entry at logout. Enrolments, verifies and key touches for the bag's user then take that user's own domain, as on 13.5; the gates follow the profile's per-user bags instead of the 13.5 store. KUnit covers tracking a designation once. On J716c (T6050), a fingerprint enrolled in the bag user's domain authorized the bag's presence keys after a password unlock. Assisted-by: LLM [Claude Code, claude-opus-5-5] Signed-off-by: Cameron Cooper <c@meron.cc>
A print enrolled into a Unix account's own key bag is filed in that
user's domain and never in the shared index. SEP_BIO_DELETE looked only
at the index, so deleting one reported success ("nothing to delete")
while the enclave kept the template, and the finger went on unlocking
the bag's keys and the lock screen.
When the identity is not in the index but the enclave lists it under an
account's bag, delete it there: the bag must be unlocked by its password
(its catacomb loaded), as for an enrolment into it; 0x57 names that
user's identity as the enclave lists it, and that user's catacomb, any
other dirty one, the master and the lockout record are saved before
success is reported. A locked bag refuses with EACCES; a busy session
with EBUSY; writes off with EROFS, as for any deletion.
KUnit covers finding an account's identity by its own user.
Assisted-by: LLM [Claude Code, claude-opus-5-5]
Signed-off-by: Cameron Cooper <c@meron.cc>
…ave forgot it A bag user's catacomb is saved in its own file, and the shared master records its component. A kernel without per-user bags restores and saves the master without that component, so after one boot of it the loaded master lists nothing for the bag user while the file remains. The bag's restore treated that as a failure, and Touch ID for the bag stayed off: verifies and keys were refused and no finger could be enrolled again. Decide from what the enclave lists: a listed component is loaded as before (a missing file is refused, with what to do); neither component nor file is a bag that never enrolled; a file the loaded master no longer lists is stale, so the bag starts with no fingerprints and the next enrolment replaces the file. Without a loaded master nothing proves that, and the restore refuses as before. The restore runs only after the bag's password, so starting afresh admits no finger; it costs the owner their enrolled ones. KUnit covers the decision. On J716c (T6050), after a boot of a kernel without per-user bags left the master without the bag's component, enrolment into the bag had been refused. Assisted-by: LLM [Claude Code, claude-opus-5-5] Signed-off-by: Cameron Cooper <c@meron.cc>
… identity proof Matching waits at each boot for proof that the cold restore worked: the configured Linux user's templates must list at least one identity, because zero after a restore cannot be told from a restore that silently failed. Once every fingerprint is enrolled into a Unix account's own key bag, the configured user has none, the proof never completes, and every verify and key touch was refused before the capture, the bag's own fingers included. A match in a bag user's own domain does not use the configured user's templates: the bag's catacomb is loaded and checked after its password, and a bag with nothing loaded answers no match. Let a match with a bag subject through once every attach step of the restore succeeded (the cold-match preparation, the SCRD credential and the component restore); a match as the configured user still needs the full proof. On J716c (T6050), with both fingers enrolled into the bag and none for the configured user, the lock screen refused every touch after a reboot. Assisted-by: LLM [Claude Code, claude-opus-5-5] Signed-off-by: Cameron Cooper <c@meron.cc>
|
Thanks, this is the right direction. Three points:
Row we would like: two accounts, A enrolled in A's bag and B in the shared domain. With A's bag unlocked, A's finger matches and B's does not. With A logged out, a verify for A is refused. A user-bag key touch after lock is refused until A's password. |
Stacked on #2049 (which is stacked on #1824) and #2048. Review starts at "Touch ID for user-bag keys in the user's own domain".
Why per-account domains
Today every Touch ID match on Linux runs in one shared catacomb user (
SBIO_PROBE_USER_ID), and #1767 binds user-bag key ACLs to it. On macOS each user's fingers live in that user's own domain: another user's finger cannot release your keys, and your enrolments go with your bag. On the 13.5 store this is not optional either: the enclave refuses a touch-gated operation on a key under a user's bag unless the match is against that bag user's own catacomb, so a user-bag key with Touch ID cannot work at all from the shared domain.This series routes Touch ID into the bag user's own domain while their bag is loaded and unlocked, and leaves everything else (no bag, or no account named) exactly as it is now:
/var/lib/apple-sep-catacomb-bag-<uid>.bin, alongside the existing ones). A password unlock prepares a password-verified Touch ID credential; only its handle is kept, and it is deleted and wiped when the bag locks or logs out, so Touch ID needs the password once after every lock, as on macOS.ENROL_STARTwhose account's bag is loaded goes into that user's domain; a loaded but locked bag refuses (the password is needed to add a finger).SEP_BIO_VERIFY_ACCOUNTwith a namedaccount_uidfield (the word that wasreserved, same layout), advertised asSEP_BIO_INFO_VERIFY_ACCOUNTonly whereper_user_keybagsallows bags;SEP_BIO_IFACE_VERSIONstays 5 and older kernels refuse the flag withEINVAL.SEP_BIO_LISTalso returns the loaded accounts' identities (unlabelled). fprintd deletes every stored print a storage device's list lacks after its first failed match; without this, one miss deleted a print the next match still answered./dev/sep-biois root-only, so this names identities only to root.SEP_BIO_DELETEreported success while the enclave kept the template. It is now deleted in that user's domain (bag unlocked,EACCESotherwise) and the bag's catacomb, the master and the lockout record are saved before success.Question for review: an account verify skips the configured user's after-boot and lockout gates. An account's domain is used only once its bag was unlocked by its password since boot (which the after-boot gate asks for), and the lockout record kept by the driver is the configured user's. Whether the enclave applies its own retry limit in a bag user's domain is something I have not measured; if you would rather keep the shared lockout gate for account verifies too, that is a one-line change.
Tests
apple_sep_list_accounts), tracking a variant-5 designation once, finding an account's identity by its own user, and the stale-bag decision, plus the existing suites (317 pass); arm64 module and KUnit builds pass with no new warnings.test_log_ratelimit.pyand the othersep-sourcestatic tests pass.Hardware
J293 (M1), with libfprint passing the account and a PAM bag module:
On a kernel built from this stack (with #2051, 2026-11-16), through the normal lock screen:
J716c (M5 Max, T6050, variant-5 store), on integration/aurora with the J716c series (#2118–#2134, #2162) and this stack with #2051, 2026-11-17/18, with libfprint naming the account:
fprintd-delete -f) removed it from the enclave: the finger was refused at once, and after a reboot the enclave listed only the remaining print;🤖 Generated with Claude Code