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
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
//! Implements IEEE 802.15.4 MAC device abstraction over a 802.15.4 MAC interface.
//! Allows its users to prepare and send frames in plaintext, handling 802.15.4
//! encoding and security procedures (in the future) transparently.
//!
//! However, certain IEEE 802.15.4 MAC device concepts are not implemented in
//! this layer of abstraction and instead handled in hardware for performance
//! purposes. These include CSMA-CA backoff, FCS generation and authentication,
//! and automatic acknowledgement. Radio power management and channel selection
//! is also passed down to the MAC control layer.
//!
//! Usage
//! -----
//!
//! To use this capsule, we need an implementation of a hardware
//! `capsules::ieee802154::mac::Mac`. Suppose we have such an implementation of type
//! `XMacDevice`.
//!
//! ```rust
//! let xmac: &XMacDevice = /* ... */;
//! let mac_device = static_init!(
//!     capsules::ieee802154::mac::Framer<'static, XMacDevice>,
//!     capsules::ieee802154::mac::Framer::new(xmac));
//! xmac.set_transmit_client(mac_device);
//! xmac.set_receive_client(mac_device, &mut MAC_RX_BUF);
//! xmac.set_config_client(mac_device);
//! ```
//!
//! The `mac_device` device is now set up. Users of the MAC device can now
//! configure the underlying radio, prepare and send frames:
//!
//! ```rust
//! mac_device.set_pan(0xABCD);
//! mac_device.set_address(0x1008);
//! mac_device.config_commit();
//!
//! let frame = mac_device
//!     .prepare_data_frame(&mut STATIC_BUFFER,
//!                         0xABCD, MacAddress::Short(0x1008),
//!                         0xABCD, MacAddress::Short(0x1009),
//!                         None)
//!     .ok()
//!     .map(|frame| {
//!         let rval = frame.append_payload(&mut SOME_DATA[..10]);
//!         if rval == ReturnCode::SUCCESS {
//!             let (rval, _) = mac_device.transmit(frame);
//!             rval
//!         } else {
//!             rval
//!         }
//!     });
//! ```
//!
//! You should also be able to set up the userspace driver for receiving/sending
//! 802.15.4 frames:
//!
//! ```rust
//! let radio_capsule = static_init!(
//!     capsules::ieee802154::RadioDriver<'static>,
//!     capsules::ieee802154::RadioDriver::new(mac_device, kernel::Grant::create(), &mut RADIO_BUF));
//! mac_device.set_key_procedure(radio_capsule);
//! mac_device.set_device_procedure(radio_capsule);
//! mac_device.set_transmit_client(radio_capsule);
//! mac_device.set_receive_client(radio_capsule);
//! ```

//
// TODO: Encryption/decryption
// TODO: Sending beacon frames
// TODO: Channel scanning
//

use core::cell::Cell;
use ieee802154::device::{MacDevice, RxClient, TxClient};
use ieee802154::mac::Mac;
use kernel::ReturnCode;
use kernel::common::take_cell::MapCell;
use kernel::hil::radio;
use kernel::hil::symmetric_encryption::{AES128CCM, CCMClient};
use net::ieee802154::*;
use net::stream::{encode_bytes, encode_u32, encode_u8};
use net::stream::SResult;

/// A `Frame` wraps a static mutable byte slice and keeps just enough
/// information about its header contents to expose a restricted interface for
/// modifying its payload. This enables the user to abdicate any concerns about
/// where the payload should be placed in the buffer.
#[derive(Eq, PartialEq, Debug)]
pub struct Frame {
    buf: &'static mut [u8],
    info: FrameInfo,
}

/// This contains just enough information about a frame to determine
///
/// 1. How to encode it once its payload has been finalized
/// 2. The sizes of the mac header, payload and MIC tag length to be added
///
/// These offsets are relative to the PSDU or `buf[radio::PSDU_OFFSET..]` so
/// that the mac frame length is `data_offset + data_len`
#[derive(Copy, Clone, Eq, PartialEq, Debug)]
struct FrameInfo {
    frame_type: FrameType,

