iwlink 0.1.1

IntelliWallet Link - encrypted phone to computer protocol for IntelliWallet for Browser
Documentation
//! Fragmenting sealed messages to fit Bluetooth writes.
//!
//! A GATT write or notification carries at most the negotiated length (about
//! 182 bytes on a default iPhone connection, up to 512 elsewhere). A sealed
//! message can be larger, so it is cut into fragments, each prefixed with one
//! header byte:
//!
//! ```text
//! bit 7      last fragment of this message
//! bit 6      first fragment of this message
//! bits 0..5  sequence number, 0 on the first fragment, then counting up
//!            and wrapping at 64
//! ```
//!
//! The start of a message is marked by its own flag rather than by sequence
//! number 0, because the sequence number wraps: a long message on a small
//! connection has more than 64 fragments, and a counter back at 0 must not be
//! mistaken for a new message.
//!
//! The receiver accepts fragments only in sequence. Anything else means a
//! write was lost, and since the Noise transport cannot recover from a lost
//! message either (see [`crate::noise`]), the reassembler does not try to be
//! clever: it reports the error, drops the partial message, and waits for the
//! next first fragment.

use crate::error::{LinkError, Result};
use crate::noise::MAX_NOISE_MESSAGE;

/// Smallest usable fragment, header included. Bluetooth's minimum ATT payload
/// is 20 bytes, so every connection can carry at least this much.
pub const MIN_FRAGMENT_LEN: usize = 20;

/// Largest reassembled message: one Noise message.
pub const MAX_ASSEMBLED: usize = MAX_NOISE_MESSAGE;

const LAST: u8 = 0x80;
const FIRST: u8 = 0x40;
const SEQ_MASK: u8 = 0x3F;

/// Split `message` into fragments of at most `fragment_len` bytes each.
pub fn fragment(message: &[u8], fragment_len: usize) -> Result<Vec<Vec<u8>>> {
    if fragment_len < MIN_FRAGMENT_LEN {
        return Err(LinkError::BadFragment("fragment length below minimum"));
    }
    if message.is_empty() {
        return Err(LinkError::BadFragment("empty message"));
    }
    if message.len() > MAX_ASSEMBLED {
        return Err(LinkError::TooLarge);
    }
    let body = fragment_len - 1;
    let count = message.len().div_ceil(body);
    Ok(message
        .chunks(body)
        .enumerate()
        .map(|(i, chunk)| {
            let mut header = (i as u8) & SEQ_MASK;
            if i == 0 {
                header |= FIRST;
            }
            if i + 1 == count {
                header |= LAST;
            }
            let mut out = Vec::with_capacity(chunk.len() + 1);
            out.push(header);
            out.extend_from_slice(chunk);
            out
        })
        .collect())
}

/// Puts fragments back together, one message at a time.
#[derive(Debug, Default)]
pub struct Reassembler {
    buffer: Vec<u8>,
    /// Sequence number expected next, or `None` when waiting for a new
    /// message.
    expected: Option<u8>,
    /// Set after an error until the next first fragment.
    resync: bool,
}

impl Reassembler {
    pub fn new() -> Reassembler {
        Reassembler::default()
    }

    /// Feed one received fragment. Returns the complete message once its last
    /// fragment has arrived.
    pub fn push(&mut self, fragment: &[u8]) -> Result<Option<Vec<u8>>> {
        let Some((&header, body)) = fragment.split_first() else {
            return self.fail("empty fragment");
        };
        let seq = header & SEQ_MASK;
        let last = header & LAST != 0;
        let first = header & FIRST != 0;

        if first {
            if seq != 0 {
                return self.fail("first fragment with a sequence number");
            }
            // A new message. If one was in progress, it lost its tail; it is
            // dropped, and the error for it has already been or will be seen
            // as a decrypt failure on the session.
            self.buffer.clear();
            self.resync = false;
        } else if self.resync {
            return Ok(None);
        } else if self.expected != Some(seq) {
            return self.fail("fragment out of sequence");
        }

        if body.is_empty() {
            return self.fail("fragment without data");
        }
        if self.buffer.len() + body.len() > MAX_ASSEMBLED {
            self.reset();
            self.resync = true;
            return Err(LinkError::TooLarge);
        }
        self.buffer.extend_from_slice(body);

        if last {
            self.expected = None;
            return Ok(Some(std::mem::take(&mut self.buffer)));
        }
        self.expected = Some((seq + 1) & SEQ_MASK);
        Ok(None)
    }

    /// Drop any partial message.
    pub fn reset(&mut self) {
        self.buffer.clear();
        self.expected = None;
    }

