[thread-direct] add TD wake command wire format and default wake key derivation

Adds MAC-layer definitions for the Thread Direct Wake Command and the
default Wake Key derivation in KeyManager.

`Frame::kMacCmdDirect` (0x54) and `Frame::kThreadMacCmdWake` (0x01)
define the command identifiers per the Thread Direct MAC command structure.
`WakeFrameType` enumerates the three wake types.

`KeyManager::GetDefaultWakeKey()` derives the Wake Key as
HMAC-SHA256(NetworkKey, "Thread-Wake"), caching the result and invalidating
it whenever the Network Key changes. Integration with SubMac and the TX/RX
paths lands in the next PR.

Author: suveshpratapa

src/core/mac/mac_frame.cpp

@@ -297,6 +297,30 @@ Error Frame::ValidatePsdu(void) const
     return error;
 }
 
+#if OPENTHREAD_CONFIG_THREAD_DIRECT_WAKE_INITIATOR_ENABLE || OPENTHREAD_CONFIG_THREAD_DIRECT_WAKE_LISTENER_ENABLE
+bool Frame::IsTdWakeCommand(void) const
+{
+    bool    isTdWake = false;
+    uint8_t commandId;
+    uint8_t index;
+
+    VerifyOrExit(IsMacCommand() && IsVersion2015());
+    SuccessOrExit(GetCommandId(commandId));
+    VerifyOrExit(commandId == kMacCmdDirect);
+
+    // The Thread Cmd ID immediately follows the Command ID byte in the payload.
+    index = FindPayloadIndex();
+    VerifyOrExit(index != kInvalidIndex);
+    VerifyOrExit(index + 1 < mLength - GetFooterLength());
+    VerifyOrExit(mPsdu[index + 1] == kThreadMacCmdWake);
+
+    isTdWake = true;
+
+exit:
+    return isTdWake;
+}
+#endif // OPENTHREAD_CONFIG_THREAD_DIRECT_WAKE_INITIATOR_ENABLE || OPENTHREAD_CONFIG_THREAD_DIRECT_WAKE_LISTENER_ENABLE
+
 #if OPENTHREAD_CONFIG_THREAD_DIRECT_WAKE_INITIATOR_ENABLE || OPENTHREAD_CONFIG_THREAD_DIRECT_WAKE_LISTENER_ENABLE
 bool Frame::IsWakeupFrame(void) const
 {
@@ -1448,6 +1472,61 @@ void TxFrame::DecryptTransmitAesCcm(const ExtAddress &aExtAddress)
 }
 #endif // OPENTHREAD_CONFIG_MAC_HEADER_IE_SUPPORT && OPENTHREAD_CONFIG_MAC_SOFTWARE_RETX_SECURITY_ENABLE
 