    // The MAC payload, including Payload IEs
    mac_payload_offset: usize,
    // The data payload, not including Payload IEs
    data_offset: usize,
    // The length of the data payload, not including MIC and FCS
    data_len: usize,
    // The length of the MIC
    mic_len: usize,

    // Security level, key, and nonce
    security_params: Option<(SecurityLevel, [u8; 16], [u8; 13])>,
}

impl Frame {
    /// Consumes the frame and retrieves the buffer it wraps
    pub fn into_buf(self) -> &'static mut [u8] {
        self.buf
    }

    /// Calculates how much more data this frame can hold
    pub fn remaining_data_capacity(&self) -> usize {
        self.buf.len() - radio::PSDU_OFFSET - radio::MFR_SIZE - self.info.secured_length()
    }

    /// Appends payload bytes into the frame if possible
    pub fn append_payload(&mut self, payload: &[u8]) -> ReturnCode {
        if payload.len() > self.remaining_data_capacity() {
            return ReturnCode::ENOMEM;
        }
        let begin = radio::PSDU_OFFSET + self.info.unsecured_length();
        self.buf[begin..begin + payload.len()].copy_from_slice(payload);
        self.info.data_len += payload.len();

        ReturnCode::SUCCESS
    }
}

impl FrameInfo {
    /// Current size of the frame, not including the MAC footer or the MIC
    fn unsecured_length(&self) -> usize {
        self.data_offset + self.data_len
    }

    /// Current size of the frame, not including the MAC footer but including
    /// the MIC
    fn secured_length(&self) -> usize {
        self.data_offset + self.data_len + self.mic_len
    }

    /// Compute the offsets in the buffer for the a data and m data fields in
    /// the CCM* authentication and encryption procedures which depends on the
    /// frame type and security levels. Returns the (offset, len) of the m data
    /// fields, not including the MIC. The a data is always the remaining prefix
    /// of the header, so it can be determined implicitly.
    #[allow(dead_code)]
    fn ccm_encrypt_ranges(&self) -> (usize, usize) {
        // IEEE 802.15.4-2015: Table 9-1. Exceptions to Private Payload field
        // The boundary between open and private payload fields depends
        // on the type of frame.
        let private_payload_offset = match self.frame_type {
            FrameType::Beacon => {
                // Beginning of beacon payload field
                unimplemented!()
            }
            FrameType::MACCommand => {
                // Beginning of MAC command content field
                unimplemented!()
            }
            _ => {
                // MAC payload field, which includes payload IEs
                self.mac_payload_offset
            }
        };

        // IEEE 802.15.4-2015: Table 9-3. a data and m data
        let encryption_needed = self.security_params
            .map_or(false, |(level, _, _)| level.encryption_needed());
        if !encryption_needed {
            // If only integrity is need, a data is the whole frame
            (self.unsecured_length(), 0)
        } else {
            // Otherwise, a data is the header and the open payload, and
            // m data is the private payload field
            (
                private_payload_offset,
                self.unsecured_length() | private_payload_offset,
            )
        }
    }
}

fn get_ccm_nonce(device_addr: &[u8; 8], frame_counter: u32, level: SecurityLevel) -> [u8; 13] {
    let mut nonce = [0u8; 13];
    let encode_ccm_nonce = |buf: &mut [u8]| {
        let off = enc_consume!(buf; encode_bytes, device_addr.as_ref());
        let off = enc_consume!(buf, off; encode_u32, frame_counter);
        let off = enc_consume!(buf, off; encode_u8, level as u8);
        stream_done!(off);
    };
    match encode_ccm_nonce(&mut nonce).done() {
        None => {
            // This should not be possible
            panic!("Failed to produce ccm nonce");
        }
        Some(_) => nonce,
    }
}

/// The needed buffer size might be bigger than an MTU, because
/// the CCM* authentication procedure
///
/// - adds an extra 16-byte block in front of the a and m data
/// - prefixes the a data with a length encoding and pads the result
/// - pads the m data to 16-byte blocks
pub const CRYPT_BUF_SIZE: usize = radio::MAX_MTU + 3 * 16;

