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;
16const 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#[bitwarden_ffi::wasm_object]
40#[derive(Debug, Clone, Copy, PartialEq, Eq)]
41pub enum Connector {
42 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#[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 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
104pub struct PendingInitiator {
106 state: State,
107 handshake: snow::HandshakeState,
108}
109
110impl PendingInitiator {
111 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 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 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
172pub struct PendingResponder {
174 connector: Connector,
175 state: State,
176 handshake: snow::HandshakeState,
177}
178
179impl PendingResponder {
180 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 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, ¶ms))
226 }
227}
228
229fn 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
239fn 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 let (responder, _) = PendingResponder::read_request(CONNECTOR, &fragment).unwrap();
365 assert!(matches!(
366 responder.encrypt_response(b"assertion"),
367 Err(WebConnectorError::Handshake)
368 ));
369 }
370}