    fn fail(&mut self, reason: &'static str) -> Result<Option<Vec<u8>>> {
        self.reset();
        self.resync = true;
        Err(LinkError::BadFragment(reason))
    }
}

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

    fn deliver(fragments: &[Vec<u8>]) -> Vec<u8> {
        let mut r = Reassembler::new();
        let mut result = None;
        for (i, f) in fragments.iter().enumerate() {
            let out = r.push(f).unwrap();
            if i + 1 < fragments.len() {
                assert!(out.is_none());
            } else {
                result = out;
            }
        }
        result.expect("complete message")
    }

    #[test]
    fn every_split_size_round_trips() {
        let message: Vec<u8> = (0..3_000u32).map(|i| (i % 251) as u8).collect();
        for len in MIN_FRAGMENT_LEN..=512 {
            let fragments = fragment(&message, len).unwrap();
            assert!(fragments.iter().all(|f| f.len() <= len));
            assert_eq!(deliver(&fragments), message, "fragment length {len}");
        }
    }

    #[test]
    fn one_fragment_message() {
        let fragments = fragment(b"hi", 20).unwrap();
        assert_eq!(fragments, vec![vec![FIRST | LAST, b'h', b'i']]);
        assert_eq!(deliver(&fragments), b"hi");
    }

    #[test]
    fn sequence_wraps_without_starting_a_new_message() {
        let message: Vec<u8> = (0..19 * 300u32).map(|i| (i % 253) as u8).collect();
        let fragments = fragment(&message, 20).unwrap();
        assert!(fragments.len() > 2 * 64);
        assert_eq!(deliver(&fragments), message);
    }

    #[test]
    fn largest_message_round_trips_and_one_more_byte_is_refused() {
        let message = vec![1u8; MAX_ASSEMBLED];
        assert_eq!(deliver(&fragment(&message, 512).unwrap()), message);
        assert_eq!(
            fragment(&vec![1u8; MAX_ASSEMBLED + 1], 512).unwrap_err(),
            LinkError::TooLarge
        );
    }

    #[test]
    fn lost_fragment_is_detected_then_the_next_message_arrives() {
        let first = fragment(&[1u8; 100], 20).unwrap();
        let second = fragment(&[2u8; 50], 20).unwrap();
        let mut r = Reassembler::new();

        r.push(&first[0]).unwrap();
        assert!(r.push(&first[2]).is_err(), "fragment 1 was lost");
        // The rest of the broken message is ignored quietly.
        for f in &first[3..] {
            assert_eq!(r.push(f).unwrap(), None);
        }
        // The next message starts at sequence 0 and arrives intact.
        let mut out = None;
        for f in &second {
            out = r.push(f).unwrap();
        }
        assert_eq!(out.unwrap(), vec![2u8; 50]);
    }

    #[test]
    fn lost_tail_is_dropped_when_a_new_message_starts() {
        let first = fragment(&[1u8; 100], 20).unwrap();
        let second = fragment(b"next", 20).unwrap();
        let mut r = Reassembler::new();
        r.push(&first[0]).unwrap();
        r.push(&first[1]).unwrap();
        assert_eq!(r.push(&second[0]).unwrap().unwrap(), b"next");
    }

    #[test]
    fn duplicated_fragment_is_an_error() {
        let fragments = fragment(&[3u8; 60], 20).unwrap();
        let mut r = Reassembler::new();
        r.push(&fragments[0]).unwrap();
        r.push(&fragments[1]).unwrap();
        assert!(r.push(&fragments[1]).is_err());
    }

    #[test]
    fn oversized_stream_is_cut_off() {
        let mut r = Reassembler::new();
        let mut body = vec![0u8; 512];
        body[0] = FIRST;
        r.push(&body).unwrap();
        let mut seq = 1u8;
        let mut result = Ok(None);
        for _ in 0..200 {
            body[0] = seq & SEQ_MASK;
            result = r.push(&body);
            if result.is_err() {
                break;
            }
            seq = seq.wrapping_add(1);
        }
        assert_eq!(result.unwrap_err(), LinkError::TooLarge);
    }

    #[test]
    fn invalid_arguments() {
        assert!(fragment(b"x", MIN_FRAGMENT_LEN - 1).is_err());
        assert!(fragment(b"", 20).is_err());
        let mut r = Reassembler::new();
        assert!(r.push(&[]).is_err());
        assert!(r.push(&[FIRST | LAST]).is_err(), "header without data");
        assert!(
            r.push(&[FIRST | 3, 1]).is_err(),
            "first fragment must be sequence 0"
        );
        assert!(
            Reassembler::new().push(&[5, 1]).is_err(),
            "continuation with nothing started"
        );
    }
}