/// IEEE 802.15.4-2015, 9.2.2, KeyDescriptor lookup procedure.
/// Trait to be implemented by an upper layer that manages the list of 802.15.4
/// key descriptors. This trait interface enables the lookup procedure to be
/// implemented either explicitly (managing a list of KeyDescriptors) or
/// implicitly with some equivalent logic.
pub trait KeyProcedure {
    /// Lookup the KeyDescriptor matching the provided security level and key ID
    /// mode and return the key associatied with it.
    fn lookup_key(&self, level: SecurityLevel, key_id: KeyId) -> Option<([u8; 16])>;
}

/// IEEE 802.15.4-2015, 9.2.5, DeviceDescriptor lookup procedure.
/// Trait to be implemented by an upper layer that manages the list of 802.15.4
/// device descriptors. This trait interface enables the lookup procedure to be
/// implemented either explicitly (managing a list of DeviceDescriptors) or
/// implicitly with some equivalent logic.
pub trait DeviceProcedure {
    /// Look up the extended MAC address of a device given either its short or
    /// long address. As defined in the IEEE 802.15.4 spec, even if the provided
    /// address is already long, a long address should be returned only if the
    /// given address matches a known DeviceDescriptor.
    fn lookup_addr_long(&self, addr: MacAddress) -> Option<([u8; 8])>;
}

