Skip to main content

zigbee_core/security/
frame.rs

1//! Security Frame Formats
2use core::mem;
3
4use zigbee_macros::impl_byte;
5use zigbee_types::IeeeAddress;
6
7impl_byte! {
8    /// Auxiliary Frame Header Format
9    ///
10    /// See Section 4.5.1.
11    #[derive(Debug, Clone, Copy)]
12    pub struct AuxFrameHeader {
13        pub security_control: SecurityControl,
14        pub frame_counter: u32,
15        /// Set only if [`SecurityControl::extended_nonce`] is `true`.
16        #[parse_if = security_control.extended_nonce()]
17        pub source_address: Option<IeeeAddress>,
18        /// Set only if [`SecurityControl::key_identifier`] is `1`.
19        #[parse_if = security_control.is_network_key()]
20        pub key_sequence_number: Option<u8>,
21    }
22}
23
24impl_byte! {
25    /// Security Control
26    ///
27    /// See Section 4.5.1.1.
28    #[derive(Clone, Copy, Default)]
29    pub struct SecurityControl(pub u8);
30}
31
32impl core::fmt::Debug for SecurityControl {
33    fn fmt(&self, f: &mut core::fmt::Formatter<'_>) -> core::fmt::Result {
34        f.debug_struct("SecurityControl")
35            .field("security_level", &self.security_level())
36            .field("key_identifier", &self.key_identifier())
37            .field("extended_nonce", &self.extended_nonce())
38            .finish()
39    }
40}
41
42impl SecurityControl {
43    /// Indicates how a frame is secured.
44    pub fn security_level(&self) -> SecurityLevel {
45        SecurityLevel::from_bits(self.0 & mask::SECURITY_LEVEL)
46    }
47
48    pub fn set_security_level(&mut self, level: SecurityLevel) {
49        self.0 = (self.0 & !mask::SECURITY_LEVEL) | ((level.into_bits()) << offset::SECURITY_LEVEL);
50    }
51
52    /// Identifies the key in use.
53    pub fn key_identifier(&self) -> KeyIdentifier {
54        // SAFETY: any 2 bit permutation is a valid KeyIdentifier
55        unsafe { mem::transmute((self.0 >> 3) & 0b11) }
56    }
57
58    pub fn set_key_identifier(&mut self, key_id: KeyIdentifier) {
59        self.0 = (self.0 & !mask::KEY_IDENTIFIER) | ((key_id as u8) << offset::KEY_IDENTIFIER);
60    }
61
62    pub(crate) fn is_network_key(&self) -> bool {
63        self.key_identifier() == KeyIdentifier::Network
64    }
65
66    /// Set if the sender address of the auxiliary header is present.
67    pub fn extended_nonce(&self) -> bool {
68        self.0 >> 5 != 0
69    }
70
71    pub fn set_extended_nonce(&mut self, extended_nonce: bool) {
72        self.0 =
73            (self.0 & !mask::EXTENDED_NONCE) | ((extended_nonce as u8) << offset::EXTENDED_NONCE);
74    }
75}
76
77mod mask {
78    pub const SECURITY_LEVEL: u8 = 0b0000_0111;
79    pub const KEY_IDENTIFIER: u8 = 0b0001_1000;
80    pub const EXTENDED_NONCE: u8 = 0b0010_0000;
81}
82
83mod offset {
84    pub const SECURITY_LEVEL: u8 = 0;
85    pub const KEY_IDENTIFIER: u8 = 3;
86    pub const EXTENDED_NONCE: u8 = 5;
87}
88
89impl_byte! {
90    #[tag(u8)]
91    /// Security Level
92    ///
93    /// See Section 4.5.1.1.1.
94    #[derive(Debug, Clone, Copy, PartialEq, Eq)]
95    #[allow(missing_docs)]
96    pub enum SecurityLevel {
97        None = 0b000,
98        Mic32 = 0b001,
99        Mic64 = 0b010,
100        Mic128 = 0b011,
101        Enc = 0b100,
102        EncMic32 = 0b101,
103        EncMic64 = 0b110,
104        EncMic128 = 0b111,
105        #[fallback = true]
106        Reserved(u8)
107    }
108}
109
110impl SecurityLevel {
111    pub fn mic_length(&self) -> usize {
112        match self {
113            Self::EncMic32 | Self::Mic32 => 4,
114            Self::EncMic64 | Self::Mic64 => 8,
115            Self::EncMic128 | Self::Mic128 => 16,
116            Self::Reserved(_) | Self::None | Self::Enc => 0,
117        }
118    }
119
120    pub fn from_bits(bits: u8) -> Self {
121        match bits {
122            0b000 => Self::None,
123            0b001 => Self::Mic32,
124            0b010 => Self::Mic64,
125            0b011 => Self::Mic128,
126            0b100 => Self::Enc,
127            0b101 => Self::EncMic32,
128            0b110 => Self::EncMic64,
129            0b111 => Self::EncMic128,
130            _ => Self::Reserved(bits),
131        }
132    }
133
134    pub fn into_bits(&self) -> u8 {
135        match self {
136            Self::None => 0b000,
137            Self::Mic32 => 0b001,
138            Self::Mic64 => 0b010,
139            Self::Mic128 => 0b011,
140            Self::Enc => 0b100,
141            Self::EncMic32 => 0b101,
142            Self::EncMic64 => 0b110,
143            Self::EncMic128 => 0b111,
144            Self::Reserved(_bits) => 0,
145        }
146    }
147}
148
149/// Key Identifier
150///
151/// See Section 4.5.1.1.2.
152#[repr(u8)]
153#[derive(Debug, Clone, Copy, PartialEq, Eq)]
154#[allow(missing_docs)]
155pub enum KeyIdentifier {
156    Data = 0b00,
157    Network = 0b01,
158    KeyTransport = 0b10,
159    KeyLoad = 0b11,
160}