Crate bitwarden_shared_unlock

Expand description

§Shared Unlock Protocol

Synchronizes vault lock state across multiple Bitwarden clients (web, browser extension, desktop) running in the same session. When a user unlocks their vault on one client, the unlock propagates to all connected clients.

§Peer Model

Every client runs exactly one SharedUnlockPeer. Each peer knows the one peer above it in the device hierarchy — its leader — and syncs to it, while also serving whichever peers sync to it:

  Web Client  ──syncs to──▶  Browser Extension  ──syncs to──▶  Desktop App
  CLI Client  ──syncs to──▶  Desktop App

The hierarchy decides who talks to whom, not who is in charge. There is no authoritative participant: reconciliation is symmetric and the freshest state wins. A peer in the middle of the chain relays simply by applying what it hears and advertising what it holds — the browser extension needs no special handling for leading the web vault while following the desktop app.

The desktop app is the only client with no leader; it exclusively serves.

§Messages

There is one message, SharedUnlockSync, carrying a user id and that device’s TimestampedLockState. It is sent in both directions.

A peer sends one sync per logged-in user, to its leader and to every active peer:

immediately on SharedUnlockPeer::start, so it does not wait an interval to be discovered,
on every DeviceEvent, so a manual lock or unlock propagates without delay, and
every SYNC_INTERVAL.
as a reply to first sync connection

  Peer                                      Peer above (leader)
    │                                          │
    │──Sync(user, state@date)─────────────────▶│  on start, on device event, every interval
    │                                          │  · applies the state if the date is newer
    │                                          │  · registers the sender as an active peer
    │                                          │
    │◀─Sync(user, state@date)──────────────────│  once on first contact, then on device
    │  · applies the state if the date is newer │  events and every interval
    │  · suppresses its vault timeout           │

§Reconciliation

On receiving a sync, a peer:

Drops it if the source is a web client whose origin does not match the user’s vault URL. The origin that passed this check is kept with the peer, and the same check is applied again on the way out (see Origin scoping).
Drops it if the user is not in SharedUnlockDriver::list_users — that is how a peer knows it has no account for a user, and it never advertises such a user either.
Drops it if changed_at is older than the date this device has recorded. A user this device has recorded nothing for counts as date 0.
On an equal date, drops it unless it is a Locked arriving at an unlocked device. Equal dates mean two devices acted inside the same millisecond without having seen each other, so the tie is broken toward Locked: both sides then resolve it identically and converge without another round, and the ambiguous case fails closed rather than resurrecting an unlock.
Otherwise records the incoming state and its date, and calls SharedUnlockDriver::lock_user or SharedUnlockDriver::unlock_user if — and only if — the state actually differs from what was recorded.

§Origin scoping

A web peer is scoped to one origin, in both directions:

an incoming sync from a web source is dropped unless its origin is the vault URL of the user it carries, and
an outgoing sync is withheld from a web peer unless the user’s vault URL is the origin that peer was registered with — which covers the introductory reply on first contact as much as the periodic and device-event syncs.

§Keep-alive

A sync received from this peer’s leader also calls SharedUnlockDriver::suppress_vault_timeout for SYNC_INTERVAL plus VAULT_TIMEOUT_GRACE_PERIOD, keeping the vault unlocked as long as the shared session is active. Syncs from peers below do not suppress anything; they only mark the sender active.

Peers that have not been heard from in PEER_STALE_AFTER are pruned and stop being synced to.

§Security Definitions

Attacker Model:
- Attacker gains user-space access to the device while the vault has been locked (steals the device)
Security Goal:
- Attacker cannot gain access to the vault key material

This security definition is aimed at stolen or seized devices. Forensics should not uncover (passively) recorded or otherwise left behind key material. The IPC encryption prevents such a compromise.

There is no further protection provided against active attackers running in userspace while the vault is unlocked on any of the clients on the device.

Attacker Model:
- Attacker controls a website that is not the web vault
Security Goal:
- Attacker cannot gain access to the vault key material

This is met by origin validation, which is enforced on both the receive and the send path — see Origin scoping. Validating only what arrives would not meet the goal: a peer that is registered after one validated sync goes on to be sent every user’s state.

Modules§

active_peers 🔒: Liveness tracking for the peers that sync to this one.
drivers 🔒: Drivers that need to be implemented per platform for the shared unlock system.
message 🔒: The protocol’s single message, and the timestamped lock state it carries.
peer 🔒: The single participant type of the shared unlock protocol.
timing 🔒: How often a peer syncs, and the clock its dates come from.
wasm: Wasm support module for shared unlock

Structs§

PeerStartError: Error type for failure to start a shared unlock peer.
SharedUnlockPeer: One participant in the shared unlock protocol.
SharedUnlockSync: The only message in the protocol, sent in both directions.
TimestampedLockState: A user’s lock state, together with when the reporting device entered it.

Enums§

DeviceEvent: The device (client) has several events that need to be reported to the shared unlock system. This enum represents the events that need to be reported.
LockState: Represents the lock state of a user.
SharedUnlockClient: A kind of client a peer may share unlock state with, independent of the IPC endpoint variants that address its individual contexts (foreground/background, renderer/main).

Constants§

PEER_STALE_AFTER: How long a peer may go without syncing before it is pruned and no longer synced to.
SYNC_INTERVAL: Interval at which a peer syncs its lock state to its leader and to its active peers.
VAULT_TIMEOUT_GRACE_PERIOD: Additional grace period added to the vault timeout when suppressing it on a sync from the leader.

Traits§

SharedUnlockDriver: Trait that implmeents the device’s shared unlock driver. These functions need to be implemented in order to allow the shared unlock system to function.