/// This state enum describes the state of the transmission pipeline.
/// Conditionally-present state is also included as fields in the enum variants.
/// We can view the transmission process as a state machine driven by the
/// following events:
///
/// - calls to `Mac#transmit`
/// - `send_done` callbacks from the underlying radio
/// - `config_done` callbacks from the underlying radio (if, for example,
///   configuration was in progress when a transmission was requested)
#[derive(Eq, PartialEq, Debug)]
enum TxState {
    /// There is no frame to be transmitted.
    Idle,
    /// There is a valid frame that needs to be secured before transmission.
    ReadyToEncrypt(FrameInfo, &'static mut [u8]),
    /// There is currently a frame being encrypted by the encryption facility.
    #[allow(dead_code)]
    Encrypting(FrameInfo),
    /// There is a frame that is completely secured or does not require
    /// security, and is waiting to be passed to the radio.
    ReadyToTransmit(FrameInfo, &'static mut [u8]),
}

#[derive(Eq, PartialEq, Debug)]
enum RxState {
    /// There is no frame that has been received.
    Idle,
    /// There is a secured frame that needs to be decrypted.
    ReadyToDecrypt(FrameInfo, &'static mut [u8]),
    /// A secured frame is currently being decrypted by the decryption facility.
    #[allow(dead_code)]
    Decrypting(FrameInfo),
    /// There is an unsecured frame that needs to be re-parsed and exposed to
    /// the client.
    #[allow(dead_code)]
    ReadyToYield(FrameInfo, &'static mut [u8]),
    /// The buffer containing the frame needs to be returned to the radio.
    ReadyToReturn(&'static mut [u8]),
}

/// This struct wraps an IEEE 802.15.4 radio device `kernel::hil::radio::Radio`
/// and exposes IEEE 802.15.4 MAC device functionality as the trait
/// `capsules::mac::Mac`. It hides header preparation, transmission and
/// processing logic from the user by essentially maintaining multiple state
/// machines corresponding to the transmission, reception and
/// encryption/decryption pipelines. See the documentation in
/// `capsules/src/mac.rs` for more details.
pub struct Framer<'a, M: Mac + 'a, A: AES128CCM<'a> + 'a> {
    mac: &'a M,
    aes_ccm: &'a A,
    data_sequence: Cell<u8>,

    /// KeyDescriptor lookup procedure
    key_procedure: Cell<Option<&'a KeyProcedure>>,
    /// DeviceDescriptor lookup procedure
    device_procedure: Cell<Option<&'a DeviceProcedure>>,

    /// Transmision pipeline state. This should never be `None`, except when
    /// transitioning between states. That is, any method that consumes the
    /// current state should always remember to replace it along with the
    /// associated state information.
    tx_state: MapCell<TxState>,
    tx_client: Cell<Option<&'a TxClient>>,

    /// Reception pipeline state. Similar to the above, this should never be
    /// `None`, except when transitioning between states.
    rx_state: MapCell<RxState>,
    rx_client: Cell<Option<&'a RxClient>>,
}

impl<'a, M: Mac + 'a, A: AES128CCM<'a> + 'a> Framer<'a, M, A> {
    pub fn new(mac: &'a M, aes_ccm: &'a A) -> Framer<'a, M, A> {
        Framer {
            mac: mac,
            aes_ccm: aes_ccm,
            data_sequence: Cell::new(0),
            key_procedure: Cell::new(None),
            device_procedure: Cell::new(None),
            tx_state: MapCell::new(TxState::Idle),
            tx_client: Cell::new(None),
            rx_state: MapCell::new(RxState::Idle),
            rx_client: Cell::new(None),
        }
    }

    /// Sets the IEEE 802.15.4 key lookup procedure to be used.
    pub fn set_key_procedure(&self, key_procedure: &'a KeyProcedure) {
        self.key_procedure.set(Some(key_procedure));
    }

    /// Sets the IEEE 802.15.4 key lookup procedure to be used.
    pub fn set_device_procedure(&self, device_procedure: &'a DeviceProcedure) {
        self.device_procedure.set(Some(device_procedure));
    }

    /// Look up the key using the IEEE 802.15.4 KeyDescriptor lookup prodecure
    /// implemented elsewhere.
    fn lookup_key(&self, level: SecurityLevel, key_id: KeyId) -> Option<([u8; 16])> {
        self.key_procedure
            .get()
            .and_then(|key_procedure| key_procedure.lookup_key(level, key_id))
    }

    /// Look up the extended address of a device using the IEEE 802.15.4
    /// DeviceDescriptor lookup prodecure implemented elsewhere.
    fn lookup_addr_long(&self, src_addr: Option<MacAddress>) -> Option<([u8; 8])> {
        src_addr.and_then(|addr| {
            self.device_procedure
                .get()
                .and_then(|device_procedure| device_procedure.lookup_addr_long(addr))
        })
    }

    /// IEEE 802.15.4-2015, 9.2.1, outgoing frame security procedure
    /// Performs the first checks in the security procedure. The rest of the
    /// steps are performed as part of the transmission pipeline.
    /// Returns the next `TxState` to enter.
    fn outgoing_frame_security(&self, buf: &'static mut [u8], frame_info: FrameInfo) -> TxState {
        // IEEE 802.15.4-2015: 9.2.1, outgoing frame security
        // Steps a-e have already been performed in the frame preparation step,
        // so we only need to dispatch on the security parameters in the frame info
        match frame_info.security_params {
            Some((level, _, _)) => {
                if level == SecurityLevel::None {
                    // This case should never occur if the FrameInfo was
                    // prepared by prepare_data_frame
                    TxState::ReadyToTransmit(frame_info, buf)
                } else {
                    TxState::ReadyToEncrypt(frame_info, buf)
                }
            }
            None => TxState::ReadyToTransmit(frame_info, buf),
        }
    }

    /// IEEE 802.15.4-2015, 9.2.3, incoming frame security procedure
    fn incoming_frame_security(&self, buf: &'static mut [u8], frame_len: usize) -> RxState {
        // Try to decode the MAC header. Three possible results can occur:
        // 1) The frame should be dropped and the buffer returned to the radio
        // 2) The frame is unsecured. We immediately expose the frame to the
        //    user and queue the buffer for returning to the radio.
        // 3) The frame needs to be unsecured.
        let result = Header::decode(&buf[radio::PSDU_OFFSET..], false)
            .done()
            .and_then(|(data_offset, (header, mac_payload_offset))| {
                // Note: there is a complication here regarding the offsets.
                // When the received frame has security enabled, the payload
                // (including the payload IEs) is encrypted, and hence the data
                // payload field includes the encrypted payload IEs too.
                // However, when the frame is not encrypted, the data payload
                // field does not include the payload IEs.
                //
                // This is fine because we re-parse the unsecured frame before
                // exposing it to the user. At that time, the data payload field
                // will not include the payload IEs.
                let mic_len = header.security.map_or(0, |sec| sec.level.mic_len());
                let data_len = frame_len - data_offset - mic_len;
                if let Some(security) = header.security {
                    // IEEE 802.15.4-2015: 9.2.3, incoming frame security procedure
                    // for security-enabled headers
                    if header.version == FrameVersion::V2003 {
                        None
                    } else {
                        // Step e: Lookup the key.
                        let key = match self.lookup_key(security.level, security.key_id) {
                            Some(key) => key,
                            None => {
                                return None;
                            }
                        };

                        // Step f: Obtain the extended source address
                        // TODO: For Thread, when the frame's security header
                        // specifies `KeyIdMode::Source4Index`, the source
                        // address used for the nonce is actually a constant
                        // defined in their spec
                        let device_addr = match self.lookup_addr_long(header.src_addr) {
                            Some(addr) => addr,
                            None => {
                                return None;
                            }
                        };

                        // Step g, h: Check frame counter
                        let frame_counter = match security.frame_counter {
                            Some(frame_counter) => {
                                if frame_counter == 0xffffffff {
                                    // Counter error
                                    return None;
                                }
                                // TODO: Check frame counter against source device
                                frame_counter
                            }
                            // TSCH mode, where ASN is used instead, not supported
                            None => {
                                return None;
                            }
                        };

                        // Compute ccm nonce
                        let nonce = get_ccm_nonce(&device_addr, frame_counter, security.level);

                        Some(FrameInfo {
                            frame_type: header.frame_type,
                            mac_payload_offset: mac_payload_offset,
                            data_offset: data_offset,
                            data_len: data_len,
                            mic_len: mic_len,
                            security_params: Some((security.level, key, nonce)),
                        })
                    }
                } else {
                    // No security needed, can yield the frame immediately
                    self.rx_client.get().map(|client| {
                        client.receive(&buf, header, radio::PSDU_OFFSET + data_offset, data_len);
                    });
                    None
                }
            });

        match result {
            None => RxState::ReadyToReturn(buf),
            Some(frame_info) => RxState::ReadyToDecrypt(frame_info, buf),
        }
    }

    /// Advances the transmission pipeline if it can be advanced.
    fn step_transmit_state(&self) -> (ReturnCode, Option<&'static mut [u8]>) {
        self.tx_state
            .take()
            .map_or((ReturnCode::FAIL, None), |state| {
                // This mechanism is a little more clunky, but makes it
                // difficult to forget to replace `tx_state`.
                let (next_state, result) = match state {
                    TxState::Idle => (TxState::Idle, (ReturnCode::SUCCESS, None)),
                    TxState::ReadyToEncrypt(info, buf) => {
                        match info.security_params {
                            None => {
                                // `ReadyToEncrypt` should only be entered when
                                // `security_params` is not `None`.
                                (TxState::Idle, (ReturnCode::FAIL, Some(buf)))
                            }
                            Some((level, key, nonce)) => {
                                let (m_off, m_len) = info.ccm_encrypt_ranges();
                                let (a_off, m_off) =
                                    (radio::PSDU_OFFSET, radio::PSDU_OFFSET + m_off);

                                if self.aes_ccm.set_key(&key) != ReturnCode::SUCCESS
                                    || self.aes_ccm.set_nonce(&nonce) != ReturnCode::SUCCESS
                                {
                                    (TxState::Idle, (ReturnCode::FAIL, Some(buf)))
                                } else {
                                    let (res, opt_buf) = self.aes_ccm.crypt(
                                        buf,
                                        a_off,
                                        m_off,
                                        m_len,
                                        info.mic_len,
                                        level.encryption_needed(),
                                        true,
                                    );
                                    match res {
                                        ReturnCode::SUCCESS => {
                                            (TxState::Encrypting(info), (res, None))
                                        }
                                        ReturnCode::EBUSY => {
                                            let buf = match opt_buf {
                                                Some(buf) => buf,
                                                None => panic!("aes_ccm did not return the buffer"),
                                            };
                                            (
                                                TxState::ReadyToEncrypt(info, buf),
                                                (ReturnCode::SUCCESS, None),
                                            )
                                        }
                                        _ => (TxState::Idle, (res, opt_buf)),
                                    }
                                }
                            }
                        }
                    }
                    TxState::Encrypting(info) => {
                        // This state should be advanced only by the hardware
                        // encryption callback.
                        (TxState::Encrypting(info), (ReturnCode::SUCCESS, None))
                    }
                    TxState::ReadyToTransmit(info, buf) => {
                        let (rval, buf) = self.mac.transmit(buf, info.secured_length());
                        match rval {
                            // If the radio is busy, just wait for either a
                            // transmit_done or config_done callback to trigger
                            // this state transition again
                            ReturnCode::EBUSY => {
                                match buf {
                                    None => {
                                        // The radio forgot to return the buffer.
                                        (TxState::Idle, (ReturnCode::FAIL, None))
                                    }
                                    Some(buf) => (
                                        TxState::ReadyToTransmit(info, buf),
                                        (ReturnCode::SUCCESS, None),
                                    ),
                                }
                            }
                            _ => (TxState::Idle, (rval, buf)),
                        }
                    }
                };
                self.tx_state.replace(next_state);
                result
            })
    }

    /// Advances the reception pipeline if it can be advanced.
    fn step_receive_state(&self) {
        self.rx_state.take().map(|state| {
            let (next_state, buf) = match state {
                RxState::Idle => (RxState::Idle, None),
                RxState::ReadyToDecrypt(info, buf) => {
                    match info.security_params {
                        None => {
                            // `ReadyToDecrypt` should only be entered when
                            // `security_params` is not `None`.
                            (RxState::Idle, Some(buf))
                        }
                        Some((level, key, nonce)) => {
                            let (m_off, m_len) = info.ccm_encrypt_ranges();
                            let (a_off, m_off) = (radio::PSDU_OFFSET, radio::PSDU_OFFSET + m_off);

                            if self.aes_ccm.set_key(&key) != ReturnCode::SUCCESS
                                || self.aes_ccm.set_nonce(&nonce) != ReturnCode::SUCCESS
                            {
                                (RxState::Idle, Some(buf))
                            } else {
                                let (res, opt_buf) = self.aes_ccm.crypt(
                                    buf,
                                    a_off,
                                    m_off,
                                    m_len,
                                    info.mic_len,
                                    level.encryption_needed(),
                                    true,
                                );
                                match res {
                                    ReturnCode::SUCCESS => (RxState::Decrypting(info), None),
                                    ReturnCode::EBUSY => {
                                        let buf = match opt_buf {
                                            Some(buf) => buf,
                                            None => panic!("aes_ccm did not return the buffer"),
                                        };
                                        (RxState::ReadyToDecrypt(info, buf), None)
                                    }
                                    _ => (RxState::Idle, opt_buf),
                                }
                            }
                        }
                    }
                }
                RxState::Decrypting(info) => {
                    // This state should be advanced only by the hardware
                    // encryption callback.
                    (RxState::Decrypting(info), None)
                }
                RxState::ReadyToYield(info, buf) => {
                    // Between the secured and unsecured frames, the
                    // unsecured frame length remains constant but the data
                    // offsets may change due to the presence of PayloadIEs.
                    // Hence, we can only use the unsecured length from the
                    // frame info, but not the offsets.
                    let frame_len = info.unsecured_length();
                    if let Some((data_offset, (header, _))) =
                        Header::decode(&buf[radio::PSDU_OFFSET..], true).done()
                    {
                        // IEEE 802.15.4-2015 specifies that unsecured
                        // frames do not have auxiliary security headers,
                        // but we do not remove the auxiliary security
                        // header before returning the frame to the client.
                        // This is so that it is possible to tell if the
                        // frame was secured or unsecured, while still
                        // always receiving the frame payload in plaintext.
                        self.rx_client.get().map(|client| {
                            client.receive(
                                &buf,
                                header,
                                radio::PSDU_OFFSET + data_offset,
                                frame_len - data_offset,
                            );
                        });
                    }
                    (RxState::Idle, Some(buf))
                }
                RxState::ReadyToReturn(buf) => (RxState::Idle, Some(buf)),
            };
            self.rx_state.replace(next_state);

            // Return the buffer to the radio if we are done with it.
            if let Some(buf) = buf {
                self.mac.set_receive_buffer(buf);
            }
        });
    }
}

impl<'a, M: Mac + 'a, A: AES128CCM<'a> + 'a> MacDevice<'a> for Framer<'a, M, A> {
    fn set_transmit_client(&self, client: &'a TxClient) {
        self.tx_client.set(Some(client));
    }

    fn set_receive_client(&self, client: &'a RxClient) {
        self.rx_client.set(Some(client));
    }

    fn get_address(&self) -> u16 {
        self.mac.get_address()
    }

    fn get_address_long(&self) -> [u8; 8] {
        self.mac.get_address_long()
    }

    fn get_pan(&self) -> u16 {
        self.mac.get_pan()
    }

    fn set_address(&self, addr: u16) {
        self.mac.set_address(addr)
    }

    fn set_address_long(&self, addr: [u8; 8]) {
        self.mac.set_address_long(addr)
    }

    fn set_pan(&self, id: u16) {
        self.mac.set_pan(id)
    }

    fn config_commit(&self) {
        self.mac.config_commit()
    }

    fn is_on(&self) -> bool {
        self.mac.is_on()
    }

    fn prepare_data_frame(
        &self,
        buf: &'static mut [u8],
        dst_pan: PanID,
        dst_addr: MacAddress,
        src_pan: PanID,
        src_addr: MacAddress,
        security_needed: Option<(SecurityLevel, KeyId)>,
    ) -> Result<Frame, &'static mut [u8]> {
        // IEEE 802.15.4-2015: 9.2.1, outgoing frame security
        // Steps a-e of the security procedure are implemented here.

        // TODO: For Thread, in the case of `KeyIdMode::Source4Index`, the source
        // address should instead be some constant defined in their
        // specification.
        let src_addr_long = self.get_address_long();
        let security_desc = security_needed.and_then(|(level, key_id)| {
            self.lookup_key(level, key_id).map(|key| {
                // TODO: lookup frame counter for device
                let frame_counter = 0;
                let nonce = get_ccm_nonce(&src_addr_long, frame_counter, level);
                (
                    Security {
                        level: level,
                        asn_in_nonce: false,
                        frame_counter: Some(frame_counter),
                        key_id: key_id,
                    },
                    key,
                    nonce,
                )
            })
        });
        if security_needed.is_some() && security_desc.is_none() {
            // If security was requested, fail when desired key was not found.
            return Err(buf);
        }

        // Construct MAC header
        let security = security_desc.map(|(sec, _, _)| sec);
        let mic_len = security.map_or(0, |sec| sec.level.mic_len());
        let header = Header {
            frame_type: FrameType::Data,
            /* TODO: determine this by looking at queue, and also set it in
             * hardware so that ACKs set this flag to the right value. */
            frame_pending: false,
            // Unicast data frames request acknowledgement
            ack_requested: true,
            version: FrameVersion::V2015,
            seq: Some(self.data_sequence.get()),
            dst_pan: Some(dst_pan),
            dst_addr: Some(dst_addr),
            src_pan: Some(src_pan),
            src_addr: Some(src_addr),
            security: security,
            header_ies: Default::default(),
            header_ies_len: 0,
            payload_ies: Default::default(),
            payload_ies_len: 0,
        };

        match header.encode(&mut buf[radio::PSDU_OFFSET..], true).done() {
            Some((data_offset, mac_payload_offset)) => Ok(Frame {
                buf: buf,
                info: FrameInfo {
                    frame_type: FrameType::Data,
                    mac_payload_offset: mac_payload_offset,
                    data_offset: data_offset,
                    data_len: 0,
                    mic_len: mic_len,
                    security_params: security_desc.map(|(sec, key, nonce)| (sec.level, key, nonce)),
                },
            }),
            None => Err(buf),
        }
    }

    fn transmit(&self, frame: Frame) -> (ReturnCode, Option<&'static mut [u8]>) {
        let Frame { buf, info } = frame;
        let state = match self.tx_state.take() {
            None => {
                return (ReturnCode::FAIL, Some(buf));
            }
            Some(state) => state,
        };
        match state {
            TxState::Idle => {
                let next_state = self.outgoing_frame_security(buf, info);
                self.tx_state.replace(next_state);
                self.step_transmit_state()
            }
            other_state => {
                self.tx_state.replace(other_state);
                (ReturnCode::EBUSY, Some(buf))
            }
        }
    }
}

impl<'a, M: Mac + 'a, A: AES128CCM<'a> + 'a> radio::TxClient for Framer<'a, M, A> {
    fn send_done(&self, buf: &'static mut [u8], acked: bool, result: ReturnCode) {
        self.data_sequence.set(self.data_sequence.get() + 1);
        self.tx_client.get().map(move |client| {
            client.send_done(buf, acked, result);
        });
    }
}

impl<'a, M: Mac + 'a, A: AES128CCM<'a> + 'a> radio::RxClient for Framer<'a, M, A> {
    fn receive(&self, buf: &'static mut [u8], frame_len: usize, crc_valid: bool, _: ReturnCode) {
        // Drop all frames with invalid CRC
        if !crc_valid {
            self.mac.set_receive_buffer(buf);
            return;
        }

        self.rx_state.take().map(move |state| {
            let next_state = match state {
                RxState::Idle => {
                    // We can start processing a new received frame only if
                    // the reception pipeline is free
                    self.incoming_frame_security(buf, frame_len)
                }
                other_state => {
                    // This should never occur unless something other than
                    // this MAC layer provided a receive buffer to the
                    // radio, but if this occurs then we have no choice but
                    // to drop the frame.
                    self.mac.set_receive_buffer(buf);
                    other_state
                }
            };
            self.rx_state.replace(next_state);
            self.step_receive_state();
        });
    }
}

