Expand description
§bitwarden-web-connector
One-shot encrypted response channel for redirect-based flows, where an app opens a web page in the browser and the page returns its result to the app through a callback URL (e.g. login with passkey).
The channel is a Noise NN handshake (Noise_NN_P256_AESGCM_SHA256):
- The app (initiator) calls
PendingInitiator::start, stores thePendingInitiatorby itsState, and opens the returned URL. The request parameters travel in the URL fragment in plaintext, together with the app’s ephemeral public key. - The page (responder) calls
PendingResponder::read_request, uses the request parameters, and navigates to the URL returned byPendingResponder::encrypt_response. - The app reads the
Statefrom the callback, looks up the pending request, and callsPendingInitiator::decrypt_response.
The connector and state are bound into the handshake prologue. The callback URL is always
bitwarden://<connector path>#<response>, derived from the Connector and never supplied by the
request.
On ASWebAuthenticationSession on macOS and iOS, and AuthTabs on Android should be used to open the
connector page, which ensures that the response always goes to the initiating app, even if an
attacker attempts to hijack the bitwarden:// scheme.
On other OSes, the app must be registered as the handler for the bitwarden:// scheme; users
running builds that aren’t installed (e.g. AppImages or local dev builds) must register it
themselves.
Web pages use the responder through WebConnectorResponder in @bitwarden/sdk-internal.
§Threat model
- In scope:
- Passive observers of the request and/or callback URL (other processes and users reading argv, browser history, logs) can’t decrypt the response to a request that the app started.
- A remote attacker who crafts a request URL can’t receive the response, since the callback always leads back to the user’s own device.
- Out of scope:
- A local attacker who can initiate a request and receive encrypted responses locally (e.g. by registering the scheme handler) can decrypt the response. (This would also apply if a browser or OS logs callback responses, but no known implementation does that today.) A local attacker can phish the response from the user.
- An attacker who can read the request can complete with their own response. Consumers must verify
the response (e.g. on the server), and should treat a second callback for the same
Stateas suspicious.
Modules§
- wasm
- WASM bindings for the responder, used by the web vault’s connector pages through
@bitwarden/sdk-internal.
Structs§
- Pending
Initiator - Request held by the initiator (the app) until the callback arrives.
- Pending
Responder - Request received by the responder (the web page), held while it produces the response.
- State
- Random value identifying a pending request, like OAuth2
state. The initiator uses it to look up the PendingInitiator when the callback returns.
Enums§
- Connector
- The flow a request belongs to.
- WebConnector
Error
Constants§
- DH_LEN 🔒
- Length of an uncompressed P-256 public key.
- MAX_
MESSAGE_ 🔒LEN - PATTERN 🔒
- PROLOGUE_
LABEL 🔒 - STATE_
LEN 🔒 - TAG_LEN 🔒
Functions§
- b64_
param 🔒 - callback_
params 🔒 - callback_
url 🔒 - The callback URL is derived from the Connector so that the server/browser, not a potential local attacker, stays in control of where the responses can be sent.
- handshake_
builder 🔒 - param 🔒
- prologue 🔒
- Binds the handshake to the connector and the state. Each field is length-prefixed so that different field splits can’t produce the same prologue.