msrt 0.1.8

Portable MSRT protocol implementation.
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107

//! Packet integrity backends.
//!
//! CRC backends detect random corruption with a collision probability of
//! 2^-16 to 2^-64 depending on width. [`SipTag`] is a 128-bit keyed tag for
//! links where even rare CRC false accepts are unacceptable; see the module
//! documentation in [`sip`] for the rationale and the security boundary.

pub mod crc;
pub mod sip;

pub use crc::{Crc16, Crc32, Crc64};
pub use sip::SipTag;

/// Packet integrity backend selected by engine configuration.
#[derive(Clone, Copy, Debug, Eq, PartialEq)]
pub enum IntegrityConfig {
    /// CRC-16/XMODEM packet integrity.
    Crc16(Crc16),
    /// CRC-32/ISO-HDLC packet integrity.
    Crc32(Crc32),
    /// CRC-64/ECMA-182 packet integrity.
    Crc64(Crc64),
    /// Keyed 128-bit packet integrity tag.
    SipTag(SipTag),
}

impl IntegrityConfig {
    /// Default packet integrity backend used by [`crate::engine::EngineConfig`].
    pub const DEFAULT: Self = Self::Crc16(Crc16);

    /// Creates the default CRC-16/XMODEM integrity configuration.
    #[must_use]
    pub const fn crc16() -> Self {
        Self::Crc16(Crc16)
    }

    /// Creates a CRC-32/ISO-HDLC integrity configuration.
    #[must_use]
    pub const fn crc32() -> Self {
        Self::Crc32(Crc32)
    }

    /// Creates a CRC-64/ECMA-182 integrity configuration.
    #[must_use]
    pub const fn crc64() -> Self {
        Self::Crc64(Crc64)
    }

    /// Creates a keyed integrity tag configuration with the library default key.
    #[must_use]
    pub const fn sip_tag() -> Self {
        Self::SipTag(SipTag::DEFAULT)
    }

    /// Creates a keyed integrity tag configuration with a custom key.
    #[must_use]
    pub const fn sip_tag_with_key(key: [u8; SipTag::KEY_LEN]) -> Self {
        Self::SipTag(SipTag::new(key))
    }
}

impl Default for IntegrityConfig {
    fn default() -> Self {
        Self::DEFAULT
    }
}

impl Integrity for IntegrityConfig {
    fn tag_len(&self) -> usize {
        match self {
            Self::Crc16(integrity) => integrity.tag_len(),
            Self::Crc32(integrity) => integrity.tag_len(),
            Self::Crc64(integrity) => integrity.tag_len(),
            Self::SipTag(integrity) => integrity.tag_len(),
        }
    }

    fn seal(&self, bytes: &[u8], out: &mut [u8]) {
        match self {
            Self::Crc16(integrity) => integrity.seal(bytes, out),
            Self::Crc32(integrity) => integrity.seal(bytes, out),
            Self::Crc64(integrity) => integrity.seal(bytes, out),
            Self::SipTag(integrity) => integrity.seal(bytes, out),
        }
    }

    fn verify(&self, bytes: &[u8], tag: &[u8]) -> bool {
        match self {
            Self::Crc16(integrity) => integrity.verify(bytes, tag),
            Self::Crc32(integrity) => integrity.verify(bytes, tag),
            Self::Crc64(integrity) => integrity.verify(bytes, tag),
            Self::SipTag(integrity) => integrity.verify(bytes, tag),
        }
    }
}

/// Calculates and verifies integrity tags for wire bytes.
pub trait Integrity {
    /// Encoded tag length in bytes.
    fn tag_len(&self) -> usize;

    /// Writes the integrity tag for `bytes` into `out`.
    fn seal(&self, bytes: &[u8], out: &mut [u8]);

    /// Returns whether `tag` matches `bytes`.
    fn verify(&self, bytes: &[u8], tag: &[u8]) -> bool;
}