Retransmissions of frames containing time-dependent header Information
Elements (IEs), such as CSL or Time Sync, require updates to these
IEs to reflect the exact time of sending. If the frame counter is not
incremented for these retransmissions, it leads to nonce reuse in
AES-CCM encryption, which is a security vulnerability.
This commit addresses this issue by ensuring that every transmission
attempt (initial or retry) uses a fresh frame counter:
- Deferred security processing from `SubMac::Send()` to
`SubMac::BeginTransmit()`.
- Upon retransmission in `SubMac::HandleTransmitDone()`, the frame is
restored to plaintext via `TxFrame::DecryptTransmitAesCcm()` and
security flags are cleared.
- This allows time-dependent IEs to be updated and a new frame counter
to be assigned for every attempt.
Added a Nexus test case `retransmission_security` to verify that both
CSL and standard MAC retransmissions use incrementing frame counters
and updated CSL phases.
This commit enables the format-nonliteral check for code missed in
`#12236`. This commit also enables the format-nonliteral warnings in
CMake to catch such warnings in future in CMake build.
The description of the method `otPlatRadioEnableCsl()` requires the platform
to include the CSL IE in the enhanced ACK when the received data frame's source
address matches the CSL receiver's peer address. This commit implements this
requirement in the simulation radio.
The simulation platform radio driver doesn't set the 'mInfo.mTxInfo.mIeInfo'
field of the ACK frame. And the function 'otMacFrameUpdateTimeIe()' directly
use the 'mInfo.mTxInfo.mIeInfo' field, this may cause the program crash.
This commit checks whether 'mInfo.mTxInfo.mIeInfo' is null before using it
and sets the 'mInfo.mTxInfo.mIeInfo' field of the ACK frame to null in
simulation platform.
The wakeup frame is sent from the wakeup coordinator rather than the
wakeup end device. Current code processes the key id mode 2 only when
the device is the wakeup end device. This commit corrects this issue.
If the radio driver supports the `OT_RADIO_CAPS_TRANSMIT_SEC`, the
radio driver should process the security of the send frame. But the
current method `otMacFrameProcessTransmitSecurity()` doesn't process
the security of the wakeup frame. Which causes sent wakeup frame is not
encrypted.
This commit enables the method `otMacFrameProcessTransmitSecurity()`
to process the security of the wakeup frame.
This commit introduces a mechanism for a device transitioning from
child to router role to keep receiving frames addressed to its
previous short address for a brief period.
A new radio platform API, `otPlatRadioSetAlternateShortAddress()`, is
introduced. This allows the OT stack to configure an alternate short
address. Radio platform support for this function is indicated by the
`OT_RADIO_CAPS_ALT_SHORT_ADDR` capability in `otPlatRadioGetCaps()`
The same function can be used with `OT_RADIO_INVALID_SHORT_ADDR`
(`0xfffe`) to clear a previously set alternate short address. Support
for the new API is implemented in RCP and `RadioSpinel`, ensuring
backward compatibility by dynamically checking supported radio
capabilities.
MLE code is updated to instruct the radio to use the old child RLOC16
as an alternate address upon role transition. The MLE layer will
automatically clear the alternate address after eight seconds, or if
other state/mode changes occur. This eight-second window ensures the
new router can transmit four MLE Advertisement messages.
This commit updates how we prepare the MAC headers:
- New `enum`s are defined in `Mac::Frame` to specify the frame
`Type`, `Version`, `SecurityLevel`, etc.
- `InitMacHeader()` will itself determine the Frame Control Field
from the given address info.
- It now uses `FrameBuilder` to prepare the headers.
- New helper `MeshForwarder::PrepareMacHeaders()` is added which
takes care of adding MAC (address, security header) along with
any IE headers.
- These changes ensure that PAN ID Compression bit is properly
set on MAC frames when using 2015 version (ensure that PAN
IDs are not omitted when both addresses use Extended format).
This commit splits OPENTHREAD_CONFIG_MLE_LINK_METRICS_ENABLE macro
into two subsequent ones:
- OPENTHREAD_CONFIG_MLE_LINK_METRICS_SUBJECT_ENABLE
- OPENTHREAD_CONFIG_MLE_LINK_METRICS_INITIATOR_ENABLE
This commit refactors the code to set frame version, IE present field
in frame control field and to append Header IE.
- Split UpdateFrameControlField into two methods: CalcIePresent and
CalcFrameVersion. Currently UpdateFrameControlField` is not
easy-to-read and hard to extend the method to handle more cases.
- Move this code from Mac to MeshForwarder. I think it should be
MeshForwarder's responsibility (PrepareDataFrame) to prepare the
frame (though Mac sometimes prepare data frames itself). Since when
preparing the frame, most information comes from the Message which
is only in MeshForwarder, we can put this code for preparing frame
in MeshForwarder.
- Enhance the way to append Header IEs to the frame. Currently in
Mac::AppendHeaderIe, it generates a list of HeaderIe first and then
call Frame::AppendHeaderIe. There are two problems here: 1. it uses
another copy (copy HeaderIe to the frame's buffer). 2. it has to
initialize Vendor IE (e.g. TimeSync IE) after Vendor IE header has
been copied to the buffer. Currently it directly finds the first
Vendor IE in the buffer and initialize it as TimeSync IE, which is
not extensible. This commit shifts the responsibility of 'how to
append the IE' to Frame, by providing AppendHeaderIeAt method. And
MeshForwarder can decide which IEs to append and directly call the
method to append IEs to the frame.
This commit implements Enhanced-ACK Probing (on simulation platform).
- Add a new public API otLinkMetricsConfigEnhAckProbing which sends
Link Metrics Management Request to configure the probing. This is
called on Probing Initiator side.
- Add a new radio platform API otPlatRadioConfigureEnhAckProbing. This
API should be called on Probing Subject side when handling the
requests from Initiators. This API notifies the radio to start/stop
aggregating link metrics info and include the data into Vendor IE in
enhanced-ACK for the specific neighbor. As discussed in #5746, the
code for doing such thing should be put in radio driver.
- Add a util module util/link_metrics, which provides a group of APIs
to implement Probing Subject side logic for Enh-ACK Probing. Any
platform could use this module to implement the feature easily in
radio driver.
- Add new util APIs in util/mac_frame to generate Enh-ACK Probing IE
(Vendor IE with Thread OUI and SubType = 0) and set value for this
IE.
- Update the implementation in simulation/radio.c to support Probing
Subject side logic for Enh-ACK Probing, using APIs in
util/link_metrics and util/mac_frame.
- Add a test
v1_2_LowPower_7_1_01_SingleProbeLinkMetricsWithEnhancedAcks.py for
testing.
Misc:
- Add check for all the public Link Metrics APIs (Initiator side) to
ensure that the Subject is a neighbor of the Initiator. If the
address is not link-local or the neighbor is not found, an error
UNKNOWN_NEIGHBOR would be returned.
- Update PrepareEmptyFrame so that when it's called for reference
device, its frame version would be set to 2015.
MAC command frame has its command ID encrypted in frame version
802.15.4-2015. Radio driver cannot decrypt this frame payload without
extended address. So the frame pending bit is not correctly set in the
ACK in response to data request command with version 2015. This commit
adds a special handling for frame version 2015 and only checks the
frame type when deciding if it needs to set the frame pending bit.
In 802.15.4-2015 spec Table 7-2, it is possible to receive frame with
destination address but without destination PAN ID. This commit
changes the address filter function to avoid dropping such frames.
This commit adds transmit security support for simulation radio so
that security Enh-ACK could be handled at radio layer. This commit
also fixes issue #5041.
This commit adds mac frame util functions to generate acks (both Imm
and Enh acks) from a received frame. These funtions are utils APIs for
platforms which don't provide ack generation.
This commit also introduces compile options for CSL to control the CSL
IE related part.
This commit adds enhanced frame pending feature of Thread 1.2. This
requires the platform radio driver to correctly set frame pending bit
for Data frames and MAC Data Request frames.
`otPlatRadioFrameUpdated()` is declared not to access any state within
OpenThread. However, the current implementation does read the extended
address. This commit moves the AES process into `Mac::TxFrame`, which
is free of `otInstance` and eliminates the current deep callback
stacks when the radio driver wants to process tx AES from interrupt
context.
Yakun Xu