Skip to content

Your Android phone and your Windows PC, working as one. Local-first, end-to-end encrypted, no account.

8.3 KB
Raw Blame
// SPDX-License-Identifier: MPL-2.0
//! Pairing primitives (protocol §9): the QR pairing URI, the pairing proof,
//! and the numeric-comparison commitment and short authentication string.

use std::net::SocketAddr;

use data_encoding::BASE64URL_NOPAD;
use hmac::{Hmac, KeyInit, Mac};
use sha2::{Digest, Sha256};
use url::Url;

use crate::DeviceId;

type HmacSha256 = Hmac<Sha256>;

/// Length of the one-time pairing secret in the QR code (128 bits).
pub const SECRET_LEN: usize = 16;
/// Length of the nonces used in the nearby (numeric comparison) flow.
pub const NONCE_LEN: usize = 16;

const PROOF_LABEL: &[u8] = b"nectarlink-pair-v0";
const SAS_LABEL: &[u8] = b"nectarlink-sas-v0";

/// Contents of the pairing QR code shown by the PC.
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct PairingUri {
    pub id: DeviceId,
    pub secret: [u8; SECRET_LEN],
    pub name: String,
    pub addrs: Vec<SocketAddr>,
}

#[derive(Debug, thiserror::Error, PartialEq, Eq)]
pub enum PairingUriError {
    #[error("not a NectarLink pairing link")]
    NotPairing,
    #[error("pairing link version {0} is not supported; please update NectarLink")]
    UnsupportedVersion(String),
    #[error("pairing link is missing {0}")]
    Missing(&'static str),
    #[error("pairing link has an invalid {0}")]
    Invalid(&'static str),
}

impl PairingUri {
    /// `nectarlink://pair?v=0&id=…&s=…&n=…[&a=ip:port,…]`
    pub fn to_uri(&self) -> String {
        let mut url = Url::parse("nectarlink://pair").expect("static URL");
        {
            let mut q = url.query_pairs_mut();
            q.append_pair("v", "0");
            q.append_pair("id", &self.id.to_string());
            q.append_pair("s", &BASE64URL_NOPAD.encode(&self.secret));
            q.append_pair("n", &self.name);
            if !self.addrs.is_empty() {
                let addrs: Vec<String> = self.addrs.iter().map(ToString::to_string).collect();
                q.append_pair("a", &addrs.join(","));
            }
        }
        url.into()
    }

    pub fn parse(uri: &str) -> Result<Self, PairingUriError> {
        let url = Url::parse(uri.trim()).map_err(|_| PairingUriError::NotPairing)?;
        if url.scheme() != "nectarlink" || url.host_str() != Some("pair") {
            return Err(PairingUriError::NotPairing);
        }
        let get = |key: &str| url.query_pairs().find(|(k, _)| k == key).map(|(_, v)| v.into_owned());

        let version = get("v").ok_or(PairingUriError::Missing("version"))?;
        if version != "0" {
            return Err(PairingUriError::UnsupportedVersion(version));
        }
        let id = get("id")
            .ok_or(PairingUriError::Missing("device ID"))?
            .parse()
            .map_err(|_| PairingUriError::Invalid("device ID"))?;
        let secret: [u8; SECRET_LEN] = BASE64URL_NOPAD
            .decode(get("s").ok_or(PairingUriError::Missing("secret"))?.as_bytes())
            .ok()
            .and_then(|b| b.try_into().ok())
            .ok_or(PairingUriError::Invalid("secret"))?;
        let name = get("n").unwrap_or_default();
        let addrs = match get("a") {
            None => Vec::new(),
            Some(list) => list
                .split(',')
                .filter(|s| !s.is_empty())
                .map(|s| s.parse().map_err(|_| PairingUriError::Invalid("address")))
                .collect::<Result<_, _>>()?,
        };
        Ok(PairingUri { id, secret, name, addrs })
    }
}

fn proof_mac(secret: &[u8; SECRET_LEN], joining: &DeviceId, host: &DeviceId) -> HmacSha256 {
    let mut mac = HmacSha256::new_from_slice(secret).expect("HMAC accepts any key length");
    mac.update(PROOF_LABEL);
    mac.update(joining.as_bytes());
    mac.update(host.as_bytes());
    mac
}

/// Proof that the joining device (phone) scanned the host's (PC's) QR code:
/// `HMAC-SHA256(S, "nectarlink-pair-v0" || joining_id || host_id)`.
pub fn pair_proof(secret: &[u8; SECRET_LEN], joining: &DeviceId, host: &DeviceId) -> [u8; 32] {
    proof_mac(secret, joining, host).finalize().into_bytes().into()
}

/// Verifies a pairing proof in constant time.
pub fn verify_pair_proof(
    secret: &[u8; SECRET_LEN],
    joining: &DeviceId,
    host: &DeviceId,
    proof: &[u8],
) -> bool {
    proof_mac(secret, joining, host).verify_slice(proof).is_ok()
}

/// Commitment to the initiator's nonce: `SHA-256(nA)`.
pub fn commitment(n_a: &[u8]) -> [u8; 32] {
    Sha256::digest(n_a).into()
}

/// Checks a revealed nonce against its commitment.
pub fn verify_commitment(commitment_bytes: &[u8], n_a: &[u8]) -> bool {
    let expected = commitment(n_a);
    // Not secret, but compare without early exit anyway.
    commitment_bytes.len() == expected.len()
        && commitment_bytes.iter().zip(expected).fold(0u8, |acc, (a, b)| acc | (a ^ b)) == 0
}

/// The 6-digit short authentication string both screens show:
/// `uint32(HMAC-SHA256(nA || nB, "nectarlink-sas-v0" || idA || idB)[0..4]) mod 1,000,000`,
/// where A is the initiator and B the responder.
pub fn sas_code(n_a: &[u8], n_b: &[u8], id_a: &DeviceId, id_b: &DeviceId) -> String {
    let mut key = Vec::with_capacity(n_a.len() + n_b.len());
    key.extend_from_slice(n_a);
    key.extend_from_slice(n_b);
    let mut mac = HmacSha256::new_from_slice(&key).expect("HMAC accepts any key length");
    mac.update(SAS_LABEL);
    mac.update(id_a.as_bytes());
    mac.update(id_b.as_bytes());
    let digest = mac.finalize().into_bytes();
    let value = u32::from_be_bytes([digest[0], digest[1], digest[2], digest[3]]) % 1_000_000;
    format!("{value:06}")
}

#[cfg(test)]
mod tests {
    use super::*;

    fn id(b: u8) -> DeviceId {
        DeviceId([b; 32])
    }

    #[test]
    fn uri_round_trips() {
        let uri = PairingUri {
            id: id(3),
            secret: [9; SECRET_LEN],
            name: "Bee's Desktop".into(),
            addrs: vec!["192.168.1.20:41641".parse().unwrap(), "[fe80::1]:41641".parse().unwrap()],
        };
        let text = uri.to_uri();
        assert!(text.starts_with("nectarlink://pair?v=0&id="));
        assert_eq!(PairingUri::parse(&text).unwrap(), uri);
    }

    #[test]
    fn uri_without_addresses() {
        let uri = PairingUri { id: id(1), secret: [0; SECRET_LEN], name: String::new(), addrs: vec![] };
        assert_eq!(PairingUri::parse(&uri.to_uri()).unwrap(), uri);
    }

    #[test]
    fn uri_errors() {
        assert_eq!(PairingUri::parse("https://example.com"), Err(PairingUriError::NotPairing));
        assert_eq!(
            PairingUri::parse("nectarlink://pair?v=9&id=x&s=y"),
            Err(PairingUriError::UnsupportedVersion("9".into()))
        );
        assert_eq!(
            PairingUri::parse("nectarlink://pair?v=0&s=AAAA"),
            Err(PairingUriError::Missing("device ID"))
        );
        let good =
            PairingUri { id: id(1), secret: [0; SECRET_LEN], name: "x".into(), addrs: vec![] }.to_uri();
        let bad_secret = good.replace("s=AAAAAAAAAAAAAAAAAAAAAA", "s=AAAA");
        assert_eq!(PairingUri::parse(&bad_secret), Err(PairingUriError::Invalid("secret")));
    }

    #[test]
    fn proof_binds_secret_and_both_ids() {
        let secret = [5u8; SECRET_LEN];
        let proof = pair_proof(&secret, &id(1), &id(2));
        assert!(verify_pair_proof(&secret, &id(1), &id(2), &proof));
        assert!(!verify_pair_proof(&[6u8; SECRET_LEN], &id(1), &id(2), &proof), "wrong secret");
        assert!(!verify_pair_proof(&secret, &id(9), &id(2), &proof), "wrong joining device");
        assert!(!verify_pair_proof(&secret, &id(1), &id(9), &proof), "wrong host");
        assert!(!verify_pair_proof(&secret, &id(1), &id(2), &proof[..31]), "truncated");
    }

    #[test]
    fn commitment_checks() {
        let n_a = [1u8; NONCE_LEN];
        let c = commitment(&n_a);
        assert!(verify_commitment(&c, &n_a));
        assert!(!verify_commitment(&c, &[2u8; NONCE_LEN]));
        assert!(!verify_commitment(&c[..10], &n_a));
    }

    #[test]
    fn sas_is_six_digits_and_order_sensitive() {
        let (n_a, n_b) = ([1u8; NONCE_LEN], [2u8; NONCE_LEN]);
        let code = sas_code(&n_a, &n_b, &id(1), &id(2));
        assert_eq!(code.len(), 6);
        assert!(code.chars().all(|c| c.is_ascii_digit()));
        assert_eq!(code, sas_code(&n_a, &n_b, &id(1), &id(2)), "deterministic");
        // A man in the middle presents a different identity on one side.
        assert_ne!(code, sas_code(&n_a, &n_b, &id(1), &id(3)));
        assert_ne!(code, sas_code(&n_b, &n_a, &id(1), &id(2)));
    }
}