Skip to main content

bitwarden_web_connector/
lib.rs

1#![doc = include_str!("../README.md")]
2
3use std::{fmt, str::FromStr};
4
5use bitwarden_encoding::B64Url;
6use bitwarden_error::bitwarden_error;
7use rand::RngExt;
8use url::{Url, form_urlencoded};
9
10#[cfg(feature = "wasm")]
11pub mod wasm;
12
13const PATTERN: &str = "Noise_NN_P256_AESGCM_SHA256";
14const PROLOGUE_LABEL: &[u8] = b"bitwarden-web-connector";
15const STATE_LEN: usize = 32;
16/// Length of an uncompressed P-256 public key.
17const DH_LEN: usize = 65;
18const TAG_LEN: usize = 16;
19const MAX_MESSAGE_LEN: usize = 65535;
20
21#[allow(missing_docs)]
22#[bitwarden_error(flat)]
23#[derive(Debug, thiserror::Error)]
24pub enum WebConnectorError {
25    #[error("Missing or malformed parameter: {0}")]
26    MalformedParameter(&'static str),
27    #[error("Payload is too large")]
28    PayloadTooLarge,
29    #[error("The callback does not belong to this request")]
30    StateMismatch,
31    #[error("Handshake failed")]
32    Handshake,
33}
34
35/// The flow a request belongs to.
36///
37/// Used for domain separation, so that a response produced for one
38/// connector can't be accepted by a pending request of another.
39#[bitwarden_ffi::wasm_object]
40#[derive(Debug, Clone, Copy, PartialEq, Eq)]
41pub enum Connector {
42    /// WebAuthn assertion in the browser, e.g. for login with passkey.
43    WebAuthnAssertion,
44}
45
46impl Connector {
47    fn id(self) -> &'static str {
48        match self {
49            Self::WebAuthnAssertion => "webauthn-assertion/v1",
50        }
51    }
52
53    fn callback_path(self) -> &'static str {
54        match self {
55            Self::WebAuthnAssertion => "webauthn-callback",
56        }
57    }
58}
59
60/// Random value identifying a pending request, like OAuth2 `state`. The initiator uses it to look
61/// up the [PendingInitiator] when the callback returns.
62#[derive(Clone, PartialEq, Eq, Hash)]
63pub struct State([u8; STATE_LEN]);
64
65impl State {
66    fn generate() -> Self {
67        let mut bytes = [0u8; STATE_LEN];
68        bitwarden_random::rng().fill(&mut bytes);
69        Self(bytes)
70    }
71
72    /// Reads the state from a callback URL, to look up the pending request.
73    pub fn from_callback(callback: &Url) -> Result<Self, WebConnectorError> {
74        param(callback_params(callback), "state")?.parse()
75    }
76}
77
78impl fmt::Display for State {
79    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
80        B64Url::from(self.0.as_slice()).fmt(f)
81    }
82}
83
84impl fmt::Debug for State {
85    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
86        write!(f, "State({self})")
87    }
88}
89
90impl FromStr for State {
91    type Err = WebConnectorError;
92
93    fn from_str(s: &str) -> Result<Self, Self::Err> {
94        let bytes =
95            B64Url::try_from(s).map_err(|_| WebConnectorError::MalformedParameter("state"))?;
96        bytes
97            .as_bytes()
98            .try_into()
99            .map(Self)
100            .map_err(|_| WebConnectorError::MalformedParameter("state"))
101    }
102}
103
104/// Request held by the initiator (the app) until the callback arrives.
105pub struct PendingInitiator {
106    state: State,
107    handshake: snow::HandshakeState,
108}
109
110impl PendingInitiator {
111    /// Starts a request.
112    ///
113    /// Returns the pending request, its [State] for lookup, and the URL to open
114    /// in the browser. `request` is sent in plaintext, but it is authenticated: if it is modified,
115    /// decrypting the response fails.
116    pub fn start(
117        connector: Connector,
118        connector_url: &Url,
119        request: &[u8],
120    ) -> Result<(Self, State, Url), WebConnectorError> {
121        if request.len() > MAX_MESSAGE_LEN - DH_LEN - TAG_LEN {
122            return Err(WebConnectorError::PayloadTooLarge);
123        }
124        let state = State::generate();
125        let mut handshake = handshake_builder(&prologue(connector, &state))
126            .build_initiator()
127            .map_err(|_| WebConnectorError::Handshake)?;
128        // snow reserves room for a tag even though the first message payload is unencrypted.
129        let mut message = vec![0u8; DH_LEN + request.len() + TAG_LEN];
130        let len = handshake
131            .write_message(request, &mut message)
132            .map_err(|_| WebConnectorError::Handshake)?;
133        message.truncate(len);
134
135        let mut url = connector_url.clone();
136        url.set_fragment(Some(
137            &form_urlencoded::Serializer::new(String::new())
138                .append_pair("state", &state.to_string())
139                .append_pair("request", &B64Url::from(message).to_string())
140                .finish(),
141        ));
142        Ok((
143            Self {
144                state: state.clone(),
145                handshake,
146            },
147            state,
148            url,
149        ))
150    }
151
152    /// Decrypts the response from the callback URL.
153    ///
154    /// A failure leaves the request pending, so a forged callback can't cancel it. A request can
155    /// only be completed once; drop it on success, or when it expires.
156    pub fn decrypt_response(&mut self, callback: &Url) -> Result<Vec<u8>, WebConnectorError> {
157        let params = callback_params(callback);
158        if param(params, "state")?.parse::<State>()? != self.state {
159            return Err(WebConnectorError::StateMismatch);
160        }
161        let message = b64_param(params, "response")?;
162        let mut response = vec![0u8; message.len()];
163        let len = self
164            .handshake
165            .read_message(&message, &mut response)
166            .map_err(|_| WebConnectorError::Handshake)?;
167        response.truncate(len);
168        Ok(response)
169    }
170}
171
172/// Request received by the responder (the web page), held while it produces the response.
173pub struct PendingResponder {
174    connector: Connector,
175    state: State,
176    handshake: snow::HandshakeState,
177}
178
179impl PendingResponder {
180    /// Reads a request from the URL fragment of the connector page. Returns the pending request
181    /// and the initiator's request parameters.
182    pub fn read_request(
183        connector: Connector,
184        fragment: &str,
185    ) -> Result<(Self, Vec<u8>), WebConnectorError> {
186        let fragment = fragment.strip_prefix('#').unwrap_or(fragment);
187        let state: State = param(fragment, "state")?.parse()?;
188        let message = b64_param(fragment, "request")?;
189
190        let mut handshake = handshake_builder(&prologue(connector, &state))
191            .build_responder()
192            .map_err(|_| WebConnectorError::Handshake)?;
193        let mut request = vec![0u8; message.len()];
194        let len = handshake
195            .read_message(&message, &mut request)
196            .map_err(|_| WebConnectorError::MalformedParameter("request"))?;
197        request.truncate(len);
198        Ok((
199            Self {
200                connector,
201                state,
202                handshake,
203            },
204            request,
205        ))
206    }
207
208    /// Encrypts the response and returns the callback URL to navigate to. Fails if the
209    /// initiator's public key is not a valid P-256 point.
210    pub fn encrypt_response(mut self, response: &[u8]) -> Result<Url, WebConnectorError> {
211        if response.len() > MAX_MESSAGE_LEN - DH_LEN - TAG_LEN {
212            return Err(WebConnectorError::PayloadTooLarge);
213        }
214        let mut message = vec![0u8; DH_LEN + response.len() + TAG_LEN];
215        let len = self
216            .handshake
217            .write_message(response, &mut message)
218            .map_err(|_| WebConnectorError::Handshake)?;
219        message.truncate(len);
220
221        let params = form_urlencoded::Serializer::new(String::new())
222            .append_pair("state", &self.state.to_string())
223            .append_pair("response", &B64Url::from(message).to_string())
224            .finish();
225        Ok(callback_url(self.connector, &params))
226    }
227}
228
229/// The callback URL is derived from the [Connector] so that the server/browser, not a potential
230/// local attacker, stays in control of where the responses can be sent.
231fn callback_url(connector: Connector, params: &str) -> Url {
232    Url::parse(&format!(
233        "bitwarden://{}#{params}",
234        connector.callback_path()
235    ))
236    .expect("callback URL is valid")
237}
238
239/// Binds the handshake to the connector and the state. Each field is length-prefixed so that
240/// different field splits can't produce the same prologue.
241fn prologue(connector: Connector, state: &State) -> Vec<u8> {
242    let mut prologue = PROLOGUE_LABEL.to_vec();
243    for field in [connector.id().as_bytes(), &state.0] {
244        let len = u16::try_from(field.len()).expect("prologue fields are short");
245        prologue.extend_from_slice(&len.to_be_bytes());
246        prologue.extend_from_slice(field);
247    }
248    prologue
249}
250
251fn handshake_builder(prologue: &[u8]) -> snow::Builder<'_> {
252    snow::Builder::with_resolver(
253        PATTERN.parse().expect("pattern is valid"),
254        Box::new(bitwarden_random::SdkCryptoResolver),
255    )
256    .prologue(prologue)
257    .expect("prologue is only set once")
258}
259
260fn callback_params(callback: &Url) -> &str {
261    callback.fragment().unwrap_or_default()
262}
263
264fn param(params: &str, name: &'static str) -> Result<String, WebConnectorError> {
265    form_urlencoded::parse(params.as_bytes())
266        .find(|(key, _)| key == name)
267        .map(|(_, value)| value.into_owned())
268        .ok_or(WebConnectorError::MalformedParameter(name))
269}
270
271fn b64_param(params: &str, name: &'static str) -> Result<Vec<u8>, WebConnectorError> {
272    B64Url::try_from(param(params, name)?)
273        .map(B64Url::into_bytes)
274        .map_err(|_| WebConnectorError::MalformedParameter(name))
275}
276
277#[cfg(test)]
278mod tests {
279    use super::*;
280
281    const CONNECTOR: Connector = Connector::WebAuthnAssertion;
282
283    fn connector_url() -> Url {
284        Url::parse("https://vault.bitwarden.com/webauthn-connector.html").unwrap()
285    }
286
287    fn start() -> (PendingInitiator, State, Url) {
288        PendingInitiator::start(CONNECTOR, &connector_url(), b"challenge").unwrap()
289    }
290
291    fn respond(request_url: &Url, response: &[u8]) -> Url {
292        let (responder, request) =
293            PendingResponder::read_request(CONNECTOR, request_url.fragment().unwrap()).unwrap();
294        assert_eq!(request, b"challenge");
295        responder.encrypt_response(response).unwrap()
296    }
297
298    #[test]
299    fn round_trip() {
300        let (mut initiator, state, request_url) = start();
301        let callback = respond(&request_url, b"assertion");
302
303        assert!(
304            callback
305                .as_str()
306                .starts_with("bitwarden://webauthn-callback#")
307        );
308        assert_eq!(State::from_callback(&callback).unwrap(), state);
309        assert_eq!(initiator.decrypt_response(&callback).unwrap(), b"assertion");
310    }
311
312    #[test]
313    fn rejects_mismatched_state() {
314        let (mut initiator, _, _) = start();
315        let (_, _, other_request_url) = start();
316        let callback = respond(&other_request_url, b"assertion");
317
318        assert!(matches!(
319            initiator.decrypt_response(&callback),
320            Err(WebConnectorError::StateMismatch)
321        ));
322    }
323
324    #[test]
325    fn tampered_response_leaves_request_pending() {
326        let (mut initiator, state, request_url) = start();
327        let callback = respond(&request_url, b"assertion");
328
329        let mut message = b64_param(callback.fragment().unwrap(), "response").unwrap();
330        *message.last_mut().unwrap() ^= 1;
331        let tampered = callback_url(
332            CONNECTOR,
333            &form_urlencoded::Serializer::new(String::new())
334                .append_pair("state", &state.to_string())
335                .append_pair("response", &B64Url::from(message).to_string())
336                .finish(),
337        );
338
339        assert!(matches!(
340            initiator.decrypt_response(&tampered),
341            Err(WebConnectorError::Handshake)
342        ));
343        assert_eq!(initiator.decrypt_response(&callback).unwrap(), b"assertion");
344    }
345
346    #[test]
347    fn completes_only_once() {
348        let (mut initiator, _, request_url) = start();
349        let callback = respond(&request_url, b"assertion");
350
351        initiator.decrypt_response(&callback).unwrap();
352        assert!(initiator.decrypt_response(&callback).is_err());
353    }
354
355    #[test]
356    fn rejects_invalid_public_key() {
357        let (_, state, _) = start();
358        let fragment = form_urlencoded::Serializer::new(String::new())
359            .append_pair("state", &state.to_string())
360            .append_pair("request", &B64Url::from(vec![4u8; DH_LEN]).to_string())
361            .finish();
362
363        // The point is only validated when the DH is computed.
364        let (responder, _) = PendingResponder::read_request(CONNECTOR, &fragment).unwrap();
365        assert!(matches!(
366            responder.encrypt_response(b"assertion"),
367            Err(WebConnectorError::Handshake)
368        ));
369    }
370}