+#if OPENTHREAD_CONFIG_THREAD_DIRECT_WAKE_INITIATOR_ENABLE
+Error TxFrame::GenerateThreadDirectWakeCommand(PanId             aPanId,
+                                               const ExtAddress &aDstExtAddress,
+                                               const ExtAddress &aSrcExtAddress,
+                                               WakeFrameType     aWakeType,
+                                               uint8_t           aRendezvousTimeTenSym,
+                                               uint8_t           aRetryInterval,
+                                               uint8_t           aRetryCount)
+{
+    uint16_t     fcf;
+    uint8_t      secCtl;
+    FrameBuilder builder;
+    Address      dst;
+    Address      src;
+
+    dst.SetExtended(aDstExtAddress);
+    src.SetExtended(aSrcExtAddress);
+
+    // 2015 MAC Command frame, extended dst+src, Dest PAN ID present,
+    // security enabled. No ACK requested - wake frames are sent as a burst without per-frame ACK.
+    fcf = kTypeMacCmd | kVersion2015 | kFcfSecurityEnabled;
+    fcf |= DetermineFcfAddrType(dst, kFcfDstAddrShift);
+    fcf |= DetermineFcfAddrType(src, kFcfSrcAddrShift);
+
+    ClearAllBytes(mInfo.mTxInfo);
+    builder.Init(mPsdu, GetMtu());
+
+    IgnoreError(builder.AppendUint<kLittleEndian>(fcf));
+    IgnoreError(builder.AppendUint8(0));                    // Sequence number (filled by SubMac)
+    IgnoreError(builder.AppendUint<kLittleEndian>(aPanId)); // Destination PAN ID
+    IgnoreError(builder.AppendMacAddress(dst));             // Destination extended address
+    IgnoreError(builder.AppendMacAddress(src));             // Source extended address
+
+    // Auxiliary Security Header: Enc-Mic-32, Key ID Mode 1 (1-byte key index for Wake Key)
+    secCtl = kKeyIdMode1 | kSecurityEncMic32;
+    IgnoreError(builder.AppendUint8(secCtl));
+    builder.AppendLength(CalculateSecurityHeaderSize(secCtl) -
+                         sizeof(secCtl)); // Frame counter + key ID (filled by SubMac)
+
+    // Encrypted payload: Thread Direct MAC Command bytes
+    IgnoreError(builder.AppendUint8(kMacCmdDirect));                   // 0x54
+    IgnoreError(builder.AppendUint8(kThreadMacCmdWake));               // 0x01
+    IgnoreError(builder.AppendUint8(static_cast<uint8_t>(aWakeType))); // Wake Frame Type
+    IgnoreError(builder.AppendUint8(aRendezvousTimeTenSym));           // Rendezvous time
+    IgnoreError(builder.AppendUint8(static_cast<uint8_t>(((aRetryInterval & 0x0f) << 4) | (aRetryCount & 0x0f))));
+
+    // Reserve space for MIC and FCS (filled during AES-CCM processing)
+    builder.AppendLength(CalculateMicSize(secCtl) + GetFcsSize());
+
+    mLength = builder.GetLength();
+
+    return kErrorNone;
+}
+#endif // OPENTHREAD_CONFIG_THREAD_DIRECT_WAKE_INITIATOR_ENABLE
+
 void TxFrame::GenerateImmAck(const RxFrame &aFrame, bool aIsFramePending)
 {
     uint16_t fcf = static_cast<uint16_t>(kTypeAck) | aFrame.GetVersion();

src/core/mac/mac_frame.hpp

@@ -129,8 +129,32 @@ class Frame : public otRadioFrame
         kMacCmdBeaconRequest              = 7,
         kMacCmdCoordinatorRealignment     = 8,
         kMacCmdGtsRequest                 = 9,
+        kMacCmdDirect                     = 0x54, ///< Thread Direct MAC Command (IEEE 802.15.4 vendor-specific command)
     };
 
+    /**
+     * Thread MAC Command IDs - byte 1 of the kMacCmdDirect (0x54) payload.
+     */
+    enum ThreadMacCmdId : uint8_t
+    {
+        kThreadMacCmdAdvertisement = 0x00,
+        kThreadMacCmdWake          = 0x01,
+        kThreadMacCmdDirectLink    = 0x02,
+    };
+
+    /**
+     * Wake Frame Type - byte 2 of the Thread Wake Command payload.
+     */
+    enum WakeFrameType : uint8_t
+    {
+        kWakeFrameTypeDirectLink     = 0x00,
+        kWakeFrameTypePowerOutage    = 0x01,
+        kWakeFrameTypeConnectionless = 0x02,
+    };
+
+    static constexpr uint8_t kWakeKeyIndex =
+        129; ///< Key index for the TD Wake Key. Must equal OT_MAC_FRAME_WAKE_KEY_INDEX.
+
     static constexpr uint16_t kInfoStringSize = 128; ///< Max chars for `InfoString` (ToInfoString()).
 
     static constexpr uint8_t kPreambleSize  = 4;
@@ -187,6 +211,14 @@ class Frame : public otRadioFrame
     bool IsMacCommand(void) const { return GetType() == kTypeMacCmd; }
 
 #if OPENTHREAD_CONFIG_THREAD_DIRECT_WAKE_INITIATOR_ENABLE || OPENTHREAD_CONFIG_THREAD_DIRECT_WAKE_LISTENER_ENABLE
