Device pairing protocol.

Cargo.toml

@@ -2,7 +2,7 @@
 name = "sos"
 version = "0.9.0"
 edition = "2021"
-rust-version = "1.68.2"
+rust-version = "1.75.0"
 description = "Distributed, encrypted database for private secrets."
 homepage = "https://saveoursecrets.com"
 license = "MIT OR Apache-2.0"

doc/sync.md

@@ -97,6 +97,35 @@ deny = [
 ]
 ```
 
+## Device Pairing
+
+Adding a new device to an existing account consists of a device that is already authenticated to the account which we call the **offering device** and another device which is not authenticated called the **accepting device**.
+
+Pairing the devices is performed using an untrusted relay server. Communication between the devices exposes sensitive information (the account signing key) which must not be exposed to the server so device pairing uses the [noise protocol](https://noiseprotocol.org/) to ensure the communication between the devices is private. The protocol includes a pre-shared symmetric key in the **sharing URL** so that the server cannot forge client connections.
+
+The **sharing URL** needs to be transferred between the offering device and the accepting device; this can be done by scanning a QR code or typing in the URL. The **sharing URL** uses the `data:` scheme to differentiate from the HTTP/S schemes.
+
+### Pairing Protocol
+
+1) Offering device generates a noise protocol session keypair and encodes the relay server URL and noise protocol public key in a **pairing URL** that can be shared with the accepting device.
+2) Once the **pairing URL** has been received by the accepting device it begins the noise protocol handshake.
+3) After completing the noise protocol handshake the accepting device encrypts and sends a **trusted device** to the offering side. The **trusted device** contains meta data about the device and the public key of the device's signing key.
+4) When the offering device receives the **trusted device** it updates the server(s) to trust the new device and sends the encrypted account signing key in reply.
+5) The pairing protocol is complete when the accepting device receives the account signing key.
+
+### Device Enrollment
+
+Once the pairing protocol is finished the accepting device can perform device enrollment as it has both the account signing key and a device signing key whose public key has been added as a trusted device to the server(s).
+
+1) Fetch account event logs and write the account to disc.
+2) Finish device enrollment by authenticating to the account using the primary password.
+
+## Device Revocation
+
+If a device is lost or stolen the device can be revoked which will remove the device from the list of trusted devices preventing it from syncing with servers.
+
+Whilst server endpoints will return a **forbidden** response for untrusted device signatures; if the lost or stolen device was unlocked and the account was authenticated the owner must consider all of their secrets compromised.
+
 ## Event Logs
 
 Several events logs are stored on both the client and server so that complete deterministic, incremental synchronization is possible for an account.

tests/device_revoke/main.rs → tests/pairing/main.rs

@@ -1,5 +1,8 @@
 #[cfg(not(target_arch = "wasm32"))]
-mod revoke;
+mod pairing_protocol;
+
+#[cfg(not(target_arch = "wasm32"))]
+mod pairing_websocket_shutdown;
 
 #[cfg(not(target_arch = "wasm32"))]
 pub use sos_test_utils as test_utils;

tests/device_enroll/enroll.rs → tests/pairing/pairing_protocol.rs

@@ -1,18 +1,14 @@
-use anyhow::Result;
-
 use crate::test_utils::{
-    assert_local_remote_events_eq, mock, simulate_device, spawn, teardown,
-};
-use sos_net::{
-    client::{NetworkAccount, RemoteSync},
-    sdk::prelude::*,
+    assert_local_remote_events_eq, mock, run_pairing_protocol,
+    simulate_device, spawn, teardown,
 };
+use anyhow::Result;
+use sos_net::{client::RemoteSync, sdk::prelude::*};
 
-/// Tests enrolling a new device and syncing the device event log
-/// including the newly enrolled device back on to a primary device.
+/// Tests the protocol for pairing devices.
 #[tokio::test]
-async fn device_enroll() -> Result<()> {
-    const TEST_ID: &str = "device_enroll";
+async fn pairing_protocol() -> Result<()> {
+    const TEST_ID: &str = "pairing_protocol";
     //crate::test_utils::init_tracing();
 
     // Spawn a backend server and wait for it to be listening
@@ -21,6 +17,8 @@ async fn device_enroll() -> Result<()> {
     // Prepare mock devices
     let mut primary_device =
         simulate_device(TEST_ID, 2, Some(&server)).await?;
+    let origin = primary_device.origin.clone();
+    let folders = primary_device.folders.clone();
 
     // Create a secret in the primary owner which won't exist
     // in the second device
@@ -31,31 +29,9 @@ async fn device_enroll() -> Result<()> {
         .await?;
     assert!(result.sync_error.is_none());
 
-    let password = primary_device.password.clone();
-    let key: AccessKey = password.into();
-    let origin = primary_device.origin.clone();
-    let signing_key = primary_device.owner.account_signer().await?;
-    let data_dir = primary_device.dirs.clients.get(1).cloned().unwrap();
-    let folders = primary_device.folders.clone();
-
-    // Need to clear the data directory for the second client
-    // as simulate_device() copies all the account data and
-    // the identity folder must not exist to enroll a new device
-    std::fs::remove_dir_all(&data_dir)?;
-    std::fs::create_dir(&data_dir)?;
-
-    // Start enrollment by fetching the account data
-    // from the remote server
-    let enrollment = NetworkAccount::enroll_device(
-        origin.clone(),
-        signing_key,
-        Some(data_dir),
-    )
-    .await?;
-
-    // Complete device enrollment by authenticating
-    // to the new account
-    let mut enrolled_account = enrollment.finish(&key).await?;
+    // Run the pairing protocol to completion.
+    let mut enrolled_account =
+        run_pairing_protocol(&mut primary_device, TEST_ID).await?;
 
     // Sync on the original device to fetch the updated device logs
     assert!(primary_device.owner.sync().await.is_none());
@@ -92,6 +68,7 @@ async fn device_enroll() -> Result<()> {
     )
     .await?;
 
+    // Sign out all devices
     primary_device.owner.sign_out().await?;
     enrolled_account.sign_out().await?;
 

tests/pairing/pairing_websocket_shutdown.rs

@@ -0,0 +1,58 @@
+use crate::test_utils::{simulate_device, spawn, teardown};
+use anyhow::Result;
+use futures::{stream::FuturesUnordered, Future, StreamExt};
+use sos_net::{
+    client::pairing::{self, OfferPairing},
+    sdk::prelude::*,
+};
+use std::pin::Pin;
+use tokio::sync::mpsc;
+
+/// Tests shutting down the websocket for an
+/// offer side of the pairing protocol.
+#[tokio::test]
+async fn pairing_websocket_shutdown() -> Result<()> {
+    const TEST_ID: &str = "pairing_websocket_shutdown";
+    //crate::test_utils::init_tracing();
+
+    // Spawn a backend server and wait for it to be listening
+    let server = spawn(TEST_ID, None, None).await?;
+
+    // Prepare mock devices
+    let mut primary_device =
+        simulate_device(TEST_ID, 2, Some(&server)).await?;
+    let origin = primary_device.origin.clone();
+
+    {
+        // Create the offer of device pairing
+        let (mut offer, offer_stream) = OfferPairing::new(
+            &mut primary_device.owner,
+            origin.url().clone(),
+        )
+        .await?;
+
+        let (offer_shutdown_tx, offer_shutdown_rx) = mpsc::channel::<()>(1);
+
+        // Run both sides of the protocol to completion
+        let mut tasks = FuturesUnordered::<
+            Pin<Box<dyn Future<Output = pairing::Result<()>>>>,
+        >::new();
+
+        tasks.push(Box::pin(offer.run(offer_stream, offer_shutdown_rx)));
+        tasks.push(Box::pin(async move {
+            tokio::time::sleep(std::time::Duration::from_millis(50)).await;
+            offer_shutdown_tx.send(()).await.unwrap();
+            Ok(())
+        }));
+
+        while let Some(result) = tasks.next().await {
+            result?;
+        }
+    }
+
+    primary_device.owner.sign_out().await?;
+
+    teardown(TEST_ID).await;
+
+    Ok(())
+}

tests/device_revoke/revoke.rs → tests/pairing_revoke/device_revoke.rs

@@ -1,18 +1,18 @@
-use anyhow::Result;
-
 use crate::test_utils::{
-    assert_local_remote_events_eq, simulate_device, spawn, teardown,
+    assert_local_remote_events_eq, run_pairing_protocol, simulate_device,
+    spawn, teardown,
 };
+use anyhow::Result;
 use http::StatusCode;
 use sos_net::{
-    client::{Error as ClientError, NetworkAccount, RemoteSync, SyncError},
+    client::{Error as ClientError, RemoteSync, SyncError},
     sdk::prelude::*,
 };
 
-/// Tests enrolling a new device and revoking trust in the device.
+/// Tests pairing a new device and revoking trust in the device.
 #[tokio::test]
-async fn device_revoke() -> Result<()> {
-    const TEST_ID: &str = "device_revoke";
+async fn pairing_device_revoke() -> Result<()> {
+    const TEST_ID: &str = "pairing_device_revoke";
     //crate::test_utils::init_tracing();
 
     // Spawn a backend server and wait for it to be listening
@@ -21,19 +21,11 @@ async fn device_revoke() -> Result<()> {
     // Prepare mock devices
     let mut primary_device =
         simulate_device(TEST_ID, 2, Some(&server)).await?;
-
-    let password = primary_device.password.clone();
-    let key: AccessKey = password.into();
     let origin = primary_device.origin.clone();
-    let signing_key = primary_device.owner.account_signer().await?;
-    let data_dir = primary_device.dirs.clients.get(1).cloned().unwrap();
     let folders = primary_device.folders.clone();
 
-    // Need to clear the data directory for the second client
-    // as simulate_device() copies all the account data and
-    // the identity folder must not exist to enroll a new device
-    std::fs::remove_dir_all(&data_dir)?;
-    std::fs::create_dir(&data_dir)?;
+    let mut enrolled_account =
+        run_pairing_protocol(&mut primary_device, TEST_ID).await?;
 
     // Cannot revoke the current device
     let current_device_public_key = primary_device
@@ -48,19 +40,6 @@ async fn device_revoke() -> Result<()> {
         .await;
     assert!(matches!(result, Err(ClientError::RevokeDeviceSelf)));
 
-    // Start enrollment by fetching the account data
-    // from the remote server
-    let enrollment = NetworkAccount::enroll_device(
-        origin.clone(),
-        signing_key,
-        Some(data_dir),
-    )
-    .await?;
-
-    // Complete device enrollment by authenticating
-    // to the new account
-    let mut enrolled_account = enrollment.finish(&key).await?;
-
     // Sync on the original device to fetch the updated device logs
     assert!(primary_device.owner.sync().await.is_none());
 
@@ -71,10 +50,11 @@ async fn device_revoke() -> Result<()> {
         .owner
         .revoke_device(&device_public_key)
         .await?;
-
-    let revoke_error = enrolled_account.revoke_device(
-        &current_device_public_key).await;
-
+
+    let revoke_error = enrolled_account
+        .revoke_device(&current_device_public_key)
+        .await;
+
     if let Err(ClientError::RevokeDeviceSync(mut e)) = revoke_error {
         let (_, err) = e.errors.remove(0);
         assert!(matches!(

tests/device_enroll/main.rs → tests/pairing_revoke/main.rs

@@ -1,5 +1,5 @@
 #[cfg(not(target_arch = "wasm32"))]
-mod enroll;
+mod device_revoke;
 
 #[cfg(not(target_arch = "wasm32"))]
 pub use sos_test_utils as test_utils;

workspace/net/Cargo.toml

@@ -18,6 +18,7 @@ full = [
   "hashcheck",
   "listen",
   "migrate",
+  "pairing",
   "preferences",
   "search",
   "server",
@@ -49,6 +50,7 @@ migrate = ["sos-sdk/migrate"]
 keychain-access = ["sos-sdk/keychain-access"]
 device = ["sos-sdk/device"]
 recovery = ["sos-sdk/recovery"]
+pairing = ["dep:snow"]
 preferences = ["sos-sdk/preferences"]
 search = ["sos-sdk/search"]
 security-report = ["sos-sdk/security-report"]
@@ -93,6 +95,9 @@ tokio-tungstenite = { version = "0.21", features = ["rustls-tls-native-roots"] ,
 utoipa = { version = "4", features = ["uuid"], optional = true }
 utoipa-rapidoc = { version = "3", features = ["axum"], optional = true }
 
+# pairing
+snow = { version = "0.9", optional = true }
+
 [dependencies.sos-sdk]
 version = "0.9.0"
 features = ["sync"]

workspace/net/src/client/account/network_account.rs

@@ -103,20 +103,22 @@ pub struct NetworkAccount {
 
 impl NetworkAccount {
     /// Enroll a new device.
-    #[cfg(feature = "device")]
+    #[cfg(all(feature = "device", feature = "pairing"))]
     pub async fn enroll_device(
         origin: Origin,
         account_signing_key: BoxedEcdsaSigner,
+        device_signer: DeviceSigner,
         data_dir: Option<PathBuf>,
-    ) -> Result<crate::client::enrollment::DeviceEnrollment> {
-        use crate::client::{enrollment::DeviceEnrollment, HttpClient};
+    ) -> Result<crate::client::pairing::DeviceEnrollment> {
+        use crate::client::{pairing::DeviceEnrollment, HttpClient};
         use crate::sdk::signer::ed25519::BoxedEd25519Signer;
 
         let address = account_signing_key.address()?;
         let mut enrollment = DeviceEnrollment::new(
             &address,
-            data_dir.clone(),
             origin.clone(),
+            device_signer,
+            data_dir.clone(),
         )?;
         let device_signing_key = enrollment.device_signing_key.clone();
         let device: BoxedEd25519Signer = device_signing_key.into();
@@ -128,7 +130,6 @@ impl NetworkAccount {
         )?;
 
         enrollment.enroll(remote).await?;
-
         Ok(enrollment)
     }
 

workspace/net/src/client/account/remote.rs

@@ -108,7 +108,7 @@ impl RemoteBridge {
             let account = self.account.lock().await;
             sync::diff(&*account, remote_status).await?
         };
-        
+
         // If we need a sync but no local device changes
         // try to pull from remote
         if let (true, None) = (needs_sync, &local_changes.device) {

workspace/net/src/client/error.rs

@@ -75,6 +75,7 @@ pub enum Error {
     RevokeDeviceSync(SyncError<Error>),
 
     /// Error generated trying to parse a device enrollment sharing URL.
+    #[deprecated]
     #[error("invalid share url for device enrollment")]
     InvalidShareUrl,