impl<'a, M: Mac + 'a, A: AES128CCM<'a> + 'a> radio::ConfigClient for Framer<'a, M, A> {
    fn config_done(&self, _: ReturnCode) {
        // The transmission pipeline is the only state machine that
        // waits for the configuration procedure to complete before
        // advancing.
        let (rval, buf) = self.step_transmit_state();
        if let Some(buf) = buf {
            // Return the buffer to the transmit client
            self.tx_client.get().map(move |client| {
                client.send_done(buf, false, rval);
            });
        }
    }
}

impl<'a, M: Mac + 'a, A: AES128CCM<'a> + 'a> CCMClient for Framer<'a, M, A> {
    fn crypt_done(&self, buf: &'static mut [u8], res: ReturnCode, tag_is_valid: bool) {
        let mut tx_waiting = false;
        let mut rx_waiting = false;

        // The crypto operation was from the transmission pipeline.
        let opt_buf = if let Some(state) = self.tx_state.take() {
            match state {
                TxState::Encrypting(info) => {
                    let (rval, opt_buf) = if res != ReturnCode::SUCCESS {
                        self.tx_state.replace(TxState::Idle);
                        (res, Some(buf))
                    } else {
                        self.tx_state.replace(TxState::ReadyToTransmit(info, buf));
                        self.step_transmit_state()
                    };

                    if let Some(buf) = opt_buf {
                        // Abort the transmission process. Return the buffer to the client.
                        self.tx_client.get().map(move |client| {
                            client.send_done(buf, false, rval);
                        });
                    }
                    None
                }
                other_state => {
                    tx_waiting = match other_state {
                        TxState::ReadyToEncrypt(_, _) => true,
                        _ => false,
                    };
                    self.tx_state.replace(other_state);
                    Some(buf)
                }
            }
        } else {
            Some(buf)
        };

        // The crypto operation was from the reception pipeline.
        if let Some(buf) = opt_buf {
            self.rx_state.take().map(move |state| {
                match state {
                    RxState::Decrypting(info) => {
                        let next_state = if tag_is_valid {
                            RxState::ReadyToYield(info, buf)
                        } else {
                            RxState::ReadyToReturn(buf)
                        };
                        self.rx_state.replace(next_state);
                        self.step_receive_state();
                    }
                    other_state => {
                        rx_waiting = match other_state {
                            RxState::ReadyToDecrypt(_, _) => true,
                            _ => false,
                        };
                        self.rx_state.replace(other_state);
                    }
                };
            });
        }

        // Now trigger the next crypto operation if one exists.
        if tx_waiting {
            let (rval, opt_buf) = self.step_transmit_state();
            if let Some(buf) = opt_buf {
                // Return the buffer to the client.
                self.tx_client.get().map(move |client| {
                    client.send_done(buf, false, rval);
                });
            }
        } else if rx_waiting {
            self.step_receive_state();
        }
    }
}