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}