Skip to main content

zigbee_core/security/
mod.rs

1//! Security Service
2//!
3//! Security services provided for Zigbee include methods for key establishment,
4//! key transport, frame protection, and device management.
5#![allow(deprecated)]
6use core::convert::TryInto;
7use core::slice;
8
9use aead::AeadMutInPlace;
10use aead::generic_array::GenericArray;
11use aes::Aes128;
12use aes::cipher::BlockEncrypt;
13use aes::cipher::KeyInit as AesKeyInit;
14use aes::cipher::generic_array::GenericArray as AesGenericArray;
15use byte::BytesExt;
16use byte::TryRead;
17use byte::TryWrite;
18use ccm::Ccm;
19use ccm::KeyInit;
20use ccm::consts::U4;
21use ccm::consts::U13;
22use frame::AuxFrameHeader;
23use frame::SecurityControl;
24use frame::SecurityLevel;
25use thiserror::Error;
26use zigbee_types::ByteArray;
27use zigbee_types::ByteArrayRef;
28use zigbee_types::IeeeAddress;
29
30use crate::aps::aib;
31use crate::aps::aib::Aib;
32use crate::aps::aib::DeviceKeyPairDescriptor;
33use crate::aps::aib::KeyAttribute;
34use crate::aps::aib::LinkKeyType;
35use crate::aps::frame::CommandFrame as ApsCommandFrame;
36use crate::aps::frame::Frame as ApsFrame;
37use crate::aps::frame::command::Command as ApsCommand;
38use crate::aps::frame::command::TransportKey;
39use crate::aps::frame::frame_control::FrameType as ApsFrameType;
40use crate::aps::frame::header::Header as ApsHeader;
41use crate::aps::types::TxOptions;
42use crate::nwk::frame::Frame as NwkFrame;
43use crate::nwk::frame::header::Header as NwkHeader;
44use crate::nwk::nib;
45use crate::nwk::nib::IncomingFrameCounterDescriptor;
46use crate::nwk::nib::NetworkSecurityMaterialDescriptor;
47use crate::nwk::nib::Nib;
48use crate::security::frame::KeyIdentifier;
49use crate::security::primitives::Aes128Mmo;
50use crate::security::primitives::HmacAes128Mmo;
51
52pub mod frame;
53pub mod primitives;
54
55/// Default ZigbeeAlliance09 centralized security global trust center link key
56pub const TRUST_CENTER_LINK_KEY: [u8; 16] = [
57    0x5a, 0x69, 0x67, 0x42, 0x65, 0x65, 0x41, 0x6c, 0x6c, 0x69, 0x61, 0x6e, 0x63, 0x65, 0x30, 0x39,
58];
59
60// AES-128 CCM with MIC32
61pub type Aes128Ccm = Ccm<Aes128, U4, U13>;
62
63#[derive(Debug, Error)]
64pub enum SecurityError {
65    #[error("invalid key")]
66    InvalidKey,
67    #[error("invalid data")]
68    InvalidData,
69    #[error("parse error")]
70    ParseError(byte::Error),
71    #[error("ccm error")]
72    CcmError(ccm::Error),
73    #[error("frame security failed")]
74    Unspecified,
75}
76
77impl From<byte::Error> for SecurityError {
78    fn from(value: byte::Error) -> Self {
79        Self::ParseError(value)
80    }
81}
82
83impl From<SecurityError> for byte::Error {
84    fn from(value: SecurityError) -> Self {
85        match value {
86            SecurityError::InvalidKey => Self::BadInput {
87                err: "security: invalid key",
88            },
89            SecurityError::InvalidData => Self::BadInput {
90                err: "security: invalid data",
91            },
92            SecurityError::ParseError(e) => e,
93            SecurityError::CcmError(_) => Self::BadInput {
94                err: "security: ccm error",
95            },
96            SecurityError::Unspecified => Self::BadInput {
97                err: "frame security failed",
98            },
99        }
100    }
101}
102
103pub struct SecurityContext<'a> {
104    nib: &'a Nib,
105    aib: &'a Aib,
106}
107
108impl<'a> SecurityContext<'a> {
109    pub fn new(nib: &'a Nib, aib: &'a Aib) -> Self {
110        Self { nib, aib }
111    }
112
113    /// Returns the `SecurityContext` referencing the static `NIB` and `AIB`.
114    pub fn get() -> Self {
115        Self {
116            nib: nib::get_ref(),
117            aib: aib::get_ref(),
118        }
119    }
120
121    // section 4.3.1.1
122    pub fn encrypt_nwk_frame_in_place(
123        &self,
124        nwk_frame: NwkFrame<'_>,
125        frame_buffer: &mut [u8],
126    ) -> Result<usize, SecurityError> {
127        let sec_level = *self.nib.security_level();
128        let _mic_len = sec_level.mic_length();
129
130        let key_sequence_number = *self.nib.active_key_seq_number();
131        // read the key + counter and increment the counter (4.3.1.1) in one
132        // atomic update
133        let mut security_material = None;
134        self.nib.update_security_material_set(|set| {
135            if let Some(material) = set
136                .iter_mut()
137                .find(|k| k.key_seq_number == key_sequence_number)
138            {
139                security_material = Some((material.outgoing_frame_counter, material.key));
140                material.outgoing_frame_counter += 1;
141            }
142        });
143        let (frame_counter, key) = security_material.ok_or(SecurityError::Unspecified)?;
144        let local_addr = *self.nib.ieee_address();
145
146        let mut security_control = SecurityControl::default();
147        security_control.set_security_level(sec_level);
148        security_control.set_key_identifier(KeyIdentifier::Network);
149        security_control.set_extended_nonce(true);
150
151        let aux_hdr = AuxFrameHeader {
152            security_control,
153            frame_counter,
154            key_sequence_number: Some(key_sequence_number),
155            source_address: Some(local_addr),
156        };
157
158        match nwk_frame {
159            NwkFrame::Data(data_frame) => Self::write_and_encrypt_in_place(
160                frame_buffer,
161                aux_hdr,
162                key.as_slice(),
163                data_frame.header,
164                data_frame.payload,
165            ),
166            NwkFrame::NwkCommand(command_frame) => Self::write_and_encrypt_in_place(
167                frame_buffer,
168                aux_hdr,
169                key.as_slice(),
170                command_frame.header,
171                command_frame.command,
172            ),
173            NwkFrame::Reserved(header) | NwkFrame::InterPan(header) => {
174                // no security required
175                let offset = &mut 0;
176                frame_buffer.write_with(offset, header, ())?;
177                Ok(*offset)
178            }
179        }
180    }
181
182    // section 4.3.1.2
183    pub fn decrypt_nwk_frame_in_place<'b>(
184        &self,
185        frame_buffer: &'b mut [u8],
186    ) -> Result<NwkFrame<'b>, SecurityError> {
187        // 4.3.1.2: overwrite the security level with the value from the NIB
188        // (default 0x05)
189        let sec_level = *self.nib.security_level();
190
191        let mic_length = sec_level.mic_length();
192        byte::check_len(frame_buffer, mic_length)?;
193
194        let (_, nwk_hdr_len) = NwkHeader::try_read(frame_buffer, ())?;
195        // SAFETY: the header buffer is not mutated, so dropping the &mut here
196        // to satisfy the borrow checker when returning NwkFrame<'_> is
197        // sound
198        let hdr_buf = unsafe { slice::from_raw_parts(frame_buffer.as_ptr(), nwk_hdr_len) };
199        let (nwk_hdr, _) = NwkHeader::try_read(hdr_buf, ())?;
200        if !nwk_hdr.frame_control.security_flag() {
201            // no security enabled for frame, exit with payload
202            return Ok(NwkFrame::from_payload(
203                nwk_hdr,
204                &frame_buffer[nwk_hdr_len..],
205            )?);
206        }
207
208        let (mut aux_hdr, aux_hdr_len) =
209            AuxFrameHeader::try_read(&frame_buffer[nwk_hdr_len..], ())?;
210
211        if aux_hdr.frame_counter == u32::MAX {
212            return Err(SecurityError::InvalidData);
213        }
214
215        let Some(source_address) = aux_hdr.source_address else {
216            return Err(SecurityError::InvalidData);
217        };
218
219        // select the key from NIB; guard scoped so the write lock below cannot
220        // deadlock
221        let key = {
222            let sec_material_set = self.nib.security_material_set();
223            let sec_material = sec_material_set
224                .iter()
225                .find(|k| {
226                    aux_hdr
227                        .key_sequence_number
228                        .is_some_and(|ksn| ksn == k.key_seq_number)
229                })
230                .ok_or(SecurityError::Unspecified)?;
231
232            // anti-replay: `<=` rejects both older counters and a replay of the
233            // most-recently-accepted one
234            if sec_material
235                .incoming_frame_counter_set
236                .iter()
237                .find(|i| source_address == i.sender_address)
238                .is_some_and(|inc_frame_counter| {
239                    aux_hdr.frame_counter <= inc_frame_counter.incoming_frame_counter
240                })
241            {
242                return Err(SecurityError::InvalidData);
243            }
244            sec_material.key
245        };
246        let key = key.as_slice();
247
248        // write back the NIB security level into the aux header; required as
249        // ccm input
250        aux_hdr.security_control.set_security_level(sec_level);
251        let mut offset = nwk_hdr_len;
252        frame_buffer.write_with(&mut offset, aux_hdr, ())?;
253
254        let (aad, frame) = frame_buffer.split_at_mut(nwk_hdr_len + aux_hdr_len);
255        let (enc_data, tag) = frame.split_at_mut(frame.len() - mic_length);
256        let tag = GenericArray::from_slice(tag);
257
258        let nonce: GenericArray<u8, _> = create_nonce(&aux_hdr)?.into();
259        let mut cipher = Aes128Ccm::new(key.into());
260
261        cipher
262            .decrypt_in_place_detached(&nonce, aad, enc_data, tag)
263            .map_err(SecurityError::CcmError)?;
264
265        // 4.7.3.10.5: a device implicitly switches to the newer network key
266        // when it hears a frame secured with it — a sleepy end device may
267        // never receive the broadcast Switch-Key. a key update carries the
268        // sequence number (N + 1) mod 256 (4.6.3.4.1), which distinguishes the
269        // newer key from the previous one still accepted for inbound frames
270        let active = *self.nib.active_key_seq_number();
271        if aux_hdr
272            .key_sequence_number
273            .is_some_and(|ksn| ksn == active.wrapping_add(1))
274        {
275            let ksn = active.wrapping_add(1);
276            log::info!("[NWK] switching to network key seq {ksn} seen in a received frame");
277            self.nib.update_active_key_seq_number(|value| *value = ksn);
278        }
279
280        // anti-replay tracking: record the now-authenticated counter as the
281        // most recent accepted value for this sender
282        let mut record_result = Ok(());
283        self.nib.update_security_material_set(|set| {
284            if let Some(material) = set.iter_mut().find(|k| {
285                aux_hdr
286                    .key_sequence_number
287                    .is_some_and(|ksn| ksn == k.key_seq_number)
288            }) {
289                record_result = record_nwk_incoming_frame_counter(
290                    material,
291                    source_address,
292                    aux_hdr.frame_counter,
293                );
294            }
295        });
296        record_result?;
297
298        Ok(NwkFrame::from_payload(nwk_hdr, enc_data)?)
299    }
300
301    pub fn encrypt_aps_frame_in_place(
302        &self,
303        aps_frame: ApsFrame<'_>,
304        frame_buffer: &mut [u8],
305        dest: IeeeAddress,
306        tx_options: TxOptions,
307    ) -> Result<usize, SecurityError> {
308        if let ApsFrame::Acknowledgement(header) = aps_frame {
309            // no encryption for acknowledgements
310            let offset = &mut 0;
311            frame_buffer.write_with(&mut 0, header, ())?;
312            return Ok(*offset);
313        }
314
315        // get link key for destination from AIB; guard scoped so the counter
316        // increment below cannot deadlock
317        let (link_key, frame_counter) = {
318            let key_set = self.aib.device_key_pair_set();
319            let key_config = key_set
320                .iter()
321                .find(|k| {
322                    k.device_address == dest
323                        && matches!(
324                            k.key_attributes,
325                            KeyAttribute::ProvisionalKey
326                                | KeyAttribute::UnverifiedKey
327                                | KeyAttribute::VerifiedKey
328                        )
329                })
330                .ok_or(SecurityError::Unspecified)?;
331            (key_config.link_key, key_config.outgoing_frame_counter)
332        };
333
334        let (key, key_id) = match &aps_frame {
335            ApsFrame::ApsCommand(ApsCommandFrame {
336                command: ApsCommand::TransportKey(TransportKey::StandardNetworkKey(_)),
337                ..
338            }) => (
339                // 4.5.3: key-transport key uses 1-octet string 0x00
340                HmacAes128Mmo::hmac(link_key.as_slice(), &[0x00])?,
341                KeyIdentifier::KeyTransport,
342            ),
343            ApsFrame::ApsCommand(ApsCommandFrame {
344                command:
345                    ApsCommand::TransportKey(
346                        TransportKey::ApplicationLinkKey(_) | TransportKey::TrustCenterLinkKey(_),
347                    ),
348                ..
349            }) => (
350                // 4.5.3: key-load key uses 1-octet string 0x02
351                HmacAes128Mmo::hmac(link_key.as_slice(), &[0x02])?,
352                KeyIdentifier::KeyLoad,
353            ),
354            _ => (link_key.0, KeyIdentifier::Data),
355        };
356
357        if frame_counter == u32::MAX {
358            return Err(SecurityError::InvalidData);
359        }
360
361        let sec_level = *self.nib.security_level();
362
363        let mut security_control = SecurityControl::default();
364        security_control.set_security_level(sec_level);
365        security_control.set_key_identifier(key_id);
366
367        if matches!(aps_frame, ApsFrame::ApsCommand(_))
368            || matches!(tx_options, TxOptions::IncludeExtendedNonce)
369        {
370            security_control.set_extended_nonce(true);
371        }
372
373        let source_address = if security_control.extended_nonce() {
374            Some(*self.nib.ieee_address())
375        } else {
376            None
377        };
378
379        let aux_hdr = AuxFrameHeader {
380            security_control,
381            frame_counter,
382            source_address,
383            // key_id here is never NetworkKey (0x01), so this must stay unset
384            key_sequence_number: None,
385        };
386
387        let offset = match aps_frame {
388            ApsFrame::Data(data_frame) => Self::write_and_encrypt_in_place(
389                frame_buffer,
390                aux_hdr,
391                key.as_slice(),
392                data_frame.header,
393                data_frame.payload,
394            ),
395            ApsFrame::ApsCommand(command_frame) => Self::write_and_encrypt_in_place(
396                frame_buffer,
397                aux_hdr,
398                key.as_slice(),
399                command_frame.header,
400                command_frame.command,
401            ),
402            // acknowledgements are returned early above
403            ApsFrame::Acknowledgement(_) => unreachable!(),
404        }?;
405
406        self.aib.update_device_key_pair_set(|key_set| {
407            if let Some(key_config) = key_set.iter_mut().find(|k| k.device_address == dest) {
408                key_config.outgoing_frame_counter += 1;
409            }
410        });
411
412        Ok(offset)
413    }
414
415    fn write_and_encrypt_in_place(
416        frame_buffer: &mut [u8],
417        aux_hdr: AuxFrameHeader,
418        key: &[u8],
419        hdr: impl TryWrite + core::fmt::Debug,
420        payload: impl TryWrite + core::fmt::Debug,
421    ) -> Result<usize, SecurityError> {
422        let mic_len = aux_hdr.security_control.security_level().mic_length();
423        let nonce = create_nonce(&aux_hdr)?;
424
425        let offset = &mut 0;
426        frame_buffer.write_with(offset, hdr, ())?;
427
428        let aux_hdr_offset = *offset;
429        frame_buffer.write_with(offset, aux_hdr, ())?;
430
431        let payload_offset = *offset;
432        frame_buffer.write_with(offset, payload, ())?;
433        let payload_len = *offset - payload_offset;
434
435        let (aad, payload) = frame_buffer.split_at_mut(payload_offset);
436        let (payload, tag) = payload.split_at_mut(payload_len);
437        let tag = &mut tag[..mic_len];
438        let len = *offset + mic_len;
439
440        let nonce = GenericArray::from(nonce);
441
442        let mut cipher = Aes128Ccm::new(GenericArray::from_slice(key));
443        let t = cipher
444            .encrypt_in_place_detached(&nonce, aad, payload)
445            .map_err(SecurityError::CcmError)?;
446        tag.copy_from_slice(t.as_slice());
447
448        // overwrite sec level in aux header with 000
449        let mut sec_ctl = SecurityControl(frame_buffer[aux_hdr_offset]);
450        sec_ctl.set_security_level(SecurityLevel::None);
451        frame_buffer[aux_hdr_offset] = sec_ctl.0;
452
453        Ok(len)
454    }
455
456    // section 4.4.1.2
457    pub fn decrypt_aps_frame_in_place<'b>(
458        &self,
459        frame_buffer: &'b mut [u8],
460    ) -> Result<ApsFrame<'b>, SecurityError> {
461        // 4.4.1.2: overwrite the security level with the value from the NIB
462        // (default 0x05)
463        let sec_level = *self.nib.security_level();
464        let mic_length = sec_level.mic_length();
465        byte::check_len(frame_buffer, mic_length)?;
466
467        let (_, aps_hdr_len) = ApsHeader::try_read(frame_buffer, ())?;
468        // SAFETY: the header buffer is not mutated, so dropping the &mut here
469        // to satisfy the borrow checker when returning ApsFrame<'_> is
470        // sound
471        let hdr_buf = unsafe { slice::from_raw_parts(frame_buffer.as_ptr(), aps_hdr_len) };
472        let (aps_hdr, _) = ApsHeader::try_read(hdr_buf, ())?;
473
474        let (mut aux_hdr, aux_hdr_len) =
475            AuxFrameHeader::try_read(&frame_buffer[aps_hdr_len..], ())?;
476
477        if aux_hdr.frame_counter == u32::MAX {
478            return Err(SecurityError::InvalidData);
479        }
480
481        let Some(source_address) = aux_hdr.source_address else {
482            return Err(SecurityError::Unspecified);
483        };
484
485        // select the security material matching the source address
486        // TODO: spec indexes by the APS frame source address, but the APS frame
487        // has no source field, only the security header
488        // known_device gates the anti-replay check below so a legitimate first
489        // frame (counter may be 0) is not rejected before any counter is on
490        // record
491        let (known_device, link_key, last_incoming_counter) = {
492            let key_set = self.aib.device_key_pair_set();
493            key_set
494                .iter()
495                .find(|k| k.device_address == source_address)
496                .map_or(
497                    // TODO: what key do we use for a new, unknown source device?
498                    (false, ByteArray(TRUST_CENTER_LINK_KEY), 0),
499                    |k| (true, k.link_key, k.incoming_frame_counter),
500                )
501        };
502
503        let key = match aux_hdr.security_control.key_identifier() {
504            KeyIdentifier::Data => link_key.0,
505            KeyIdentifier::KeyTransport => {
506                // 4.5.3: key-transport key uses 1-octet string 0x00
507                HmacAes128Mmo::hmac(link_key.as_slice(), &[0x00])?
508            }
509            KeyIdentifier::KeyLoad => {
510                // 4.5.3: key-load key uses 1-octet string 0x02
511                HmacAes128Mmo::hmac(link_key.as_slice(), &[0x02])?
512            }
513            KeyIdentifier::Network => return Err(SecurityError::InvalidData),
514        };
515
516        // anti-replay applies to every link-key type, including the global
517        // trust-center key, once a frame has previously been accepted from this
518        // device
519        if known_device && aux_hdr.frame_counter <= last_incoming_counter {
520            return Err(SecurityError::Unspecified);
521        }
522
523        // write back the NIB security level into the aux header; required as
524        // ccm input
525        aux_hdr.security_control.set_security_level(sec_level);
526        let mut offset = aps_hdr_len;
527        frame_buffer.write_with(&mut offset, aux_hdr, ())?;
528
529        let (aad, frame) = frame_buffer.split_at_mut(aps_hdr_len + aux_hdr_len);
530        let (enc_data, tag) = frame.split_at_mut(frame.len() - mic_length);
531        let tag = GenericArray::from_slice(tag);
532
533        // TODO: verify the source address
534        let Some(_source_address) = aux_hdr.source_address else {
535            return Err(SecurityError::InvalidData);
536        };
537
538        let nonce: GenericArray<u8, _> = create_nonce(&aux_hdr)?.into();
539        let mut cipher = Aes128Ccm::new(&key.into());
540
541        cipher
542            .decrypt_in_place_detached(&nonce, aad, enc_data, tag)
543            .map_err(SecurityError::CcmError)?;
544
545        // anti-replay tracking: record the now-authenticated counter as the
546        // most recent accepted value for this device, inserting the
547        // entry if new
548        self.aib.update_device_key_pair_set(|key_set| {
549            let key_config = key_set.find_or_insert_with_mut(
550                |k| k.device_address == source_address,
551                || DeviceKeyPairDescriptor {
552                    device_address: source_address,
553                    key_attributes: KeyAttribute::VerifiedKey,
554                    link_key: ByteArray(TRUST_CENTER_LINK_KEY),
555                    outgoing_frame_counter: 0,
556                    incoming_frame_counter: 0,
557                    link_key_type: LinkKeyType::GlobalLinkKey,
558                },
559            );
560            key_config.incoming_frame_counter = aux_hdr.frame_counter;
561        });
562
563        Ok(ApsFrame::from_payload(aps_hdr, enc_data)?)
564    }
565}
566
567// records frame_counter as the most recently accepted incoming counter for
568// sender_address, inserting a new entry for a first-time sender
569fn record_nwk_incoming_frame_counter(
570    material: &mut NetworkSecurityMaterialDescriptor,
571    sender_address: IeeeAddress,
572    frame_counter: u32,
573) -> Result<(), SecurityError> {
574    if let Some(entry) = material
575        .incoming_frame_counter_set
576        .iter_mut()
577        .find(|i| i.sender_address == sender_address)
578    {
579        entry.incoming_frame_counter = frame_counter;
580        Ok(())
581    } else {
582        material
583            .incoming_frame_counter_set
584            .push(IncomingFrameCounterDescriptor {
585                sender_address,
586                incoming_frame_counter: frame_counter,
587            })
588            .map_err(|_| SecurityError::Unspecified)
589    }
590}
591
592// Figure 4-20
593#[allow(clippy::needless_range_loop)]
594fn create_nonce(aux_header: &AuxFrameHeader) -> Result<[u8; 13], SecurityError> {
595    let AuxFrameHeader {
596        security_control,
597        frame_counter,
598        source_address: Some(IeeeAddress(source_address)),
599        ..
600    } = aux_header
601    else {
602        return Err(SecurityError::InvalidData);
603    };
604
605    let mut nonce = [0u8; 13];
606    for i in 0..8 {
607        nonce[i] = (source_address >> (8 * i) & 0xff) as u8;
608    }
609
610    for i in 0..4 {
611        nonce[i + 8] = (frame_counter >> (8 * i) & 0xff) as u8;
612    }
613    nonce[12] = security_control.0;
614    Ok(nonce)
615}
616
617#[cfg(test)]
618mod tests {
619
620    use heapless::Vec;
621    use zigbee_types::ByteArray;
622    use zigbee_types::StorageVec;
623
624    use super::*;
625    use crate::nwk::nib::IncomingFrameCounterDescriptor;
626    use crate::nwk::nib::NetworkSecurityMaterialDescriptor;
627
628    const NETWORK_KEY: [u8; 16] = [
629        0xab, 0xcd, 0xef, 0x01, 0x23, 0x45, 0x67, 0x89, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
630        0x00,
631    ];
632
633    fn setup_nib() -> Nib {
634        let nib = Nib::new();
635
636        let mut set = Vec::new();
637        set.push(NetworkSecurityMaterialDescriptor {
638            key_seq_number: 0,
639            outgoing_frame_counter: 1,
640            incoming_frame_counter_set: StorageVec(Vec::new()),
641            key: ByteArray(NETWORK_KEY),
642            network_key_type: 0,
643        })
644        .unwrap();
645        nib.update_security_material_set(|value| *value = StorageVec(set));
646        nib.update_ieee_address(|value| *value = IeeeAddress(0x1234_5678_90ab_cdef));
647        nib.update_security_level(|value| *value = SecurityLevel::EncMic32);
648
649        assert_eq!(nib.security_material_set()[0].key, ByteArray(NETWORK_KEY));
650
651        nib
652    }
653
654    fn setup_aib() -> Aib {
655        let aib = Aib::new();
656        aib
657    }
658
659    fn append_aib_device_key_pair_set(aib: &Aib, k: DeviceKeyPairDescriptor) {
660        aib.update_device_key_pair_set(|set| set.push(k).unwrap());
661    }
662
663    #[test]
664    fn test_create_nonce() {
665        let source_address = Some(IeeeAddress(0xaaaa_bbbb_cccc_dddd));
666        let frame_counter = 0x0;
667        let security_control = SecurityControl(0x40);
668        let aux_hdr = AuxFrameHeader {
669            security_control,
670            frame_counter,
671            source_address,
672            key_sequence_number: None,
673        };
674        let nonce = create_nonce(&aux_hdr).unwrap();
675        assert_eq!(
676            nonce,
677            [
678                0xdd, 0xdd, 0xcc, 0xcc, 0xbb, 0xbb, 0xaa, 0xaa, 0x00, 0x00, 0x00, 0x00, 0x40
679            ]
680        );
681    }
682
683    #[test]
684    fn decrypt_aps_frame_data() {
685        let nib = setup_nib();
686        let aib = setup_aib();
687
688        // aps cmd request key
689        let frame_buffer = [
690            0x21, 0x66, // aps header
691            0x20, 0x4, 0x0, 0x0, 0x0, 0xe5, 0x1, 0x30, 0x38, 0x9c, 0x38, 0xc1,
692            0xa4, // aux header
693            0x1a, 0x31, // enc data
694            0xa4, 0xd7, 0xf4, 0xd7, //mic
695        ];
696
697        let security_context = SecurityContext::new(&nib, &aib);
698
699        let mut buf = frame_buffer;
700        let frame = security_context
701            .decrypt_aps_frame_in_place(&mut buf)
702            .unwrap();
703
704        let dest = IeeeAddress(0x1234_5678_90ab_cdef);
705        append_aib_device_key_pair_set(
706            &aib,
707            DeviceKeyPairDescriptor {
708                device_address: dest,
709                key_attributes: KeyAttribute::VerifiedKey,
710                link_key: ByteArray(TRUST_CENTER_LINK_KEY),
711                outgoing_frame_counter: 4,
712                incoming_frame_counter: 0,
713                link_key_type: LinkKeyType::GlobalLinkKey,
714            },
715        );
716        nib.update_ieee_address(|value| *value = IeeeAddress(0xa4c1_389c_3830_01e5));
717        let mut got_buffer = [0u8; 21];
718
719        let offset = security_context
720            .encrypt_aps_frame_in_place(frame, &mut got_buffer, dest, TxOptions::SecurityEnabled)
721            .unwrap();
722
723        assert_eq!(offset, frame_buffer.len());
724        assert_eq!(frame_buffer, got_buffer);
725    }
726
727    #[test]
728    fn decrypt_aps_frame_records_incoming_frame_counter() {
729        let nib = setup_nib();
730        let aib = setup_aib();
731        let security_context = SecurityContext::new(&nib, &aib);
732
733        let mut buf = [
734            0x21, 0x66, // aps header
735            0x20, 0x4, 0x0, 0x0, 0x0, 0xe5, 0x1, 0x30, 0x38, 0x9c, 0x38, 0xc1,
736            0xa4, // aux header
737            0x1a, 0x31, // enc data
738            0xa4, 0xd7, 0xf4, 0xd7, // mic
739        ];
740        security_context
741            .decrypt_aps_frame_in_place(&mut buf)
742            .unwrap();
743
744        let recorded = aib
745            .device_key_pair_set()
746            .iter()
747            .find(|k| k.device_address == IeeeAddress(0xa4c1_389c_3830_01e5))
748            .map(|k| k.incoming_frame_counter);
749
750        assert_eq!(
751            recorded,
752            Some(4),
753            "decrypt must persist the accepted frame counter for the device"
754        );
755    }
756
757    #[test]
758    fn decrypt_aps_frame_key_transport() {
759        let nib = setup_nib();
760        let aib = setup_aib();
761
762        let frame_buffer = [
763            0x21, 0x95, // aps hdr
764            0x30, 0x0, 0x0, 0x0, 0x0, 0xe1, 0x52, 0x38, 0x7d, 0xc1, 0x36, 0xce, // aux hdr
765            0xf4, 0xcc, 0x56, 0x50, 0x5e, 0x7, 0x2d, 0xc5, 0xc1, 0xe8, 0x40, 0xf2, 0xd5, 0xce, 0xc,
766            0xa9, 0x2d, 0x64, 0x23, 0xcc, 0xc, 0x56, 0xcc, 0xc4, 0xcc, 0xf, 0x18, 0xa2, 0xe4, 0x82,
767            0x88, 0x58, 0x4a, 0x90, 0x3e, 0x0, // enc data
768            0x47, 0x60, 0xf2, 0x5d, // mic
769        ];
770
771        let security_context = SecurityContext::new(&nib, &aib);
772
773        let mut buf = frame_buffer;
774        let frame = security_context
775            .decrypt_aps_frame_in_place(&mut buf)
776            .unwrap();
777
778        let dest = IeeeAddress(0xa4c1_389c_3830_01e5);
779        append_aib_device_key_pair_set(
780            &aib,
781            DeviceKeyPairDescriptor {
782                device_address: dest,
783                key_attributes: KeyAttribute::VerifiedKey,
784                link_key: ByteArray(TRUST_CENTER_LINK_KEY),
785                outgoing_frame_counter: 0,
786                incoming_frame_counter: 0,
787                link_key_type: LinkKeyType::GlobalLinkKey,
788            },
789        );
790        nib.update_ieee_address(|value| *value = IeeeAddress(0xf4ce_36c1_7d38_52e1));
791
792        let mut got_buffer = [0u8; 54];
793        let offset = security_context
794            .encrypt_aps_frame_in_place(frame, &mut got_buffer, dest, TxOptions::SecurityEnabled)
795            .unwrap();
796
797        assert_eq!(offset, frame_buffer.len());
798        assert_eq!(frame_buffer, got_buffer);
799    }
800
801    #[test]
802    fn decrypt_aps_frame_key_load() {
803        let nib = setup_nib();
804        let aib = setup_aib();
805
806        let frame_buffer = [
807            0x21, 0x97, // aps hdr
808            0x38, 0x1, 0x0, 0x0, 0x0, 0xe1, 0x52, 0x38, 0x7d, 0xc1, 0x36, 0xce, // aux hdr
809            0xf4, 0xe0, 0x4b, 0x37, 0xdb, 0x35, 0xc7, 0x13, 0x41, 0x71, 0xf0, 0xdf, 0xdb, 0x22,
810            0xa5, 0xa1, 0x65, 0xbf, 0xfe, 0x41, 0x5a, 0xb2, 0x5f, 0xd9, 0x85, 0x79, 0x92, 0x5a,
811            0xd4, 0xe6, 0x48, 0xfa, 0x6, 0xfb, 0x11, // enc data
812            0xb7, 0xc9, 0x4, 0x3e, // mic
813        ];
814
815        let security_context = SecurityContext::new(&nib, &aib);
816
817        let mut buf = frame_buffer;
818        let frame = security_context
819            .decrypt_aps_frame_in_place(&mut buf)
820            .unwrap();
821
822        let dest = IeeeAddress(0xa4c1_389c_3830_01e5);
823        append_aib_device_key_pair_set(
824            &aib,
825            DeviceKeyPairDescriptor {
826                device_address: dest,
827                key_attributes: KeyAttribute::VerifiedKey,
828                link_key: ByteArray(TRUST_CENTER_LINK_KEY),
829                outgoing_frame_counter: 1,
830                incoming_frame_counter: 0,
831                link_key_type: LinkKeyType::GlobalLinkKey,
832            },
833        );
834        nib.update_ieee_address(|value| *value = IeeeAddress(0xf4ce_36c1_7d38_52e1));
835
836        let mut got_buffer = [0u8; 128];
837        let offset = security_context
838            .encrypt_aps_frame_in_place(frame, &mut got_buffer, dest, TxOptions::SecurityEnabled)
839            .unwrap();
840
841        assert_eq!(offset, frame_buffer.len());
842        assert_eq!(frame_buffer, got_buffer[..offset]);
843    }
844
845    // same payload as decrypt_aps_frame_data
846    const APS_FRAME_DATA: [u8; 21] = [
847        0x21, 0x66, // aps header
848        0x20, 0x4, 0x0, 0x0, 0x0, 0xe5, 0x1, 0x30, 0x38, 0x9c, 0x38, 0xc1, 0xa4, // aux header
849        0x1a, 0x31, // enc data
850        0xa4, 0xd7, 0xf4, 0xd7, // mic
851    ];
852
853    // seeds a UniqueLinkKey descriptor for the fixture's sender with the given
854    // already-accepted incoming counter; UniqueLinkKey is required for the APS
855    // anti-replay gate to run
856    fn aib_with_incoming_counter(accepted: u32) -> Aib {
857        let aib = setup_aib();
858        append_aib_device_key_pair_set(
859            &aib,
860            DeviceKeyPairDescriptor {
861                device_address: IeeeAddress(0xa4c1_389c_3830_01e5),
862                key_attributes: KeyAttribute::VerifiedKey,
863                link_key: ByteArray(TRUST_CENTER_LINK_KEY),
864                outgoing_frame_counter: 0,
865                incoming_frame_counter: accepted,
866                link_key_type: LinkKeyType::UniqueLinkKey,
867            },
868        );
869        aib
870    }
871
872    #[test]
873    fn decrypt_aps_frame_rejects_replayed_frame_counter() {
874        let nib = setup_nib();
875        let aib = aib_with_incoming_counter(4);
876        let security_context = SecurityContext::new(&nib, &aib);
877
878        let mut buf = APS_FRAME_DATA;
879        assert!(
880            security_context
881                .decrypt_aps_frame_in_place(&mut buf)
882                .is_err(),
883            "replay of an already-accepted APS frame counter must be rejected"
884        );
885    }
886
887    #[test]
888    fn decrypt_aps_frame_accepts_newer_frame_counter() {
889        let nib = setup_nib();
890        let aib = aib_with_incoming_counter(3);
891        let security_context = SecurityContext::new(&nib, &aib);
892
893        let mut buf = APS_FRAME_DATA;
894        assert!(
895            security_context
896                .decrypt_aps_frame_in_place(&mut buf)
897                .is_ok(),
898            "a frame counter newer than the last accepted one must be accepted"
899        );
900    }
901
902    // encrypted NWK EndDeviceTimeoutRequest
903    const NWK_FRAME_CMD_BUFFER: [u8; 45] = [
904        0x9, 0x1a, // frame control
905        0x0, 0x0, 0xe1, 0xcd, 0x1, 0x93, 0xe1, 0x52, 0x38, 0x7d, 0xc1, 0x36, 0xce, 0xf4, 0xe5, 0x1,
906        0x30, 0x38, 0x9c, 0x38, 0xc1, 0xa4, // nwk header
907        0x28, // security control
908        0x1, 0x0, 0x0, 0x0, 0xe5, 0x1, 0x30, 0x38, 0x9c, 0x38, 0xc1, 0xa4, 0x0, //aad
909        0xa6, 0xac, 0x13, // enc_data
910        0xf8, 0x5, 0x7f, 0x53, // mic
911    ];
912
913    #[test]
914    fn decrypt_nwk_frame() {
915        let nib = setup_nib();
916        let aib = setup_aib();
917
918        let security_context = SecurityContext::new(&nib, &aib);
919        let mut frame_buffer = NWK_FRAME_CMD_BUFFER;
920
921        let frame = security_context
922            .decrypt_nwk_frame_in_place(&mut frame_buffer)
923            .unwrap();
924
925        assert!(matches!(frame, NwkFrame::NwkCommand(_)));
926    }
927
928    #[test]
929    fn decrypt_nwk_frame_records_incoming_frame_counter() {
930        let nib = setup_nib();
931        let aib = setup_aib();
932        let security_context = SecurityContext::new(&nib, &aib);
933
934        // Fixture sender is 0xa4c1_389c_3830_01e5 with frame counter 1.
935        let mut frame_buffer = NWK_FRAME_CMD_BUFFER;
936        security_context
937            .decrypt_nwk_frame_in_place(&mut frame_buffer)
938            .unwrap();
939
940        let material = nib.security_material_set();
941        let recorded = material[0]
942            .incoming_frame_counter_set
943            .iter()
944            .find(|i| i.sender_address == IeeeAddress(0xa4c1_389c_3830_01e5))
945            .map(|i| i.incoming_frame_counter);
946
947        assert_eq!(
948            recorded,
949            Some(1),
950            "decrypt must record the accepted frame counter for the sender"
951        );
952    }
953
954    // builds a NIB whose incoming frame-counter set already records accepted
955    // as the last accepted counter for the fixture's sender
956    fn nib_with_incoming_counter(accepted: u32) -> Nib {
957        let nib = Nib::new();
958
959        let mut incoming = Vec::new();
960        incoming
961            .push(IncomingFrameCounterDescriptor {
962                sender_address: IeeeAddress(0xa4c1_389c_3830_01e5),
963                incoming_frame_counter: accepted,
964            })
965            .unwrap();
966
967        let mut set = Vec::new();
968        set.push(NetworkSecurityMaterialDescriptor {
969            key_seq_number: 0,
970            outgoing_frame_counter: 1,
971            incoming_frame_counter_set: StorageVec(incoming),
972            key: ByteArray(NETWORK_KEY),
973            network_key_type: 0,
974        })
975        .unwrap();
976        nib.update_security_material_set(|value| *value = StorageVec(set));
977        nib.update_ieee_address(|value| *value = IeeeAddress(0x1234_5678_90ab_cdef));
978        nib.update_security_level(|value| *value = SecurityLevel::EncMic32);
979        nib
980    }
981
982    #[test]
983    fn decrypt_nwk_frame_rejects_replayed_frame_counter() {
984        let nib = nib_with_incoming_counter(1);
985        let aib = setup_aib();
986        let security_context = SecurityContext::new(&nib, &aib);
987        let mut frame_buffer = NWK_FRAME_CMD_BUFFER;
988
989        assert!(
990            security_context
991                .decrypt_nwk_frame_in_place(&mut frame_buffer)
992                .is_err(),
993            "replay of an already-accepted NWK frame counter must be rejected"
994        );
995    }
996
997    #[test]
998    fn decrypt_nwk_frame_accepts_newer_frame_counter() {
999        let nib = nib_with_incoming_counter(0);
1000        let aib = setup_aib();
1001        let security_context = SecurityContext::new(&nib, &aib);
1002        let mut frame_buffer = NWK_FRAME_CMD_BUFFER;
1003
1004        assert!(
1005            security_context
1006                .decrypt_nwk_frame_in_place(&mut frame_buffer)
1007                .is_ok(),
1008            "a frame counter newer than the last accepted one must be accepted"
1009        );
1010    }
1011
1012    #[test]
1013    fn encrypt_nwk_frame() {
1014        let nib = setup_nib();
1015        let aib = setup_aib();
1016        let security_context = SecurityContext::new(&nib, &aib);
1017        let mut frame_buffer = NWK_FRAME_CMD_BUFFER;
1018        let frame = security_context
1019            .decrypt_nwk_frame_in_place(&mut frame_buffer)
1020            .unwrap();
1021
1022        let mut frame_buffer = [0u8; 45];
1023        nib.update_ieee_address(|value| *value = IeeeAddress(0xa4c1_389c_3830_01e5));
1024
1025        let offset = security_context
1026            .encrypt_nwk_frame_in_place(frame, &mut frame_buffer)
1027            .unwrap();
1028
1029        assert_eq!(offset, NWK_FRAME_CMD_BUFFER.len());
1030        assert_eq!(frame_buffer[..38], NWK_FRAME_CMD_BUFFER[..38]);
1031        assert_eq!(frame_buffer[38..45], NWK_FRAME_CMD_BUFFER[38..45]);
1032    }
1033
1034    #[test]
1035    fn encrypt_nwk_frame_increments_frame_counter() {
1036        let nib = setup_nib();
1037        let aib = setup_aib();
1038        let security_context = SecurityContext::new(&nib, &aib);
1039
1040        assert_eq!(nib.security_material_set()[0].outgoing_frame_counter, 1);
1041
1042        let mut frame_buffer = NWK_FRAME_CMD_BUFFER;
1043        let frame = security_context
1044            .decrypt_nwk_frame_in_place(&mut frame_buffer)
1045            .unwrap();
1046
1047        nib.update_ieee_address(|value| *value = IeeeAddress(0xa4c1_389c_3830_01e5));
1048        let mut buf = [0u8; 45];
1049        security_context
1050            .encrypt_nwk_frame_in_place(frame, &mut buf)
1051            .unwrap();
1052
1053        assert_eq!(nib.security_material_set()[0].outgoing_frame_counter, 2);
1054
1055        // clear the incoming replay window so the captured fixture frame can be
1056        // decrypted again for a second encrypt
1057        nib.update_security_material_set(|material| {
1058            material[0].incoming_frame_counter_set = StorageVec(Vec::new());
1059        });
1060
1061        let mut frame_buffer = NWK_FRAME_CMD_BUFFER;
1062        let frame = security_context
1063            .decrypt_nwk_frame_in_place(&mut frame_buffer)
1064            .unwrap();
1065        let mut buf = [0u8; 45];
1066        security_context
1067            .encrypt_nwk_frame_in_place(frame, &mut buf)
1068            .unwrap();
1069
1070        assert_eq!(nib.security_material_set()[0].outgoing_frame_counter, 3);
1071    }
1072
1073    #[test]
1074    fn decrypt_unsecured_nwk_data_frame() {
1075        let nib = setup_nib();
1076        let aib = setup_aib();
1077        let security_context = SecurityContext::new(&nib, &aib);
1078
1079        #[rustfmt::skip]
1080        let mut frame_buffer = [
1081            0x08, 0x00, // frame control (data, protocol v2, no security)
1082            0x00, 0x00, // destination
1083            0xcd, 0xe1, // source
1084            0x01,       // radius
1085            0x42,       // sequence number
1086            // APS payload follows
1087            0xAA, 0xBB, 0xCC,
1088        ];
1089
1090        let frame = security_context
1091            .decrypt_nwk_frame_in_place(&mut frame_buffer)
1092            .unwrap();
1093
1094        let NwkFrame::Data(data_frame) = frame else {
1095            panic!("expected data frame");
1096        };
1097
1098        // payload should be the APS bytes, not the entire buffer
1099        assert_eq!(data_frame.payload, &[0xAA, 0xBB, 0xCC]);
1100    }
1101
1102    #[test]
1103    fn encrypt_aps_frame_increments_frame_counter() {
1104        let nib = setup_nib();
1105        let aib = setup_aib();
1106
1107        let dest = IeeeAddress(0xa4c1_389c_3830_01e5);
1108        append_aib_device_key_pair_set(
1109            &aib,
1110            DeviceKeyPairDescriptor {
1111                device_address: dest,
1112                key_attributes: KeyAttribute::VerifiedKey,
1113                link_key: ByteArray(TRUST_CENTER_LINK_KEY),
1114                outgoing_frame_counter: 0,
1115                incoming_frame_counter: 0,
1116                link_key_type: LinkKeyType::GlobalLinkKey,
1117            },
1118        );
1119
1120        let security_context = SecurityContext::new(&nib, &aib);
1121
1122        let mut buf = [0u8; 128];
1123        let frame_buffer = [
1124            0x21, 0x66, // aps header
1125            0x20, 0x4, 0x0, 0x0, 0x0, 0xe5, 0x1, 0x30, 0x38, 0x9c, 0x38, 0xc1,
1126            0xa4, // aux header
1127            0x1a, 0x31, // enc data
1128            0xa4, 0xd7, 0xf4, 0xd7, //mic
1129        ];
1130        let mut dec_buf = frame_buffer;
1131        let frame = security_context
1132            .decrypt_aps_frame_in_place(&mut dec_buf)
1133            .unwrap();
1134        security_context
1135            .encrypt_aps_frame_in_place(frame, &mut buf, dest, TxOptions::SecurityEnabled)
1136            .unwrap();
1137
1138        assert_eq!(
1139            aib.device_key_pair_set()
1140                .iter()
1141                .find(|k| k.device_address == dest)
1142                .unwrap()
1143                .outgoing_frame_counter,
1144            1
1145        );
1146
1147        // reset the incoming counter so the captured fixture frame can be
1148        // decrypted again for a second encrypt
1149        aib.update_device_key_pair_set(|key_set| {
1150            if let Some(k) = key_set.iter_mut().find(|k| k.device_address == dest) {
1151                k.incoming_frame_counter = 0;
1152            }
1153        });
1154
1155        let mut dec_buf = frame_buffer;
1156        let frame = security_context
1157            .decrypt_aps_frame_in_place(&mut dec_buf)
1158            .unwrap();
1159        security_context
1160            .encrypt_aps_frame_in_place(frame, &mut buf, dest, TxOptions::SecurityEnabled)
1161            .unwrap();
1162
1163        assert_eq!(
1164            aib.device_key_pair_set()
1165                .iter()
1166                .find(|k| k.device_address == dest)
1167                .unwrap()
1168                .outgoing_frame_counter,
1169            2
1170        );
1171    }
1172}