+    /**
+     * Returns whether the frame is a Thread Direct Wake Command (MAC Command 0x54 / Thread Cmd 0x01).
+     *
+     * @retval TRUE   If this is a Thread Direct Wake Command.
+     * @retval FALSE  Otherwise.
+     */
+    bool IsTdWakeCommand(void) const;
+
     /**
      * This method returns whether the frame is an IEEE 802.15.4 Wake-up frame.
      *
@@ -1342,6 +1374,30 @@ class TxFrame : public Frame
     void SetTimeSyncSeq(uint8_t aTimeSyncSeq) { mInfo.mTxInfo.mIeInfo->mTimeSyncSeq = aTimeSyncSeq; }
 #endif // OPENTHREAD_CONFIG_TIME_SYNC_ENABLE
 
+#if OPENTHREAD_CONFIG_THREAD_DIRECT_WAKE_INITIATOR_ENABLE
+    /**
+     * Generates a Thread Direct Wake Command frame (MAC Command 0x54 / Thread Cmd 0x01).
+     *
+     * @param[in] aPanId                 The Thread network PAN ID.
+     * @param[in] aDstExtAddress         Extended address of the target Wake Listener.
+     * @param[in] aSrcExtAddress         Extended address of this Wake Initiator.
+     * @param[in] aWakeType              Wake Frame Type byte.
+     * @param[in] aRendezvousTimeTenSym  Remaining wake sequence duration in 10-symbol units (0-255).
+     * @param[in] aRetryInterval         Connection retry interval (4-bit value).
+     * @param[in] aRetryCount            Connection retry count (4-bit value).
+     *
+     * @retval kErrorNone         Frame generated successfully.
+     * @retval kErrorInvalidArgs  Source address is not set.
+     */
+    Error GenerateThreadDirectWakeCommand(PanId             aPanId,
+                                          const ExtAddress &aDstExtAddress,
+                                          const ExtAddress &aSrcExtAddress,
+                                          WakeFrameType     aWakeType,
+                                          uint8_t           aRendezvousTimeTenSym,
+                                          uint8_t           aRetryInterval,
+                                          uint8_t           aRetryCount);
+#endif
+
     /**
      * Generate Imm-Ack in this frame object.
      *

src/core/thread/key_manager.cpp

@@ -45,6 +45,12 @@ const uint8_t KeyManager::kThreadString[] = {
     'T', 'h', 'r', 'e', 'a', 'd',
 };
 
+#if OPENTHREAD_CONFIG_THREAD_DIRECT_WAKE_INITIATOR_ENABLE || OPENTHREAD_CONFIG_THREAD_DIRECT_WAKE_LISTENER_ENABLE
+const uint8_t KeyManager::kWakeKeyString[] = {
+    'T', 'h', 'r', 'e', 'a', 'd', '-', 'W', 'a', 'k', 'e',
+};
+#endif
+
 #if OPENTHREAD_CONFIG_RADIO_LINK_TREL_ENABLE
 const uint8_t KeyManager::kHkdfExtractSaltString[] = {'T', 'h', 'r', 'e', 'a', 'd', 'S', 'e', 'q', 'u', 'e', 'n',
                                                       'c', 'e', 'M', 'a', 's', 't', 'e', 'r', 'K', 'e', 'y'};
@@ -179,6 +185,10 @@ KeyManager::KeyManager(Instance &aInstance)
 {
     otPlatCryptoInit();
 
+#if OPENTHREAD_CONFIG_THREAD_DIRECT_WAKE_INITIATOR_ENABLE || OPENTHREAD_CONFIG_THREAD_DIRECT_WAKE_LISTENER_ENABLE
+    mWakeKeyValid = false;
+#endif
+
 #if OPENTHREAD_CONFIG_PLATFORM_KEY_REFERENCES_ENABLE
     mNetworkKeyRef = Crypto::Storage::kInvalidKeyRef;
     mPskcRef       = Crypto::Storage::kInvalidKeyRef;
@@ -281,6 +291,9 @@ void KeyManager::SetNetworkKey(const NetworkKey &aNetworkKey)
     Get<Notifier>().Signal(kEventThreadKeySeqCounterChanged);
 
     mKeySequence = 0;
+#if OPENTHREAD_CONFIG_THREAD_DIRECT_WAKE_INITIATOR_ENABLE || OPENTHREAD_CONFIG_THREAD_DIRECT_WAKE_LISTENER_ENABLE
+    mWakeKeyValid = false;
+#endif
     UpdateKeyMaterial();
     ResetFrameCounters();
 
@@ -330,6 +343,37 @@ void KeyManager::ComputeTrelKey(uint32_t aKeySequence, Mac::Key &aKey) const
 }
 #endif
 
+#if OPENTHREAD_CONFIG_THREAD_DIRECT_WAKE_INITIATOR_ENABLE || OPENTHREAD_CONFIG_THREAD_DIRECT_WAKE_LISTENER_ENABLE
+const Mac::KeyMaterial &KeyManager::GetDefaultWakeKey(void)
+{
+    if (!mWakeKeyValid)
+    {
+        Crypto::HmacSha256       hmac;
+        Crypto::HmacSha256::Hash hash;
+        Crypto::Key              cryptoKey;
+        Mac::Key                 wakeKey;
+
+#if OPENTHREAD_CONFIG_PLATFORM_KEY_REFERENCES_ENABLE
+        cryptoKey.SetAsKeyRef(mNetworkKeyRef);
+#else
+        cryptoKey.Set(mNetworkKey.m8, NetworkKey::kSize);
+#endif
+
+        hmac.Start(cryptoKey);
+        hmac.Update(kWakeKeyString);
+        hmac.Finish(hash);
+
+        static_assert(Mac::Key::kSize <= Crypto::HmacSha256::Hash::kSize, "Wake Key size exceeds HMAC output size");
+        memcpy(wakeKey.m8, hash.m8, Mac::Key::kSize);
+
+        mWakeKeyMaterial.SetFrom(wakeKey, kExportableMacKeys);
+        mWakeKeyValid = true;
+    }
+
+    return mWakeKeyMaterial;
+}
+#endif // OPENTHREAD_CONFIG_THREAD_DIRECT_WAKE_INITIATOR_ENABLE || OPENTHREAD_CONFIG_THREAD_DIRECT_WAKE_LISTENER_ENABLE
+
 void KeyManager::UpdateKeyMaterial(void)
 {
     HashKeys hashKeys;
@@ -692,6 +736,9 @@ void KeyManager::SetNetworkKeyRef(otNetworkKeyRef aKeyRef)
     Get<Notifier>().Signal(kEventNetworkKeyChanged);
     Get<Notifier>().Signal(kEventThreadKeySeqCounterChanged);
     mKeySequence = 0;
+#if OPENTHREAD_CONFIG_THREAD_DIRECT_WAKE_INITIATOR_ENABLE || OPENTHREAD_CONFIG_THREAD_DIRECT_WAKE_LISTENER_ENABLE
+    mWakeKeyValid = false;
+#endif
     UpdateKeyMaterial();
     ResetFrameCounters();
 

src/core/thread/key_manager.hpp

@@ -449,6 +449,18 @@ class KeyManager : public InstanceLocator, private NonCopyable
      */
     void IncrementMleFrameCounter(void);
 
