espressif/openthread
1
0
Fork 0
mirror of https://github.com/espressif/openthread.git synced 2026-09-16 14:10:09 +00:00
Code Issues Packages Projects Releases Wiki Activity

[radio] clarify Key ID Mode 1 usage in otPlatRadioSetMacKey() (#13380)

Browse Source 
The radio platform API `otPlatRadioSetMacKey()` was originally
introduced with an `aKeyIdMode` parameter for potential future
extensions. However, in practice, platform-provided transmit security
only applies to and is used with Key ID Mode 1 (standard Thread
security). Attempting to interpret or support other Key ID modes in
radio platform implementations introduces unnecessary complexity and
ambiguity regarding how `aKeyIdMode` values are represented.

This commit updates and clarifies the documentation for
`otPlatRadioSetMacKey()` and `otLinkRawSetMacKey()` to explicitly
state that the APIs only apply to Key ID Mode 1 and that `aKeyIdMode`
must be ignored.

This commit also refactors internal OpenThread C++ methods in
`LinkRaw`, `SubMac`, and `Radio` to `SetMode1MacKeys()`, removing the
redundant Key ID Mode parameter and eliminating unused temporary key
handling for other modes.
This commit is contained in:
Abtin Keshavarzian
2026-07-24 08:59:19 -07:00
committed by GitHub
parent a76515b3d4
commit 6ff0e4ed95
11 changed files with 44 additions and 66 deletions
Download Patch File Download Diff File Expand all files Collapse all files
include/openthread/instance.h
+1 -1
View File
@@ -52,7 +52,7 @@ extern "C" {
*
* @note This number versions both OpenThread platform and user APIs.
*/
#define OPENTHREAD_API_VERSION (614)
#define OPENTHREAD_API_VERSION (615)
/**
* @addtogroup api-instance
include/openthread/link_raw.h
+4 -1
View File
@@ -337,8 +337,11 @@ otError otLinkRawSrcMatchClearExtEntries(otInstance *aInstance);
/**
* Update MAC keys and key index.
*
* The input @p aKeyIdMode parameter is ignored and is always treated as Key ID Mode 1. This API mirrors the
* `otPlatRadioSetMacKey()` platform API. See `otPlatRadioSetMacKey()` for more information on Key ID Mode.
*
* @param[in] aInstance A pointer to an OpenThread instance.
* @param[in] aKeyIdMode The key ID mode.
* @param[in] aKeyIdMode The key ID mode (ignored).
* @param[in] aKeyIndex The key index.
* @param[in] aPrevKey The previous MAC key.
* @param[in] aCurrKey The current MAC key.
include/openthread/platform/radio.h
+15 -4
View File
@@ -719,17 +719,28 @@ void otPlatRadioSetPromiscuous(otInstance *aInstance, bool aEnable);
void otPlatRadioSetRxOnWhenIdle(otInstance *aInstance, bool aEnable);
/**
* Update MAC keys and key index
* Update MAC keys and key index.
*
* Is used when radio provides OT_RADIO_CAPS_TRANSMIT_SEC capability.
* Is used when radio provides `OT_RADIO_CAPS_TRANSMIT_SEC` capability.
*
* Radio platform implementations MUST ignore the @p aKeyIdMode parameter entirely and treat the keys configured via
* this API as Key ID Mode 1 (standard Thread security).
*
* This API was originally introduced with the @p aKeyIdMode parameter for potential future extensions, and it is
* retained in the function signature for backward compatibility. However, in practice, platform transmit security
* is only intended and used for Key ID Mode 1. Attempting to support or interpret other Key ID modes in the radio
* platform introduces complexity and ambiguity regarding how @p aKeyIdMode values are represented (e.g.,
* bit-shifted as it appears in the IEEE 802.15.4 Security Control field vs. simple sequential mode values 0, 1, 2).
*
* A call to this API replaces any previously set MAC keys.
*
* The radio platform should reset the current security MAC frame counter tracked by the radio on this call. While this
* is highly recommended, the OpenThread stack, as a safeguard, will also reset the frame counter using the
* `otPlatRadioSetMacFrameCounter()` before calling this API.
*
* @param[in] aInstance A pointer to an OpenThread instance.
* @param[in] aKeyIdMode The key ID mode.
* @param[in] aKeyIndex Current MAC key index.
* @param[in] aKeyIdMode The key ID mode (must be ignored by the radio platform).
* @param[in] aKeyIndex Current MAC key index.
* @param[in] aPrevKey A pointer to the previous MAC key.
* @param[in] aCurrKey A pointer to the current MAC key.
* @param[in] aNextKey A pointer to the next MAC key.
src/core/api/link_raw_api.cpp
+4 -2
View File
@@ -209,8 +209,10 @@ otError otLinkRawSetMacKey(otInstance *aInstance,
const otMacKey *aCurrKey,
const otMacKey *aNextKey)
{
return AsCoreType(aInstance).Get<Mac::LinkRaw>().SetMacKey(aKeyIdMode, aKeyIndex, AsCoreType(aPrevKey),
AsCoreType(aCurrKey), AsCoreType(aNextKey));
OT_UNUSED_VARIABLE(aKeyIdMode);
return AsCoreType(aInstance).Get<Mac::LinkRaw>().SetMode1MacKeys(aKeyIndex, AsCoreType(aPrevKey),
AsCoreType(aCurrKey), AsCoreType(aNextKey));
}
otError otLinkRawSetMacFrameCounter(otInstance *aInstance, uint32_t aMacFrameCounter)
src/core/mac/link_raw.cpp
+2 -6
View File
@@ -240,17 +240,13 @@ void LinkRaw::InvokeEnergyScanDone(int8_t aEnergyScanMaxRssi)
}
}
Error LinkRaw::SetMacKey(uint8_t aKeyIdMode,
uint8_t aKeyIndex,
const Key &aPrevKey,
const Key &aCurKey,
const Key &aNextKey)
Error LinkRaw::SetMode1MacKeys(uint8_t aKeyIndex, const Key &aPrevKey, const Key &aCurKey, const Key &aNextKey)
{
Error error = kErrorNone;
VerifyOrExit(IsEnabled(), error = kErrorInvalidState);
mSubMac.SetMacKey(aKeyIdMode, aKeyIndex, aPrevKey, aCurKey, aNextKey);
mSubMac.SetMode1MacKeys(aKeyIndex, aPrevKey, aCurKey, aNextKey);
exit:
return error;
src/core/mac/link_raw.hpp
+2 -7
View File
@@ -214,9 +214,8 @@ public:
Error SetExtAddress(const ExtAddress &aExtAddress);
/**
* Updates MAC keys and key index.
* Updates MAC keys and key index for Key ID Mode 1.
*
* @param[in] aKeyIdMode The key ID mode.
* @param[in] aKeyIndex The key index.
* @param[in] aPrevKey The previous MAC key.
* @param[in] aCurKey The current MAC key.
@@ -225,11 +224,7 @@ public:
* @retval kErrorNone If successful.
* @retval kErrorInvalidState If the raw link-layer isn't enabled.
*/
Error SetMacKey(uint8_t aKeyIdMode,
uint8_t aKeyIndex,
const Key &aPrevKey,
const Key &aCurKey,
const Key &aNextKey);
Error SetMode1MacKeys(uint8_t aKeyIndex, const Key &aPrevKey, const Key &aCurKey, const Key &aNextKey);
/**
* Sets the current MAC frame counter value.
src/core/mac/sub_mac.cpp
+3 -31
View File
@@ -895,41 +895,13 @@ void SubMac::SetState(State aState)
}
}
void SubMac::SetMacKey(uint8_t aKeyIdMode,
uint8_t aKeyIndex,
const Key &aPrevKey,
const Key &aCurKey,
const Key &aNextKey)
void SubMac::SetMode1MacKeys(uint8_t aKeyIndex, const Key &aPrevKey, const Key &aCurKey, const Key &aNextKey)
{
const KeyTrio *radioKeys = nullptr;
KeyTrio tempKeyTrio;
if (aKeyIdMode == Frame::kKeyIdMode1)
{
mKeyTrio.Set(aKeyIndex, aPrevKey, aCurKey, aNextKey);
}
mKeyTrio.Set(aKeyIndex, aPrevKey, aCurKey, aNextKey);
VerifyOrExit(!ShouldHandleTransmitSecurity());
switch (aKeyIdMode)
{
case Frame::kKeyIdMode0:
case Frame::kKeyIdMode2:
tempKeyTrio.Set(aKeyIndex, aPrevKey, aCurKey, aNextKey);
radioKeys = &tempKeyTrio;
break;
case Frame::kKeyIdMode1:
radioKeys = &mKeyTrio;
break;
default:
OT_ASSERT(false);
break;
}
VerifyOrExit(radioKeys != nullptr);
Get<Radio::Radio>().SetMacKey(aKeyIdMode, *radioKeys);
Get<Radio::Radio>().SetMode1MacKeys(mKeyTrio);
exit:
return;
src/core/mac/sub_mac.hpp
+2 -3
View File
@@ -416,15 +416,14 @@ public:
const KeyMaterial &GetMacKey(KeyTrio::Type aType) const { return mKeyTrio.GetKey(aType); }
/**
* Sets MAC keys and key index.
* Sets MAC keys and key index for Key ID Mode 1.
*
* @param[in] aKeyIdMode MAC key ID mode.
* @param[in] aKeyIndex The key index.
* @param[in] aPrevKey The previous MAC key.
* @param[in] aCurKey The current MAC key.
* @param[in] aNextKey The next MAC key.
*/
void SetMacKey(uint8_t aKeyIdMode, uint8_t aKeyIndex, const Key &aPrevKey, const Key &aCurKey, const Key &aNextKey);
void SetMode1MacKeys(uint8_t aKeyIndex, const Key &aPrevKey, const Key &aCurKey, const Key &aNextKey);
/**
* Clears the stored MAC keys.
src/core/radio/radio.cpp
+1 -1
View File
@@ -107,7 +107,7 @@ void Radio::Init(void)
SetShortAddress(Mac::kShortAddrInvalid);
emptyKeyTrio.Clear();
SetMacKey(Mac::Frame::kKeyIdMode1, emptyKeyTrio);
SetMode1MacKeys(emptyKeyTrio);
SetMacFrameCounter(0);
SetPromiscuous(false);
src/core/radio/radio.hpp
+8 -8
View File
@@ -432,12 +432,11 @@ public:
void SetAlternateShortAddress(Mac::ShortAddress aShortAddress);
/**
* Sets MAC keys and key index.
* Sets MAC keys and key index for Key ID Mode 1.
*
* @param[in] aKeyIdMode MAC key ID mode.
* @param[in] aKeyTrio The `KeyTrio` set (prev, cur, next) along with the key index.
* @param[in] aKeyTrio The `KeyTrio` set (prev, cur, next) along with the key index.
*/
void SetMacKey(uint8_t aKeyIdMode, const Mac::KeyTrio &aKeyTrio);
void SetMode1MacKeys(const Mac::KeyTrio &aKeyTrio);
/**
* Sets the current MAC Frame Counter value.
@@ -920,7 +919,7 @@ inline void Radio::SetAlternateShortAddress(Mac::ShortAddress aShortAddress)
otPlatRadioSetAlternateShortAddress(GetInstancePtr(), aShortAddress);
}
inline void Radio::SetMacKey(uint8_t aKeyIdMode, const Mac::KeyTrio &aKeyTrio)
inline void Radio::SetMode1MacKeys(const Mac::KeyTrio &aKeyTrio)
{
otRadioKeyType keyType;
@@ -930,8 +929,9 @@ inline void Radio::SetMacKey(uint8_t aKeyIdMode, const Mac::KeyTrio &aKeyTrio)
keyType = OT_KEY_TYPE_LITERAL_KEY;
#endif
otPlatRadioSetMacKey(GetInstancePtr(), aKeyIdMode, aKeyTrio.GetKeyIndex(), &aKeyTrio.GetKey(Mac::KeyTrio::kPrev),
&aKeyTrio.GetKey(Mac::KeyTrio::kCur), &aKeyTrio.GetKey(Mac::KeyTrio::kNext), keyType);
otPlatRadioSetMacKey(GetInstancePtr(), Mac::Frame::kKeyIdMode1, aKeyTrio.GetKeyIndex(),
&aKeyTrio.GetKey(Mac::KeyTrio::kPrev), &aKeyTrio.GetKey(Mac::KeyTrio::kCur),
&aKeyTrio.GetKey(Mac::KeyTrio::kNext), keyType);
}
inline Error Radio::GetTransmitPower(int8_t &aPower) { return otPlatRadioGetTransmitPower(GetInstancePtr(), &aPower); }
@@ -1076,7 +1076,7 @@ inline void Radio::SetShortAddress(Mac::ShortAddress) {}
inline void Radio::SetAlternateShortAddress(Mac::ShortAddress) {}
inline void Radio::SetMacKey(uint8_t, const Mac::KeyTrio &) {}
inline void Radio::SetMode1MacKeys(const Mac::KeyTrio &) {}
inline Error Radio::GetTransmitPower(int8_t &) { return kErrorNotImplemented; }
src/core/thread/key_manager.cpp
+2 -2
View File
@@ -346,8 +346,8 @@ void KeyManager::UpdateKeyMaterial(void)
ComputeKeys(mKeySequence - 1, prevHashKeys);
ComputeKeys(mKeySequence + 1, nextHashKeys);
Get<Mac::SubMac>().SetMacKey(Mac::Frame::kKeyIdMode1, Mac::DetermineKeyIndexFor(mKeySequence),
prevHashKeys.GetMacKey(), hashKeys.GetMacKey(), nextHashKeys.GetMacKey());
Get<Mac::SubMac>().SetMode1MacKeys(Mac::DetermineKeyIndexFor(mKeySequence), prevHashKeys.GetMacKey(),
hashKeys.GetMacKey(), nextHashKeys.GetMacKey());
}
#endif