Skip to content

soc: apple: sep: Touch ID in each user's own domain - #2050

Draft
cameroncooper wants to merge 17 commits into
aurora-silicon:integration/aurorafrom
cameroncooper:review/sep-touchid-user-domain
Draft

cameroncooper wants to merge 17 commits into
aurora-silicon:integration/aurorafrom
cameroncooper:review/sep-touchid-user-domain

Conversation

@cameroncooper

@cameroncooper cameroncooper commented Nov 16, 2026 •

Copy link
Copy Markdown

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:

  • user-bag keys: a biometric subject routes the unlock evaluation, match, lockout and template persistence to the bag's designation; each bag user's catacomb is its own file (/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.
  • enrolment for a v5 ENROL_START whose 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).
  • verify for a named account: SEP_BIO_VERIFY_ACCOUNT with a named account_uid field (the word that was reserved, same layout), advertised as SEP_BIO_INFO_VERIFY_ACCOUNT only where per_user_keybags allows bags; SEP_BIO_IFACE_VERSION stays 5 and older kernels refuse the flag with EINVAL.
  • open a bag while a fingerprint prompt waits: the bag ioctls no longer need the Touch ID session idle, so a lock screen's password and fingerprint prompts can run together. The user's catacomb is loaded once per load of their bag, before the first password makes the Touch ID credential (loading it later would invalidate that credential); if a fingerprint wait holds the sensor then, that capture is ended as a cancel ends it, with a bounded wait for it to stop.
  • list: SEP_BIO_LIST also 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-bio is root-only, so this names identities only to root.
  • variant-5 store (T8140, T6040 and its inheritors, which have per-user bags too): a designated bag is tracked under its designation, so key touches, verifies and enrolments for its user take that user's domain as on 13.5. Before this, a touch for a bag's presence key matched in the configured domain and the enclave refused the credential (status -8).
  • delete from the bag that holds a print: a print enrolled into an account's bag is never in the shared index, so SEP_BIO_DELETE reported success while the enclave kept the template. It is now deleted in that user's domain (bag unlocked, EACCES otherwise) and the bag's catacomb, the master and the lockout record are saved before success.
  • start a bag's Touch ID afresh when the enclave forgot it: a kernel without per-user bags saves the master without the bag's component. A saved bag file the loaded master no longer lists is stale; after the bag's password, Touch ID for that bag now starts with no fingerprints instead of staying off. A listed component with no file still refuses.
  • a bag user's match and the configured user's identity proof: once every finger is in a bag, the configured user has none and the boot-time identity proof never completes. A match with a bag subject now needs every attach step of the restore, but not that proof.

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

  • KUnit: list ordering and de-duplication (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.py and the other sep-source static tests pass.

Hardware

J293 (M1), with libfprint passing the account and a PAM bag module:

  • after a password unlock, one touch signed a user-presence key under the bag, and the template update was saved to the user's file; after a lock the same call was refused at once;
  • an enrolment for the account went into the bag user's domain and its finger then signed under the bag; the configured user's enrolments were unchanged;
  • an account verify with a finger enrolled only in that domain matched; after the bag locked it was refused at once; a plain verify still matched;
  • the lock screen kept matching after misses once the list included the account's identities.

On a kernel built from this stack (with #2051, 2026-11-16), through the normal lock screen:

  • the first touch after the password matched in the user's domain, after a boot and after a suspend (before the catacomb-ordering fix in "open a bag while a fingerprint prompt waits", that first touch was refused and asked for the password again);
  • two misses, then a match; no stored print was deleted;
  • after a suspend, Touch ID was refused without a capture until the password;
  • not run on this build: enrolment into the domain.

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:

  • before the variant-5 commit, a presence-key signature under the bag failed with -8 while a no-presence key and a password-authorized one worked; after it, a finger enrolled in the bag user's domain authorized the bag's presence keys after a password unlock;
  • fprintd enrolment went into the bag user's domain, and the lock screen matched there;
  • deleting a print enrolled into the bag (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;
  • with every finger in the bag and none for the configured user, the lock screen matched straight after a reboot (it had refused every touch before the identity-proof commit);
  • the stale-bag case was found here (after a boot of a kernel without per-user bags) and recovered by hand before the fix; the fix itself is covered by KUnit, not yet by a reproduction on hardware.

🤖 Generated with Claude Code

…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>
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>
@cameroncooper
cameroncooper force-pushed the review/sep-touchid-user-domain branch from a7e1f3e to fd8c3c5 Compare November 16, 2026 20:23
cameroncooper added a commit to cameroncooper/keychain that referenced this pull request Nov 16, 2026
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>
@RyanTheTide

Copy link
Copy Markdown
Contributor

Thanks, this is the right direction. Three points:

  1. drivers/soc/apple/sbio.rs run_verify(): with SEP_BIO_VERIFY_ACCOUNT, a locked bag refuses (good), but an account whose bag is not loaded falls back to the shared configured user's templates. Once an account has its own enrolment (its catacomb file exists, or the master lists its component), a verify naming that account should refuse when the bag is not loaded,. The fallback can stay for accounts with no enrolment of their own.

  2. "let a bag user's match through the configured user's identity proof": please keep an equivalent proof on the bag side, so a bag whose catacomb lists no identity after loading answers no match. A comment and a KUnit case would cover it.

  3. The stack carries a different revision of the soc: apple: sep: fail key operations when credential disposal fails #2048 commit than soc: apple: sep: fail key operations when credential disposal fails #2048 itself. Could you rebase on soc: apple: sep: fail key operations when credential disposal fails #2048's current head so it is reviewed once?

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.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants