718 lines
28 KiB
Rust
718 lines
28 KiB
Rust
//! Cryptography shared between the relay, the mobile-connector plugin, and the
|
|
//! reference vector generator (see plugin.md §1.1, crypto.md).
|
|
//!
|
|
//! Two layers live here:
|
|
//!
|
|
//! 1. **Relay subset** — the relay only ever verifies the Ed25519
|
|
//! challenge-response signature (crypto.md §8) and derives the `namespace_id`
|
|
//! (crypto.md §7). It never touches X25519/AEAD.
|
|
//! 2. **End-to-end suite** — key derivation from a seed, X25519 ECDH, the
|
|
//! HKDF → `aes_key` step, AES-256-GCM seal/open, and nonce construction
|
|
//! (crypto.md §3-6). These are used by the plugin (and by `gen-vectors`) so
|
|
//! that every Rust consumer produces byte-identical output to the reference
|
|
//! vectors in test-vectors.md.
|
|
|
|
use aes_gcm::aead::{Aead, Payload};
|
|
use aes_gcm::{Aes256Gcm, KeyInit, Nonce};
|
|
use ed25519_dalek::{Signature, Signer, SigningKey, VerifyingKey};
|
|
use flate2::Compression;
|
|
use flate2::read::ZlibDecoder;
|
|
use flate2::write::ZlibEncoder;
|
|
use hkdf::Hkdf;
|
|
use sha2::{Digest, Sha256};
|
|
use std::io::{Read, Write};
|
|
use subtle::ConstantTimeEq;
|
|
use x25519_dalek::{PublicKey, StaticSecret};
|
|
|
|
// ---------------------------------------------------------------------------
|
|
// Domain constants (crypto.md §1). These MUST stay byte-identical across all
|
|
// implementations — changing one invalidates the protocol and the vectors.
|
|
// ---------------------------------------------------------------------------
|
|
|
|
/// Challenge-response signing domain (crypto.md §1, `AUTH_DOMAIN`).
|
|
pub const AUTH_DOMAIN: &[u8] = b"skald-relay-auth-v1";
|
|
/// Namespace derivation domain (crypto.md §1, `NS_DOMAIN`).
|
|
pub const NS_DOMAIN: &[u8] = b"skald-namespace-v1";
|
|
/// Key-derivation salt for deriving Ed25519/X25519 private keys from the seed
|
|
/// (crypto.md §3). Used with info `"ed25519"` / `"x25519"`.
|
|
pub const KDF_SALT: &[u8] = b"skald-kdf-v1";
|
|
/// HKDF info string for the X25519 private key derivation (crypto.md §3).
|
|
pub const KDF_INFO_X25519: &[u8] = b"x25519";
|
|
/// HKDF info string for the Ed25519 private key derivation (crypto.md §3).
|
|
pub const KDF_INFO_ED25519: &[u8] = b"ed25519";
|
|
/// HKDF salt for deriving the per-session AES key from the ECDH shared secret
|
|
/// (crypto.md §5).
|
|
pub const SESSION_SALT: &[u8] = b"skald-session-v1";
|
|
/// HKDF info string for the AES-256-GCM session key (crypto.md §5).
|
|
pub const SESSION_INFO_AES: &[u8] = b"aes-256-gcm";
|
|
|
|
/// Nonce direction prefix, agent → client (crypto.md §6).
|
|
pub const DIR_AGENT_TO_CLIENT: [u8; 4] = [0, 0, 0, 1];
|
|
/// Nonce direction prefix, client → agent (crypto.md §6).
|
|
pub const DIR_CLIENT_TO_AGENT: [u8; 4] = [0, 0, 0, 2];
|
|
|
|
// ---------------------------------------------------------------------------
|
|
// Encoding helpers
|
|
// ---------------------------------------------------------------------------
|
|
|
|
/// Decode a hex pubkey/signature/id (case-insensitive on input) into `N` bytes.
|
|
/// Returns `None` on malformed hex or wrong length.
|
|
pub fn decode_hex<const N: usize>(s: &str) -> Option<[u8; N]> {
|
|
let bytes = hex::decode(s).ok()?;
|
|
if bytes.len() != N {
|
|
return None;
|
|
}
|
|
let mut out = [0u8; N];
|
|
out.copy_from_slice(&bytes);
|
|
Some(out)
|
|
}
|
|
|
|
// ---------------------------------------------------------------------------
|
|
// Relay subset: namespace derivation + challenge verification
|
|
// ---------------------------------------------------------------------------
|
|
|
|
/// `namespace_id = hex(SHA256(NS_DOMAIN ‖ 0x00 ‖ agent_ed25519_pub))` (crypto.md §7).
|
|
/// Returns both the raw 32 bytes and the lowercase hex string.
|
|
pub fn namespace_id(agent_ed25519_pub: &[u8; 32]) -> ([u8; 32], String) {
|
|
let mut h = Sha256::new();
|
|
h.update(NS_DOMAIN);
|
|
h.update([0u8]);
|
|
h.update(agent_ed25519_pub);
|
|
let raw: [u8; 32] = h.finalize().into();
|
|
let hexed = hex::encode(raw);
|
|
(raw, hexed)
|
|
}
|
|
|
|
/// Build the challenge message that is signed/verified:
|
|
/// `AUTH_DOMAIN ‖ 0x00 ‖ challenge_nonce_raw(32B)` (crypto.md §8).
|
|
pub fn challenge_message(challenge_nonce_raw: &[u8; 32]) -> Vec<u8> {
|
|
let mut msg = Vec::with_capacity(AUTH_DOMAIN.len() + 1 + 32);
|
|
msg.extend_from_slice(AUTH_DOMAIN);
|
|
msg.push(0x00);
|
|
msg.extend_from_slice(challenge_nonce_raw);
|
|
msg
|
|
}
|
|
|
|
/// Verify the Ed25519 challenge signature over the [`challenge_message`] under
|
|
/// `ed25519_pub`. Uses `verify_strict` (rejects malleable signatures / low-order
|
|
/// keys).
|
|
pub fn verify_challenge(
|
|
ed25519_pub: &[u8; 32],
|
|
challenge_nonce_raw: &[u8; 32],
|
|
signature: &[u8; 64],
|
|
) -> bool {
|
|
let Ok(vk) = VerifyingKey::from_bytes(ed25519_pub) else {
|
|
return false;
|
|
};
|
|
let sig = Signature::from_bytes(signature);
|
|
vk.verify_strict(&challenge_message(challenge_nonce_raw), &sig)
|
|
.is_ok()
|
|
}
|
|
|
|
/// Sign the challenge message with `signing_key` (used by the agent/plugin and
|
|
/// by the reference generator). Returns the 64-byte signature.
|
|
pub fn sign_challenge(signing_key: &SigningKey, challenge_nonce_raw: &[u8; 32]) -> [u8; 64] {
|
|
signing_key
|
|
.sign(&challenge_message(challenge_nonce_raw))
|
|
.to_bytes()
|
|
}
|
|
|
|
/// Plain SHA-256 of `data` (used e.g. for the pipe data-plane `dest =
|
|
/// SHA256(peer_ed25519_pub)` cross-check, pipe.md §2.1).
|
|
pub fn sha256(data: &[u8]) -> [u8; 32] {
|
|
let mut h = Sha256::new();
|
|
h.update(data);
|
|
h.finalize().into()
|
|
}
|
|
|
|
/// Constant-time comparison of two tokens/secrets (relay.md §6: pairing_token).
|
|
pub fn ct_eq(a: &[u8], b: &[u8]) -> bool {
|
|
if a.len() != b.len() {
|
|
return false;
|
|
}
|
|
a.ct_eq(b).into()
|
|
}
|
|
|
|
// ---------------------------------------------------------------------------
|
|
// End-to-end suite: key derivation, ECDH, AEAD (crypto.md §3-6)
|
|
// ---------------------------------------------------------------------------
|
|
|
|
/// HKDF-SHA256 expanding to a 32-byte output (crypto.md §3/§5).
|
|
pub fn hkdf32(ikm: &[u8], salt: &[u8], info: &[u8]) -> [u8; 32] {
|
|
let hk = Hkdf::<Sha256>::new(Some(salt), ikm);
|
|
let mut out = [0u8; 32];
|
|
hk.expand(info, &mut out)
|
|
.expect("32 is a valid HKDF-SHA256 output length");
|
|
out
|
|
}
|
|
|
|
/// The Ed25519 + X25519 key material derived from a 32-byte seed (crypto.md §3).
|
|
pub struct DerivedKeys {
|
|
pub ed25519_priv: [u8; 32],
|
|
pub ed25519_pub: [u8; 32],
|
|
pub x25519_priv: [u8; 32],
|
|
pub x25519_pub: [u8; 32],
|
|
}
|
|
|
|
impl DerivedKeys {
|
|
/// Reconstruct the Ed25519 signing key from the derived private bytes.
|
|
pub fn signing_key(&self) -> SigningKey {
|
|
SigningKey::from_bytes(&self.ed25519_priv)
|
|
}
|
|
|
|
/// Reconstruct the X25519 static secret from the derived private bytes.
|
|
pub fn x25519_secret(&self) -> StaticSecret {
|
|
StaticSecret::from(self.x25519_priv)
|
|
}
|
|
}
|
|
|
|
/// Derive the Ed25519 and X25519 key pairs from a 32-byte seed (crypto.md §3):
|
|
/// each private key is `HKDF(seed, salt="skald-kdf-v1", info=<algo>, 32)`.
|
|
pub fn derive_keys(seed: &[u8; 32]) -> DerivedKeys {
|
|
let ed25519_priv = hkdf32(seed, KDF_SALT, KDF_INFO_ED25519);
|
|
let x25519_priv = hkdf32(seed, KDF_SALT, KDF_INFO_X25519);
|
|
|
|
let signing = SigningKey::from_bytes(&ed25519_priv);
|
|
let ed25519_pub = signing.verifying_key().to_bytes();
|
|
|
|
let x_secret = StaticSecret::from(x25519_priv);
|
|
let x25519_pub = PublicKey::from(&x_secret).to_bytes();
|
|
|
|
DerivedKeys {
|
|
ed25519_priv,
|
|
ed25519_pub,
|
|
x25519_priv,
|
|
x25519_pub,
|
|
}
|
|
}
|
|
|
|
/// X25519 public key from a raw 32-byte private scalar (clamping applied
|
|
/// internally, consistent with [`ecdh`]). Used to derive a pipe ephemeral pubkey
|
|
/// from a freshly-sampled private key (pipe.md §3).
|
|
pub fn x25519_pubkey(x25519_priv: &[u8; 32]) -> [u8; 32] {
|
|
PublicKey::from(&StaticSecret::from(*x25519_priv)).to_bytes()
|
|
}
|
|
|
|
/// X25519 ECDH: compute the shared secret between `my_x25519_priv` and the
|
|
/// peer's public key (crypto.md §4).
|
|
pub fn ecdh(my_x25519_priv: &[u8; 32], peer_x25519_pub: &[u8; 32]) -> [u8; 32] {
|
|
let secret = StaticSecret::from(*my_x25519_priv);
|
|
let peer = PublicKey::from(*peer_x25519_pub);
|
|
*secret.diffie_hellman(&peer).as_bytes()
|
|
}
|
|
|
|
/// Derive the per-session AES-256-GCM key from the ECDH shared secret
|
|
/// (crypto.md §5).
|
|
pub fn derive_aes_key(shared_secret: &[u8; 32]) -> [u8; 32] {
|
|
hkdf32(shared_secret, SESSION_SALT, SESSION_INFO_AES)
|
|
}
|
|
|
|
/// Build the 12-byte AEAD nonce: `direction(4B) ‖ counter(8B big-endian)`
|
|
/// (crypto.md §6).
|
|
pub fn build_nonce(direction: [u8; 4], counter: u64) -> [u8; 12] {
|
|
let mut n = [0u8; 12];
|
|
n[..4].copy_from_slice(&direction);
|
|
n[4..].copy_from_slice(&counter.to_be_bytes());
|
|
n
|
|
}
|
|
|
|
/// Build the AEAD additional-authenticated-data: `namespace_id_raw ‖ from_pub ‖
|
|
/// to_pub`, all 32-byte raw values (crypto.md §6).
|
|
pub fn build_aad(namespace_id_raw: &[u8; 32], from_pub: &[u8; 32], to_pub: &[u8; 32]) -> Vec<u8> {
|
|
let mut aad = Vec::with_capacity(96);
|
|
aad.extend_from_slice(namespace_id_raw);
|
|
aad.extend_from_slice(from_pub);
|
|
aad.extend_from_slice(to_pub);
|
|
aad
|
|
}
|
|
|
|
/// AES-256-GCM seal: returns `ciphertext ‖ tag` (crypto.md §6). `Err` only on a
|
|
/// malformed key length (the AEAD itself never fails on encrypt).
|
|
pub fn seal(
|
|
aes_key: &[u8; 32],
|
|
nonce: &[u8; 12],
|
|
aad: &[u8],
|
|
plaintext: &[u8],
|
|
) -> Result<Vec<u8>, CryptoError> {
|
|
let cipher = Aes256Gcm::new_from_slice(aes_key).map_err(|_| CryptoError::Key)?;
|
|
cipher
|
|
.encrypt(Nonce::from_slice(nonce), Payload { msg: plaintext, aad })
|
|
.map_err(|_| CryptoError::Aead)
|
|
}
|
|
|
|
/// AES-256-GCM open: verifies the tag and returns the plaintext (crypto.md §6).
|
|
/// `Err(CryptoError::Aead)` on tag mismatch / wrong key / wrong AAD.
|
|
pub fn open(
|
|
aes_key: &[u8; 32],
|
|
nonce: &[u8; 12],
|
|
aad: &[u8],
|
|
ciphertext: &[u8],
|
|
) -> Result<Vec<u8>, CryptoError> {
|
|
let cipher = Aes256Gcm::new_from_slice(aes_key).map_err(|_| CryptoError::Key)?;
|
|
cipher
|
|
.decrypt(Nonce::from_slice(nonce), Payload { msg: ciphertext, aad })
|
|
.map_err(|_| CryptoError::Aead)
|
|
}
|
|
|
|
/// Errors from the AEAD layer. Intentionally opaque: never leak plaintext or
|
|
/// distinguish failure causes to a caller that might log them.
|
|
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
|
|
pub enum CryptoError {
|
|
/// Invalid key length supplied to the cipher.
|
|
Key,
|
|
/// Seal/open failed (e.g. authentication tag mismatch on open).
|
|
Aead,
|
|
}
|
|
|
|
impl std::fmt::Display for CryptoError {
|
|
fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
|
|
match self {
|
|
CryptoError::Key => write!(f, "invalid AES key length"),
|
|
CryptoError::Aead => write!(f, "AES-GCM operation failed"),
|
|
}
|
|
}
|
|
}
|
|
|
|
impl std::error::Error for CryptoError {}
|
|
|
|
// ---------------------------------------------------------------------------
|
|
// v2 plaintext framing (data/iOS-app/v2/framing.md §1, §2, §3)
|
|
// ---------------------------------------------------------------------------
|
|
|
|
/// Framing version byte for `compress_payload` / `decompress_payload`
|
|
/// (framing.md §1). Always `0x01` today.
|
|
pub const FRAMING_VERSION: u8 = 0x01;
|
|
/// `comp` byte value: no compression (framing.md §2).
|
|
pub const COMP_NONE: u8 = 0x00;
|
|
/// `comp` byte value: zlib / DEFLATE (framing.md §2).
|
|
pub const COMP_ZLIB: u8 = 0x01;
|
|
/// Soglia: solo comprimere se `len(payload) > COMPRESS_THRESHOLD` (framing.md §2.3).
|
|
pub const COMPRESS_THRESHOLD: usize = 1024;
|
|
/// Hard ceiling on the decompressed payload size (defense-in-depth against a
|
|
/// zlib bomb from a compromised authorized device). A small ciphertext, under
|
|
/// the frame limit, could otherwise expand to many GB. 8 MiB is well above any
|
|
/// legitimate payload (the largest, `health_sync` on the live channel, is
|
|
/// bounded by `MAX_LIVE_CIPHERTEXT_BYTES` ≈ 512 KiB even before compression).
|
|
pub const MAX_DECOMPRESSED_BYTES: u64 = 8 * 1024 * 1024;
|
|
|
|
/// Compose the v2 plaintext frame around `payload`:
|
|
/// `version(0x01) ‖ comp(1B) ‖ payload`. Compresses with zlib if
|
|
/// `payload.len() > COMPRESS_THRESHOLD` (framing.md §2.3, §1).
|
|
pub fn compress_payload(payload: &[u8]) -> Vec<u8> {
|
|
if payload.len() > COMPRESS_THRESHOLD {
|
|
let mut enc = ZlibEncoder::new(Vec::new(), Compression::default());
|
|
enc.write_all(payload).expect("zlib write to Vec is infallible");
|
|
let compressed = enc.finish().expect("zlib finish is infallible");
|
|
let mut out = Vec::with_capacity(2 + compressed.len());
|
|
out.push(FRAMING_VERSION);
|
|
out.push(COMP_ZLIB);
|
|
out.extend_from_slice(&compressed);
|
|
out
|
|
} else {
|
|
let mut out = Vec::with_capacity(2 + payload.len());
|
|
out.push(FRAMING_VERSION);
|
|
out.push(COMP_NONE);
|
|
out.extend_from_slice(payload);
|
|
out
|
|
}
|
|
}
|
|
|
|
/// Errors from the v2 plaintext framing (framing.md §3). The error variant
|
|
/// is intentionally opaque to avoid leaking information to upstream callers.
|
|
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
|
|
pub enum FramingError {
|
|
/// Truncated input (fewer than 2 bytes).
|
|
Short,
|
|
/// `version` byte is not `0x01`.
|
|
BadVersion,
|
|
/// `comp` byte is not in `{0x00, 0x01}`.
|
|
BadComp,
|
|
/// zlib decompress failed (corrupt compressed body) or the decompressed
|
|
/// output exceeded [`MAX_DECOMPRESSED_BYTES`].
|
|
Zlib,
|
|
}
|
|
|
|
impl std::fmt::Display for FramingError {
|
|
fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
|
|
match self {
|
|
FramingError::Short => write!(f, "framing input shorter than 2 bytes"),
|
|
FramingError::BadVersion => write!(f, "unknown framing version"),
|
|
FramingError::BadComp => write!(f, "unknown compression algorithm"),
|
|
FramingError::Zlib => write!(f, "zlib decompress failed"),
|
|
}
|
|
}
|
|
}
|
|
impl std::error::Error for FramingError {}
|
|
|
|
/// Decompose a v2 plaintext frame: return the original `payload` (i.e. the
|
|
/// bytes that were passed to `compress_payload`). Validates the framing
|
|
/// header and decompresses the body if `comp == 0x01` (framing.md §3).
|
|
pub fn decompress_payload(plaintext: &[u8]) -> Result<Vec<u8>, FramingError> {
|
|
let (version, comp, body) = match plaintext.split_first_chunk::<2>() {
|
|
Some((&[v, c], rest)) => (v, c, rest),
|
|
None => return Err(FramingError::Short),
|
|
};
|
|
if version != FRAMING_VERSION {
|
|
return Err(FramingError::BadVersion);
|
|
}
|
|
match comp {
|
|
COMP_NONE => Ok(body.to_vec()),
|
|
COMP_ZLIB => {
|
|
// Cap the output: `take` makes the reader yield EOF at the limit, so
|
|
// a zlib bomb stops there instead of exhausting memory. If the
|
|
// decoder still has bytes left we hit exactly the limit and reject.
|
|
let mut dec = ZlibDecoder::new(body).take(MAX_DECOMPRESSED_BYTES + 1);
|
|
let mut out = Vec::with_capacity((body.len() * 2).min(MAX_DECOMPRESSED_BYTES as usize));
|
|
dec.read_to_end(&mut out).map_err(|_| FramingError::Zlib)?;
|
|
if out.len() as u64 > MAX_DECOMPRESSED_BYTES {
|
|
return Err(FramingError::Zlib);
|
|
}
|
|
Ok(out)
|
|
}
|
|
_ => Err(FramingError::BadComp),
|
|
}
|
|
}
|
|
|
|
// ---------------------------------------------------------------------------
|
|
// Pipe protocol crypto (docs/relay/pipe.md §3, §5). The data-plane auth reuses
|
|
// the Ed25519 challenge primitive with its own domain; the secure channel
|
|
// reuses ECDH + HKDF + AES-256-GCM, keyed by a *per-pipe ephemeral* DH (PFS).
|
|
// ---------------------------------------------------------------------------
|
|
|
|
/// Data-plane auth signing domain (pipe.md §2.1, `PIPE_AUTH_DOMAIN`).
|
|
pub const PIPE_AUTH_DOMAIN: &[u8] = b"skald-pipe-auth-v1";
|
|
/// HKDF salt for deriving the per-pipe AES key from the ephemeral ECDH secret.
|
|
pub const PIPE_KDF_SALT: &[u8] = b"skald-pipe-v1";
|
|
/// HKDF info for the per-pipe AES-256-GCM key.
|
|
pub const PIPE_KDF_INFO: &[u8] = b"pipe-aes-256-gcm";
|
|
|
|
/// Nonce direction prefix, pipe initiator → responder (pipe.md §3).
|
|
pub const DIR_PIPE_INITIATOR: [u8; 4] = [0, 0, 0, 3];
|
|
/// Nonce direction prefix, pipe responder → initiator (pipe.md §3).
|
|
pub const DIR_PIPE_RESPONDER: [u8; 4] = [0, 0, 0, 4];
|
|
|
|
/// Framing version byte marking a **pipe signaling** payload on the E2E channel:
|
|
/// `0x02 ‖ comp(0x00) ‖ msgpack`. Distinct from [`FRAMING_VERSION`] (`0x01`,
|
|
/// JSON app payloads) so the receiver can route by peeking the first byte
|
|
/// *without* changing [`decompress_payload`] (which still rejects `0x02`).
|
|
pub const FRAMING_VERSION_PIPE: u8 = 0x02;
|
|
|
|
/// Derive the per-pipe AES-256-GCM key from the ephemeral ECDH shared secret.
|
|
pub fn derive_pipe_key(eph_shared_secret: &[u8; 32]) -> [u8; 32] {
|
|
hkdf32(eph_shared_secret, PIPE_KDF_SALT, PIPE_KDF_INFO)
|
|
}
|
|
|
|
/// Build the data-plane auth message that is signed/verified (pipe.md §2.1):
|
|
/// `PIPE_AUTH_DOMAIN ‖ 0x00 ‖ challenge_nonce(32B) ‖ connection_id(32B)`.
|
|
pub fn pipe_auth_message(challenge_nonce: &[u8; 32], connection_id: &[u8; 32]) -> Vec<u8> {
|
|
let mut msg = Vec::with_capacity(PIPE_AUTH_DOMAIN.len() + 1 + 32 + 32);
|
|
msg.extend_from_slice(PIPE_AUTH_DOMAIN);
|
|
msg.push(0x00);
|
|
msg.extend_from_slice(challenge_nonce);
|
|
msg.extend_from_slice(connection_id);
|
|
msg
|
|
}
|
|
|
|
/// Sign the data-plane auth message with `signing_key`. Returns the 64B signature.
|
|
pub fn sign_pipe_auth(
|
|
signing_key: &SigningKey,
|
|
challenge_nonce: &[u8; 32],
|
|
connection_id: &[u8; 32],
|
|
) -> [u8; 64] {
|
|
signing_key
|
|
.sign(&pipe_auth_message(challenge_nonce, connection_id))
|
|
.to_bytes()
|
|
}
|
|
|
|
/// Verify the data-plane auth signature under `ed25519_pub` (uses `verify_strict`).
|
|
pub fn verify_pipe_auth(
|
|
ed25519_pub: &[u8; 32],
|
|
challenge_nonce: &[u8; 32],
|
|
connection_id: &[u8; 32],
|
|
signature: &[u8; 64],
|
|
) -> bool {
|
|
let Ok(vk) = VerifyingKey::from_bytes(ed25519_pub) else {
|
|
return false;
|
|
};
|
|
let sig = Signature::from_bytes(signature);
|
|
vk.verify_strict(&pipe_auth_message(challenge_nonce, connection_id), &sig)
|
|
.is_ok()
|
|
}
|
|
|
|
/// Wrap a MsgPack pipe-signaling payload in the reserved framing:
|
|
/// `FRAMING_VERSION_PIPE ‖ COMP_NONE ‖ msgpack` (uncompressed; signaling is tiny).
|
|
pub fn frame_pipe_signal(msgpack: &[u8]) -> Vec<u8> {
|
|
let mut out = Vec::with_capacity(2 + msgpack.len());
|
|
out.push(FRAMING_VERSION_PIPE);
|
|
out.push(COMP_NONE);
|
|
out.extend_from_slice(msgpack);
|
|
out
|
|
}
|
|
|
|
/// `true` if a decrypted E2E plaintext is a pipe-signaling frame (vs a `0x01`
|
|
/// app payload). A cheap first-byte peek used to route inbound messages.
|
|
pub fn is_pipe_signal(framed: &[u8]) -> bool {
|
|
framed.first() == Some(&FRAMING_VERSION_PIPE)
|
|
}
|
|
|
|
/// Strip the pipe-signaling framing, returning the inner MsgPack body. `None`
|
|
/// if the header is not exactly `FRAMING_VERSION_PIPE ‖ COMP_NONE`.
|
|
pub fn unframe_pipe_signal(framed: &[u8]) -> Option<&[u8]> {
|
|
match framed.split_first_chunk::<2>() {
|
|
Some((&[FRAMING_VERSION_PIPE, COMP_NONE], body)) => Some(body),
|
|
_ => None,
|
|
}
|
|
}
|
|
|
|
#[cfg(test)]
|
|
mod tests {
|
|
use super::*;
|
|
use ed25519_dalek::SigningKey;
|
|
|
|
#[test]
|
|
fn decode_hex_rejects_wrong_len() {
|
|
assert!(decode_hex::<32>("00").is_none());
|
|
assert!(decode_hex::<32>("zz".repeat(32).as_str()).is_none());
|
|
assert_eq!(decode_hex::<2>("ABcd"), Some([0xAB, 0xCD])); // accepts uppercase
|
|
}
|
|
|
|
#[test]
|
|
fn challenge_roundtrip() {
|
|
let sk = SigningKey::from_bytes(&[7u8; 32]);
|
|
let pk = sk.verifying_key().to_bytes();
|
|
let nonce = [0x42u8; 32];
|
|
|
|
let sig = sign_challenge(&sk, &nonce);
|
|
assert!(verify_challenge(&pk, &nonce, &sig));
|
|
|
|
// Different nonce → invalid signature.
|
|
assert!(!verify_challenge(&pk, &[0x43u8; 32], &sig));
|
|
// Different key → invalid.
|
|
let other = SigningKey::from_bytes(&[8u8; 32])
|
|
.verifying_key()
|
|
.to_bytes();
|
|
assert!(!verify_challenge(&other, &nonce, &sig));
|
|
}
|
|
|
|
#[test]
|
|
fn namespace_id_is_hex_of_sha256() {
|
|
let pk = [0u8; 32];
|
|
let (raw, hexed) = namespace_id(&pk);
|
|
assert_eq!(hexed.len(), 64);
|
|
assert_eq!(hex::encode(raw), hexed);
|
|
}
|
|
|
|
#[test]
|
|
fn ecdh_is_symmetric_and_seals_roundtrip() {
|
|
let seed_a: [u8; 32] = (0u8..32).collect::<Vec<_>>().try_into().unwrap();
|
|
let seed_c: [u8; 32] = (32u8..64).collect::<Vec<_>>().try_into().unwrap();
|
|
let a = derive_keys(&seed_a);
|
|
let c = derive_keys(&seed_c);
|
|
|
|
let s1 = ecdh(&a.x25519_priv, &c.x25519_pub);
|
|
let s2 = ecdh(&c.x25519_priv, &a.x25519_pub);
|
|
assert_eq!(s1, s2, "ECDH must be symmetric");
|
|
|
|
let key = derive_aes_key(&s1);
|
|
let (ns_raw, _) = namespace_id(&a.ed25519_pub);
|
|
let nonce = build_nonce(DIR_AGENT_TO_CLIENT, 1);
|
|
let aad = build_aad(&ns_raw, &a.ed25519_pub, &c.ed25519_pub);
|
|
|
|
let pt = b"hello world";
|
|
let sealed = seal(&key, &nonce, &aad, pt).unwrap();
|
|
let opened = open(&key, &nonce, &aad, &sealed).unwrap();
|
|
assert_eq!(opened, pt);
|
|
|
|
// Tampered AAD must fail to open.
|
|
let mut bad_aad = aad.clone();
|
|
bad_aad[0] ^= 1;
|
|
assert!(open(&key, &nonce, &bad_aad, &sealed).is_err());
|
|
}
|
|
|
|
/// Cross-compat: the iOS client uses `CryptoKit` to sign the auth challenge,
|
|
/// the relay uses `ed25519-dalek` to verify. The two libraries produce
|
|
/// *different* (but both valid) Ed25519 signatures for the same (key,
|
|
/// message) — see `data/ios-app/test-vectors.md` §4 "Note on V18". This test
|
|
/// pins the two signatures the relay must accept for the canonical
|
|
/// `SEED_CLIENT = bytes(32..<64)` test vector.
|
|
#[test]
|
|
fn challenge_verifies_cryptokit_signature() {
|
|
// V8 client_ed25519_pub from test-vectors.md §4.
|
|
let client_pub: [u8; 32] =
|
|
hex::decode("12355ea750e60d6370ba6776037f25062f6c9450c5009669884895fd5b377a18")
|
|
.unwrap()
|
|
.try_into()
|
|
.unwrap();
|
|
let challenge: [u8; 32] =
|
|
hex::decode("aabbccddeeff00112233445566778899aabbccddeeff00112233445566778899")
|
|
.unwrap()
|
|
.try_into()
|
|
.unwrap();
|
|
// V18 from test-vectors.md §4 (CryptoKit signature).
|
|
let v18_cryptokit: [u8; 64] =
|
|
hex::decode("a2af4518a7001e3269006d30e1175d33d36cc23350c6c4def8347be8ec97e32ce51c4f066ca29cc497690aa241524d20ea20a72d38d9beb6da01e966aada8508")
|
|
.unwrap()
|
|
.try_into()
|
|
.unwrap();
|
|
// The dalek reference value (regression — see "Note on V18" in §4).
|
|
let v18_dalek: [u8; 64] =
|
|
hex::decode("ae38491a1f25bb5fb11f0b17e3d344412bfc927461b6517e9a0ab6a64020054677f59490af026f34c81d9378d4daae4823109ca2d1afbf4ff00230a038270002")
|
|
.unwrap()
|
|
.try_into()
|
|
.unwrap();
|
|
|
|
assert!(verify_challenge(&client_pub, &challenge, &v18_cryptokit),
|
|
"relay must accept the CryptoKit signature committed as V18");
|
|
assert!(verify_challenge(&client_pub, &challenge, &v18_dalek),
|
|
"relay must also accept the historical dalek reference signature");
|
|
|
|
// Sanity: tampered signature is rejected.
|
|
let mut bad = v18_cryptokit;
|
|
bad[0] ^= 0x01;
|
|
assert!(!verify_challenge(&client_pub, &challenge, &bad));
|
|
}
|
|
|
|
/// Pin the derived keys / namespace / aes_key against the committed vectors
|
|
/// (test-vectors.md §4) so the library functions can never silently diverge.
|
|
#[test]
|
|
fn library_matches_reference_vectors() {
|
|
let seed_a: [u8; 32] = (0u8..32).collect::<Vec<_>>().try_into().unwrap();
|
|
let a = derive_keys(&seed_a);
|
|
assert_eq!(
|
|
hex::encode(a.ed25519_pub),
|
|
"b3e202f4ac99fd9929da47df20adedd5b2598411a466a229f086eda3467ffa7b"
|
|
);
|
|
let (ns_raw, ns_hex) = namespace_id(&a.ed25519_pub);
|
|
assert_eq!(
|
|
ns_hex,
|
|
"f7d340d3c3f0b0052fa904ba60ebd38a0f7e7d10672ac80648991a2c632c9e58"
|
|
);
|
|
|
|
let seed_c: [u8; 32] = (32u8..64).collect::<Vec<_>>().try_into().unwrap();
|
|
let c = derive_keys(&seed_c);
|
|
let shared = ecdh(&a.x25519_priv, &c.x25519_pub);
|
|
assert_eq!(
|
|
hex::encode(shared),
|
|
"66c51034dd6360b9cdddc495049463b0191d7f3bddce9ea6f2975c85d471540a"
|
|
);
|
|
let aes_key = derive_aes_key(&shared);
|
|
assert_eq!(
|
|
hex::encode(aes_key),
|
|
"74fb4ffcbbe069859cfb0790023811554dad328d9f4ac4a1d28077086e33a4e7"
|
|
);
|
|
let _ = ns_raw;
|
|
}
|
|
|
|
#[test]
|
|
fn framing_round_trip_small_payload_no_compression() {
|
|
// Below threshold → comp = 0x00
|
|
let payload = b"{\"v\":1,\"kind\":\"x\"}";
|
|
let framed = compress_payload(payload);
|
|
assert_eq!(framed[0], FRAMING_VERSION);
|
|
assert_eq!(framed[1], COMP_NONE);
|
|
assert_eq!(&framed[2..], payload);
|
|
assert_eq!(decompress_payload(&framed).unwrap(), payload);
|
|
}
|
|
|
|
#[test]
|
|
fn framing_round_trip_large_payload_zlib() {
|
|
// Build a payload that clearly crosses the threshold and is
|
|
// highly compressible (a repeated string → ~1% of original).
|
|
let payload: Vec<u8> = "skald ".repeat(500).into_bytes();
|
|
assert!(payload.len() > COMPRESS_THRESHOLD);
|
|
let framed = compress_payload(&payload);
|
|
assert_eq!(framed[0], FRAMING_VERSION);
|
|
assert_eq!(framed[1], COMP_ZLIB);
|
|
// Compressed body must be smaller than the original.
|
|
assert!(framed.len() < payload.len());
|
|
assert_eq!(decompress_payload(&framed).unwrap(), payload);
|
|
}
|
|
|
|
#[test]
|
|
fn framing_rejects_bad_version() {
|
|
let mut bad = vec![0x02, COMP_NONE];
|
|
bad.extend_from_slice(b"x");
|
|
assert_eq!(decompress_payload(&bad), Err(FramingError::BadVersion));
|
|
}
|
|
|
|
#[test]
|
|
fn framing_rejects_bad_comp() {
|
|
let mut bad = vec![FRAMING_VERSION, 0x02];
|
|
bad.extend_from_slice(b"x");
|
|
assert_eq!(decompress_payload(&bad), Err(FramingError::BadComp));
|
|
}
|
|
|
|
#[test]
|
|
fn framing_rejects_truncated_input() {
|
|
assert_eq!(decompress_payload(&[]), Err(FramingError::Short));
|
|
assert_eq!(
|
|
decompress_payload(&[FRAMING_VERSION]),
|
|
Err(FramingError::Short)
|
|
);
|
|
}
|
|
|
|
#[test]
|
|
fn framing_rejects_corrupt_zlib_body() {
|
|
let mut bad = vec![FRAMING_VERSION, COMP_ZLIB];
|
|
bad.extend_from_slice(b"this is not zlib data");
|
|
assert_eq!(decompress_payload(&bad), Err(FramingError::Zlib));
|
|
}
|
|
|
|
#[test]
|
|
fn framing_rejects_zlib_bomb_over_limit() {
|
|
// A tiny compressed frame that decompresses past MAX_DECOMPRESSED_BYTES
|
|
// must be rejected, not allocated. Zeros compress to a handful of bytes.
|
|
let huge = vec![0u8; (MAX_DECOMPRESSED_BYTES as usize) + 1];
|
|
let framed = compress_payload(&huge);
|
|
assert!(framed.len() < huge.len() / 100, "bomb frame compresses hugely");
|
|
assert_eq!(decompress_payload(&framed), Err(FramingError::Zlib));
|
|
}
|
|
|
|
#[test]
|
|
fn framing_accepts_payload_at_limit() {
|
|
// Exactly at the ceiling must still round-trip.
|
|
let big = vec![7u8; MAX_DECOMPRESSED_BYTES as usize];
|
|
let framed = compress_payload(&big);
|
|
assert_eq!(decompress_payload(&framed).unwrap(), big);
|
|
}
|
|
|
|
#[test]
|
|
fn pipe_auth_sign_verify_binds_nonce_and_connection() {
|
|
let sk = SigningKey::from_bytes(&[9u8; 32]);
|
|
let pk = sk.verifying_key().to_bytes();
|
|
let nonce = [0x11u8; 32];
|
|
let cid = [0x22u8; 32];
|
|
|
|
let sig = sign_pipe_auth(&sk, &nonce, &cid);
|
|
assert!(verify_pipe_auth(&pk, &nonce, &cid, &sig));
|
|
// Different nonce or connection_id → invalid (anti-replay / rebind).
|
|
assert!(!verify_pipe_auth(&pk, &[0x12u8; 32], &cid, &sig));
|
|
assert!(!verify_pipe_auth(&pk, &nonce, &[0x23u8; 32], &sig));
|
|
// Domain separation: an AUTH_DOMAIN signature must not verify here.
|
|
let auth_sig = sign_challenge(&sk, &nonce);
|
|
assert!(!verify_pipe_auth(&pk, &nonce, &cid, &auth_sig));
|
|
}
|
|
|
|
#[test]
|
|
fn pipe_key_is_symmetric_over_ephemeral_dh() {
|
|
// Two fresh ephemeral X25519 keypairs derive the same pipe key.
|
|
let a = derive_keys(&[1u8; 32]);
|
|
let b = derive_keys(&[2u8; 32]);
|
|
let ka = derive_pipe_key(&ecdh(&a.x25519_priv, &b.x25519_pub));
|
|
let kb = derive_pipe_key(&ecdh(&b.x25519_priv, &a.x25519_pub));
|
|
assert_eq!(ka, kb);
|
|
}
|
|
|
|
#[test]
|
|
fn pipe_signal_framing_round_trip() {
|
|
let body = b"\x82\xa1k\x01"; // arbitrary msgpack-ish bytes
|
|
let framed = frame_pipe_signal(body);
|
|
assert!(is_pipe_signal(&framed));
|
|
assert_eq!(unframe_pipe_signal(&framed), Some(&body[..]));
|
|
// A normal v2 app frame is NOT a pipe signal and won't unframe.
|
|
let app = compress_payload(b"{}");
|
|
assert!(!is_pipe_signal(&app));
|
|
assert_eq!(unframe_pipe_signal(&app), None);
|
|
}
|
|
}
|