Skip to main content

umbera_core/devlink/
mod.rs

1// umbera_core::devlink — linked devices (desktop ↔ phone), core cryptography.
2//
3// Overview (see the protocol description for formats and design decisions):
4//  * session  — QR linking: one-time desktop keys (X25519 + ML-KEM-1024), hybrid
5//               key agreement, HKDF bound to the transcript, verification code (6 digits),
6//               key confirmation in both directions, replay-free AEAD blobs {kind, seq, data};
7//  * cert     — long-term device identity (Ed25519 + ML-DSA-65 for signing,
8//               X25519 + ML-KEM-1024 for encryption), a "this device belongs to my
9//               account" certificate signed with the account key (secp256k1 + ML-DSA-65), and revocation;
10//  * package  — transfer bundle in chunks (AEAD per chunk, final checksum, strict limits:
11//               videos and large files are not transferred);
12//  * comm     — Communities membership vault root (no account private keys);
13//  * mlsjoin  — every device is a separate leaf of an MLS group (requests, offers,
14//               mutual signature of "sibling" leaves).
15//
16// Only vetted crates the core already uses (x25519-dalek, ml-kem, ml-dsa,
17// ed25519-dalek, k256, aes-gcm, hkdf, hmac, sha2). No custom cryptography here — only
18// composition of standard primitives and format parsing.
19
20pub mod cert;
21pub mod comm;
22pub mod mlsjoin;
23pub mod package;
24pub mod session;
25
26mod codec;
27
28#[cfg(test)]
29mod tests;
30
31/// Linking errors. Each variant has exactly one string field (iOS binding contract:
32/// variant ordinal + string). Variant order is part of the ABI, do not change it.
33#[derive(Debug, thiserror::Error, uniffi::Error)]
34pub enum LinkError {
35    /// Malformed input: wrong QR, truncated blob, trailing bytes, lengths.
36    #[error("malformed: {0}")]
37    Malformed(String),
38    /// Expired: QR older than 60 s, verification code not confirmed in time.
39    #[error("expired: {0}")]
40    Expired(String),
41    /// Mismatch: key confirmation, ML-KEM commitment, signature, AEAD, final
42    /// checksum. Indicates tampering — the session is destroyed afterwards.
43    #[error("mismatch: {0}")]
44    Mismatch(String),
45    /// Replay of an already accepted blob (seq lower than expected). The session is unchanged.
46    #[error("replay: {0}")]
47    Replay(String),
48    /// Call in the wrong session state (or the session is already destroyed).
49    #[error("state: {0}")]
50    State(String),
51    /// Primitive error (wrong key length, etc.).
52    #[error("crypto: {0}")]
53    Crypto(String),
54}
55
56pub type LR<T> = Result<T, LinkError>;
57
58impl From<crate::primitives::PrimitiveError> for LinkError {
59    fn from(e: crate::primitives::PrimitiveError) -> Self {
60        LinkError::Crypto(e.to_string())
61    }
62}
63
64/// Prefix of all protocol domain labels (HKDF info, signatures, AAD).
65pub(crate) const DOMAIN: &[u8] = b"umbera-link-v1";
66
67/// Constant-time comparison (for MACs, commitments and checksums).
68pub(crate) fn ct_eq(a: &[u8], b: &[u8]) -> bool {
69    if a.len() != b.len() {
70        return false;
71    }
72    let mut d = 0u8;
73    for (x, y) in a.iter().zip(b) {
74        d |= x ^ y;
75    }
76    // black_box keeps the compiler from turning the loop into an early exit.
77    std::hint::black_box(d) == 0
78}
79
80pub(crate) fn sha256(parts: &[&[u8]]) -> [u8; 32] {
81    use sha2::{Digest, Sha256};
82    let mut h = Sha256::new();
83    for p in parts {
84        h.update(p);
85    }
86    h.finalize().into()
87}
88
89/// SHA-256 over parts, each prefixed with a 4-byte length: unambiguous concatenation.
90pub(crate) fn sha256_framed(parts: &[&[u8]]) -> [u8; 32] {
91    use sha2::{Digest, Sha256};
92    let mut h = Sha256::new();
93    for p in parts {
94        h.update((p.len() as u32).to_be_bytes());
95        h.update(p);
96    }
97    h.finalize().into()
98}