Skip to content

soc: apple: sep: authorization contexts for user-bag keys - #2051

Draft
cameroncooper wants to merge 24 commits into
aurora-silicon:integration/aurorafrom
cameroncooper:review/sep-retained-authorization
Draft

cameroncooper wants to merge 24 commits into
aurora-silicon:integration/aurorafrom
cameroncooper:review/sep-retained-authorization

Conversation

@cameroncooper

@cameroncooper cameroncooper commented Nov 16, 2026 •

Copy link
Copy Markdown

Stacked on #2050 (and its stack). Review starts at "one owner for the sensor at a time"; five commits, each builds and passes KUnit on its own.

The case

A password manager that keeps its items sealed to Secure Enclave keys is an obvious thing to build on this driver, and I have one running (Keychain, an iCloud Keychain-compatible password manager for Linux, on J293). With /dev/sep-key as it is, every reveal or autofill needs a fresh Touch ID match or password: one match, one operation (#1541). That leaves such an app two choices: prompt for every item (ten items, ten touches), or unseal its vault key once and keep it in process memory, outside the enclave. macOS does neither: an authentication context can be reused for a short time (touchIDAuthenticationAllowableReuseDuration), which is how Keychain and Passwords reveal several items after one unlock.

So this adds authorization contexts: an explicit, scoped and expiring exception that a key's owner asks for, while the one-match-one-operation rule stays for every other path. The key never leaves the enclave, every operation still goes through it, and the kernel enforces the ceiling and the scope; the app picks the lifetime within them (Keychain exposes it as a user setting).

  • A context belongs to one Unix account's bag (SEP_KEY_CTX_NEW: root or that user) and is a file descriptor; closing it ends it.
  • One authentication (SEP_KEY_CTX_AUTH: a Touch ID match in the user's own domain from soc: apple: sep: Touch ID in each user's own domain #2050; SEP_KEY_CTX_AUTH_PASSWORD: the bag's password, checked and counted by the enclave) lasts lifetime_s, at most 12 hours. It ends at once when the bag locks, on suspend, on SEP_KEY_CTX_REVOKE and when the driver stops (EKEYEXPIRED after).
  • SEP_KEY_CTX_BIND, before authentication, can limit it to one key and the operations (sign, decrypt) it may run; anything else is then refused with EPERM.
  • Each SEP_KEY_CTX_SIGN/DECRYPT is still one enclave operation under that key's own access control.
  • Opt-in: key_context_api=1, advertised as SEP_KEY_FEATURE_CONTEXTS (0x20; 0x10 is soc: apple: sep: Touch ID and password keys under a user's bag #1767's), and only on the 13.5 store with per-user bags for now.

The ABI is in apple-sep.h (0x40–0x48 on the usual magic) and marked DESIGN DRAFT, like the key-bag block.

Commits

  1. one owner for the sensor at a time: a capture owner (lease) so the BIO calls that reach the enclave without catacomb_writer (GET_INFO, ATTEST, LIST_ENCLAVE, PREPARE_ENROL) cannot run between a key touch's steps. Changes the default path with the parameter off; the justification is in the commit.
  2. make /dev/sep-key a per-open device: each open gets its own file and driver reference, so requests can belong to the file that made them. Every existing request is unchanged. Since unregistering no longer waits for running calls, remove counts them and waits for them before taking the hardware down.
  3. authorization contexts: NEW, Touch ID AUTH, SIGN, DECRYPT, QUERY, REVOKE, SEP_KEY_CANCEL_ID; request ids, single delivery of each result, revocation on bag lock and suspend.
  4. authenticate a context with the bag's password: AUTH_PASSWORD.
  5. bind a context to one key: BIND.
  6. contexts on the variant-5 store: offered on any key store with per-user bags, and a variant-5 bag's lock (any lock, and logout) revokes its contexts first, as the 13.5 lock does.
  7. wait for the last touch before any enclave request: a no-match is reported before the worker's bookkeeping ends, and with (1) every request that takes the enclave held the capture, so the call right after one (PREPARE_ENROL after fprintd's duplicate check, a retry's GET_INFO) got EBUSY. Every such request now waits for the worker, bounded as a capture start does, and the worker frees the sensor before it marks itself stopped. This fixes a regression from (1); it can be folded into it if you prefer.

Tests

  • KUnit (in-module, run on arm64 QEMU): apple_sep_capture_owner, apple_sep_key_request_ids, apple_sep_key_result, apple_sep_key_context_state, apple_sep_key_context_scope; all 331 SEP tests pass at the tip.
  • Host test tools/aurora-sep/keys/tests/check_context_lifecycle.py (6 cases: the delivery transitions with a drop observer); the sep-source static tests pass at the tip.
  • arm64 module and KUnit builds pass with no new warnings.

Hardware

  • J293 (M1), on kernels built from this stack before and after the split (2026-11-16), with the same results on both:

    • Keychain unlocked with one Touch ID, then four item reveals ran as four context decrypts with no further prompt;
    • a test on throwaway keys under the user's bag: SEP_KEY_CANCEL_ID ended a waiting AUTH (ECANCELED); a context bound to one key for decrypt decrypted twice with no prompt, refused another key (EPERM) and a second BIND (EBUSY), and returned EKEYEXPIRED after its lifetime.
    • Found and fixed in that pass: an AUTH right after a cancelled one got EBUSY while the old request was still cleaning up (it now waits, bounded); an ended context touch was logged as a sensor fault.
    • Not run: password AUTH, a bag lock revoking a live context, key_context_api=0, driver removal with a call in progress.
  • J716c (M5 Max, T6050, variant-5 store), on integration/aurora with the J716c series (arm64: spin table: release chosen stopped CPUs ahead of the others #2118–nvme: apple: the T6050 ANS2 sleep attachment on the J716c #2134, arm64: dts: apple: t6050-j716c: Add the Touch ID sensor #2162), 2026-11-17/18:

    • the same throwaway-key test passed (cancel, Touch ID AUTH, two decrypts with no prompt, out-of-scope key EPERM, second BIND EBUSY, EKEYEXPIRED);
    • a context authorized with the bag's password signed and decrypted with the bag's presence keys;
    • after (7), fprintd enrolment succeeded right after its duplicate check; on J293, the second and third touch of one lock-screen authentication stayed in the account's domain.
  • J293 again after (6), on the 13.5 store: the throwaway-key test passed unchanged.

  • Known and not fixed here: after a lock-screen fingerprint unlock, a key touch under the bag is refused until the next password (J293); under investigation.

🤖 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>
@cameroncooper
cameroncooper force-pushed the review/sep-retained-authorization branch from 7d8fbe0 to c18d442 Compare November 16, 2026 18:45
@cameroncooper
cameroncooper force-pushed the review/sep-retained-authorization branch from c18d442 to f9afd69 Compare November 16, 2026 19:49
@cameroncooper cameroncooper changed the title RFC: soc: apple: sep: authorization contexts for user-bag keys soc: apple: sep: authorization contexts for user-bag keys Nov 16, 2026
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-retained-authorization branch from f9afd69 to e9afbc6 Compare November 16, 2026 20:23
…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>
Touch ID enrolment and verify, a touch-gated /dev/sep-key operation and
the late sensor attach each drive the sensor and the enclave's match
operations, and serialize on catacomb_writer. Other BIO calls reach the
enclave without it (GET_INFO, ATTEST, LIST_ENCLAVE, PREPARE_ENROL), so
one of those could run between a key touch's steps.

Add a capture owner. A synchronous user (one of those calls, a
deletion, a bio open, the late attach, a key touch) takes a lease for
its duration; an enrol or verify start hands its lease to the queued
worker, which gives it up only after its cleanup. A second owner gets
EBUSY. Starting a capture still waits, as before, for the last worker
to stop, now before the lease is taken.

KUnit covers the owner's transitions.

Assisted-by: LLM [Claude Code, claude-opus-5-5]
Signed-off-by: Cameron Cooper <c@meron.cc>
/dev/sep-key was registered with sep_bio_register_concurrent: one shared
context for every opener, no per-file state, and an unregister that
waited for running ioctls. Requests that belong to the file that made
them (an id to cancel, an authorization a file holds) need state per
open file.

Register it through a small misc-device shim instead. Each open makes a
file that holds its own reference to the driver, so it may outlive the
registration; its calls then fail with ENODEV. Because unregistering no
longer waits for running calls, the driver counts them, and remove
waits for them to end before it takes the hardware down, as the old
unregister did; no call starts once remove has begun.

Every existing /dev/sep-key request goes to key_ioctl unchanged. The
unused register_concurrent Rust wrapper goes; the C function stays for
its KUnit test.

Assisted-by: LLM [Claude Code, claude-opus-5-5]
Signed-off-by: Cameron Cooper <c@meron.cc>
A password manager whose items are sealed to Secure Enclave keys needs
one authentication to cover a run of operations: macOS lets a Touch ID
or password authentication be reused for a short time for exactly this
(a reuse duration on the authentication context), so that revealing
several items after one unlock does not ask for a finger each time.
/dev/sep-key has only one-shot authorization: one match, one operation.
Without more, such an app either asks for a finger for every item or
unseals its vault key once and keeps it outside the enclave.

Add authorization contexts (SEP_KEY_CTX_*, SEP_KEY_FEATURE_CONTEXTS),
opt-in with key_context_api=1 on the 13.5 key store with per-user
bags, and bounded:

- a context belongs to one Unix account's bag (NEW: root or that user)
  and is a file descriptor: closing it ends it;
- one authentication (AUTH: a Touch ID match in the user's own domain)
  lasts lifetime_s from the match, at most 12 hours, and ends at once
  when the bag locks, on suspend, on REVOKE and when the driver stops
  (EKEYEXPIRED after);
- each SIGN or DECRYPT is still one enclave operation under that key's
  own access control, run with the context's credential.

Each request carries an id; SEP_KEY_CANCEL_ID on the file it was made on
ends it (an AUTH waiting for a finger). A request's result is delivered
once, after its worker has given up the capture; a cancel or the
deadline wins over an undelivered result. An AUTH straight after a
cancelled one waits, bounded, for the old request's cleanup rather than
fail with EBUSY, and an ended request's capture is not reported as a
sensor fault.

The one-match-one-operation rule stays for every other path; a context
is an explicit, scoped and expiring exception requested by its owner.

KUnit covers request ids, the result and context state machines; the
host test runs the delivery transitions with a drop observer.

Assisted-by: LLM [Claude Code, claude-opus-5-5]
Signed-off-by: Cameron Cooper <c@meron.cc>
Touch ID is not always there to authorize a context: no finger may be
enrolled, the bag may have just been unlocked after a lock or a restart,
or the user may prefer the password, as macOS offers it in its prompt.

Add SEP_KEY_CTX_AUTH_PASSWORD. The enclave checks the password against
that context's bag, and counts a wrong one, into a fresh credential that
becomes the context's grant; a wrong password ends the context (outcome
NOT_MATCHED), so another attempt opens a new one. The kernel wipes its
copy of the password, in the reply too. An accepted password also renews
the bag's Touch ID preparation, as a bag unlock does.

Assisted-by: LLM [Claude Code, claude-opus-5-5]
Signed-off-by: Cameron Cooper <c@meron.cc>
A context authorizes every key under its bag for as long as it lives. A
password manager's vault session needs only its item key, and only to
decrypt; if anything else in that process misused the context, it could
not then decrypt a passkey's secret or sign with another key.

Add SEP_KEY_CTX_BIND. Before AUTH, and only once, it names one key (by
its handle, which must be under the context's bag) and the operations
(SEP_KEY_CTX_SCOPE_SIGN, _DECRYPT) the context may run on it; SIGN and
DECRYPT then refuse any other key or operation with EPERM. A BIND after
authentication is refused with EBUSY: a scope cannot widen what an
existing authorization covers. An unbound context behaves as before.

KUnit covers the scope's checks.

Assisted-by: LLM [Claude Code, claude-opus-5-5]
Signed-off-by: Cameron Cooper <c@meron.cc>
Authorization contexts were offered only on the 13.5 key store, but they
need only per-user bags and a match in the bag user's own domain, which
the variant-5 store (T8140, T6040 and its inheritors) now has too. Offer
them on any key store with per-user bags.

A variant-5 bag's lock, with or without a grace period and at logout,
now revokes that bag's contexts before the store is asked, as the 13.5
lock does, so no retained match outlives it.

On J716c (T6050) a bag context authorized with Touch ID or the bag's
password signed and decrypted with the bag's presence keys, kept each
key and operation to its binding, and ended when released.

Assisted-by: LLM [Claude Code, claude-opus-5-5]
Signed-off-by: Cameron Cooper <c@meron.cc>
One owner for the sensor at a time made every /dev/sep-bio request that
takes the enclave hold the capture, but only enrol and verify starts
waited for the last enrol or verify worker to stop. A no-match is
reported before that worker's bookkeeping ends (the lockout record and
the background result), so the request right after one often found the
sensor still held and was refused with EBUSY: fprintd's enrolment after
its duplicate check (PREPARE_ENROL) failed, and libfprint's GET_INFO
before a retry failed, which made that retry match as the built-in user
instead of the account.

Every request that takes the enclave now waits for the worker, bounded
as a capture start is. The worker also frees the sensor before it marks
itself stopped, so a request woken by its exit finds the sensor free.

On J716c (T6050), fprintd's enrolment of a new finger had failed with
EBUSY right after the duplicate check.

Assisted-by: LLM [Claude Code, claude-opus-5-5]
Signed-off-by: Cameron Cooper <c@meron.cc>
@cameroncooper
cameroncooper force-pushed the review/sep-retained-authorization branch from e9afbc6 to fb42dbf Compare November 18, 2026 18:20
@RyanTheTide

Copy link
Copy Markdown
Contributor

Thanks for the clear write-up. Three points:

  1. key_device.rs:27: contexts are enabled by the key_context_api module parameter. We avoid module-parameter opt-ins for features; please advertise SEP_KEY_FEATURE_CONTEXTS wherever per-user bags are supported, and keep it in draft until the ABI can be on by default.

  2. lifetime_s = 0 means no expiry (key_context.rs:245), while the description promises at most 12 hours. Please reject 0 or treat it as SEP_KEY_CTX_LIFETIME_MAX, so the kernel's ceiling always holds.

  3. The owner check happens only at SEP_KEY_CTX_NEW. After that, anyone holding the context fd (passed over a socket or inherited by fork) can sign and decrypt under it. Either document the fd as a capability in apple-sep.h, or record the creator's credentials at NEW and refuse other users at use. Please also confirm BIND is refused after AUTH.

Nit: sep_key_ctx_new and sep_key_ctx_query have no reserved field.

Row we would like on J293 and one newer Mac: NEW for another user gives EPERM; signing after REVOKE, a bag lock or a suspend gives EKEYEXPIRED; BIND to key A then signing with key B gives EPERM; closing the fd ends the context.

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