Repository navigation
Conversation
m11y
force-pushed
the
feat/macos-secure-enclave-unlock
branch
2 times, most recently
from
September 3, 2026 13:37
a7cde29 to
8762fc7
Compare
3 of 6 tasks
m11y
force-pushed
the
feat/macos-secure-enclave-unlock
branch
from
September 4, 2026 06:06
8762fc7 to
57915ee
Compare
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Add optional, session-scoped Touch ID unlock on macOS using an ephemeral
Secure Enclave P-256 key.
After the master password unlocks the vault once in an
rbw-agentprocess,the agent can wrap the 64-byte user/vault key for a non-exportable Secure
Enclave key. A later timeout or
rbw lockdrops the plaintext vault andorganization keys as before; the next unlock asks the Secure Enclave to unwrap
the cached key, which makes macOS require Touch ID.
Enable it with:
The setting defaults to false and is rejected when enabled on non-macOS
platforms.
Security model
Keychain.
rbw-agentexits, so the first unlock after reboot orrbw stop-agentstill requires the master password.BiometryCurrentSetinvalidates the key if enrolled fingerprints change.protected_keyrevokes thebiometric session. The unlock completion checks that the same session is
still current before restoring keys, covering concurrent revocation.
path.
The Secure Enclave operation runs in a private helper child on its main thread.
The helper has no listening socket and communicates only with its parent over
anonymous pipes. This is necessary because macOS did not reliably present the
authentication UI when Security framework was called from the daemon's Tokio
blocking worker.
Before the parent sends the vault key, the helper must successfully disable
debugger attachment and core dumps and acknowledge that hardened state. Helper
initialization runs off the Tokio worker threads and both handshake phases have
a bounded timeout. The child receives the vault key once to wrap it, then
retains only the Secure Enclave key handle and ciphertext. Plaintext returned
by Security framework is moved immediately into locked memory, its unavoidable
pageable copy is zeroized, and helper pipe I/O bypasses stdio buffering.
Scope and related PRs
This is deliberately narrower than #308: there is no PIN, configurable backend,
persistent state, or new client-agent protocol. It directly addresses the
runtime-only mode suggested by the maintainer in
#308 (comment), while moving the
unlock operation itself into the Secure Enclave as discussed in the follow-up
comment.
It also differs from draft #355: it has no Bitwarden Desktop dependency and
does not use the Desktop browser-integration protocol. The config key is named
touch_id_unlockso the two approaches do not claim the same generic setting.During cancellation testing I reproduced the pre-existing disconnected-client
panic fixed independently by #332; that unrelated change is not included here.
Verification
cargo build --all-targets --all-featurescargo check --all-targets --all-featurescargo test --all-featurescargo test --no-default-featuresRUSTDOCFLAGS=-Dwarnings cargo doc --all-features --no-depscargo fmt --checkgit diff --checkcategories tracked by Fix clippy 1.98 lints #373
master-password unlock ->
rbw lock-> Touch ID unlock -> unlocked stateTouch ID was canceledwithout invoking pinentry;unified logging confirmed
com.apple.LocalAuthenticationcode-2helper creation
session key
rbw stop-agentdestroys the helper and the next agent processrequires the master password again
cargo denywas not available locally. This patch adds no new package toCargo.lock: it only makes the already resolvedsecurity-framework 3.5.1package a direct macOS dependency.