+#if OPENTHREAD_CONFIG_THREAD_DIRECT_WAKE_INITIATOR_ENABLE || OPENTHREAD_CONFIG_THREAD_DIRECT_WAKE_LISTENER_ENABLE
+    /**
+     * Returns the default Thread Direct Wake Key as `Mac::KeyMaterial`.
+     *
+     * The Wake Key is derived as HMAC-SHA256(NetworkKey, "Thread-Wake") and cached.
+     * The cache is invalidated whenever the Network Key changes.
+     *
+     * @returns A reference to the cached Wake Key material.
+     */
+    const Mac::KeyMaterial &GetDefaultWakeKey(void);
+#endif
+
     /**
      * Returns the KEK as `KekKeyMaterial`
      *
@@ -614,6 +626,10 @@ class KeyManager : public InstanceLocator, private NonCopyable
 
     static const uint8_t kThreadString[];
 
+#if OPENTHREAD_CONFIG_THREAD_DIRECT_WAKE_INITIATOR_ENABLE || OPENTHREAD_CONFIG_THREAD_DIRECT_WAKE_LISTENER_ENABLE
+    static const uint8_t kWakeKeyString[];
+#endif
+
 #if OPENTHREAD_CONFIG_RADIO_LINK_TREL_ENABLE
     static const uint8_t kHkdfExtractSaltString[];
     static const uint8_t kTrelInfoString[];
@@ -629,6 +645,11 @@ class KeyManager : public InstanceLocator, private NonCopyable
     Mle::KeyMaterial mMleKey;
     Mle::KeyMaterial mTemporaryMleKey;
 
+#if OPENTHREAD_CONFIG_THREAD_DIRECT_WAKE_INITIATOR_ENABLE || OPENTHREAD_CONFIG_THREAD_DIRECT_WAKE_LISTENER_ENABLE
+    Mac::KeyMaterial mWakeKeyMaterial;
+    bool             mWakeKeyValid : 1;
+#endif
+
 #if OPENTHREAD_CONFIG_THREAD_DIRECT_WAKE_LISTENER_ENABLE
     Mle::KeyMaterial mTemporaryMacKey;
 #endif

tests/unit/CMakeLists.txt

@@ -229,6 +229,7 @@ ot_unit_test(hmac_sha256)
 ot_unit_test(ip4_header)
 ot_unit_test(ip6_header)
 ot_unit_test(ip_address)
+ot_unit_test(key_manager)
 ot_unit_test(link_metrics_manager)
 ot_unit_test(link_quality)
 ot_unit_test(linked_list)

tests/unit/test_key_manager.cpp

@@ -0,0 +1,91 @@
+/*
+ *  Copyright (c) 2026, The OpenThread Authors.
+ *  All rights reserved.
+ *
+ *  Redistribution and use in source and binary forms, with or without
+ *  modification, are permitted provided that the following conditions are met:
+ *  1. Redistributions of source code must retain the above copyright
+ *     notice, this list of conditions and the following disclaimer.
+ *  2. Redistributions in binary form must reproduce the above copyright
+ *     notice, this list of conditions and the following disclaimer in the
+ *     documentation and/or other materials provided with the distribution.
+ *  3. Neither the name of the copyright holder nor the
+ *     names of its contributors may be used to endorse or promote products
+ *     derived from this software without specific prior written permission.
+ *
+ *  THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+ *  AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+ *  IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
+ *  ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE
+ *  LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
+ *  CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
+ *  SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
+ *  INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
+ *  CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
+ *  ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
+ *  POSSIBILITY OF SUCH DAMAGE.
+ */
+
+#include "common/code_utils.hpp"
+#include "common/debug.hpp"
+#include "thread/key_manager.hpp"
+
+#include "test_platform.h"
+#include "test_util.hpp"
+
+namespace ot {
+
+#if OPENTHREAD_CONFIG_THREAD_DIRECT_WAKE_INITIATOR_ENABLE || OPENTHREAD_CONFIG_THREAD_DIRECT_WAKE_LISTENER_ENABLE
+
+void TestWakeKeyDerivation(void)
+{
+    // `KeyManager::GetDefaultWakeKey()` matches the first 16 bytes of
+    // HMAC-SHA256 over the literal "Thread-Wake" using the Thread Network Key
+    // as the HMAC key (see `KeyManager::GetDefaultWakeKey()`).
+    //
+    // Test vector (network key is non-zero on purpose):
+    //   Network Key : 00 01 02 03 04 05 06 07 08 09 0a 0b 0c 0d 0e 0f
+    //   Wake Key    : f5 ca 7d 94 57 48 c4 55 e8 ad 69 6a 76 fb 18 d0
+    //
+    // Recompute with:
+    //   python3 -c "import
+    //   hmac,hashlib;k=bytes(range(16));print(hmac.new(k,b'Thread-Wake',hashlib.sha256).digest()[:16].hex())"
+
+    constexpr uint8_t kNetworkKeyBytes[OT_NETWORK_KEY_SIZE] = {
+        0x00, 0x01, 0x02, 0x03, 0x04, 0x05, 0x06, 0x07, 0x08, 0x09, 0x0a, 0x0b, 0x0c, 0x0d, 0x0e, 0x0f,
+    };
+
+    constexpr uint8_t kExpectedWakeKey[Mac::Key::kSize] = {
+        0xf5, 0xca, 0x7d, 0x94, 0x57, 0x48, 0xc4, 0x55, 0xe8, 0xad, 0x69, 0x6a, 0x76, 0xfb, 0x18, 0xd0,
+    };
+
+    Instance  *instance;
+    NetworkKey networkKey;
+    Mac::Key   derivedKey;
+
+    instance = testInitInstance();
+    VerifyOrQuit(instance != nullptr);
+
+    memcpy(networkKey.m8, kNetworkKeyBytes, sizeof(networkKey.m8));
+    instance->Get<KeyManager>().SetNetworkKey(networkKey);
+
+    const Mac::KeyMaterial &wakeMaterial = instance->Get<KeyManager>().GetDefaultWakeKey();
+
+    wakeMaterial.ExtractKey(derivedKey);
+    VerifyOrQuit(memcmp(derivedKey.GetBytes(), kExpectedWakeKey, Mac::Key::kSize) == 0, "Wake key derivation mismatch");
+
+    testFreeInstance(instance);
+}
+
+#endif // OPENTHREAD_CONFIG_THREAD_DIRECT_WAKE_INITIATOR_ENABLE || OPENTHREAD_CONFIG_THREAD_DIRECT_WAKE_LISTENER_ENABLE
+
+} // namespace ot
+
+int main(void)
+{
+#if OPENTHREAD_CONFIG_THREAD_DIRECT_WAKE_INITIATOR_ENABLE || OPENTHREAD_CONFIG_THREAD_DIRECT_WAKE_LISTENER_ENABLE
+    ot::TestWakeKeyDerivation();
+#endif
+    printf("All tests passed\n");
+    return 0;
+}