[thread-direct] add guest Wake Key support

Extends the wake key model to support pre-provisioned guest keys
(indices 130-192) for WI devices that do not hold the Thread Network Key.

`KeyManager` gains a fixed `GuestWakeKeyEntry` table for storing and
looking up guest keys.

`otThreadDirectSetGuestWakeKey` / `otThreadDirectRemoveGuestWakeKey`
expose the table to applications.  `otThreadDirectWakeup` rejects a
burst with an unprovisioned guest key index before the first frame is
sent.

Author: suveshpratapa

include/openthread/instance.h

@@ -52,7 +52,7 @@ extern "C" {
  *
  * @note This number versions both OpenThread platform and user APIs.
  */
-#define OPENTHREAD_API_VERSION (609)
+#define OPENTHREAD_API_VERSION (610)
 
 /**
  * @addtogroup api-instance

include/openthread/thread_direct.h

@@ -228,6 +228,37 @@ bool otThreadDirectIsWakeListenerEnabled(otInstance *aInstance);
  */
 bool otThreadDirectIsWakeBurstActive(otInstance *aInstance);
 
+/**
+ * Adds or replaces a guest Wake Key at the given key index.
+ *
+ * Guest Wake Keys are raw 16-byte keys provisioned out-of-band and used by WI devices
+ * that do not hold the Thread Network Key.  Valid key indices: [130, 192].
+ * Key Index 129 is reserved for the default (network-derived) Wake Key.
+ *
+ * @param[in] aInstance   The OpenThread instance.
+ * @param[in] aKeyIndex   Key Index in [130, 192].
+ * @param[in] aKey        16-byte key material.
+ *
+ * @retval OT_ERROR_NONE              Key stored.
+ * @retval OT_ERROR_INVALID_ARGS      @p aKeyIndex is outside [130, 192].
+ * @retval OT_ERROR_NO_BUFS           Guest key table is full.
+ * @retval OT_ERROR_DISABLED_FEATURE  OPENTHREAD_CONFIG_THREAD_DIRECT_GUEST_WAKE_KEY_ENABLE = 0.
+ */
+otError otThreadDirectSetGuestWakeKey(otInstance *aInstance, uint8_t aKeyIndex, const otThreadDirectWakeKey *aKey);
+
+/**
+ * Removes a previously configured guest Wake Key.
+ *
+ * No-op if no key is registered at @p aKeyIndex.
+ *
+ * @param[in] aInstance  The OpenThread instance.
+ * @param[in] aKeyIndex  Key Index of the guest key to remove.
+ *
+ * @retval OT_ERROR_NONE          Key removed (or was not present).
+ * @retval OT_ERROR_INVALID_ARGS  @p aKeyIndex is outside [130, 192].
+ */
+otError otThreadDirectRemoveGuestWakeKey(otInstance *aInstance, uint8_t aKeyIndex);
+
 /**
  * @}
  *

src/core/api/thread_direct_api.cpp

@@ -87,6 +87,13 @@ otError otThreadDirectWakeup(otInstance            *aInstance,
             IgnoreError(AsCoreType(aInstance).Get<MeshCoP::ActiveDatasetManager>().ApplyConfiguration());
         }
 
+        if (effectiveKeyIndex >= OT_MAC_FRAME_GUEST_WAKE_KEY_INDEX_MIN &&
+            effectiveKeyIndex <= OT_MAC_FRAME_GUEST_WAKE_KEY_INDEX_MAX)
+        {
+            VerifyOrExit(AsCoreType(aInstance).Get<ot::Mac::SubMac>().IsGuestWakeKeyRegistered(effectiveKeyIndex),
+                         error = OT_ERROR_INVALID_STATE);
+        }
+
         error = AsCoreType(aInstance).Get<WakeupTxScheduler>().StartWakeup(
             AsCoreType(aExtAddress), static_cast<Mac::Frame::WakeFrameType>(aWakeType), intervalUs, durationMs,
             effectiveKeyIndex);
@@ -125,4 +132,39 @@ bool otThreadDirectIsWakeListenerEnabled(otInstance *aInstance)
 
 #endif // OPENTHREAD_CONFIG_THREAD_DIRECT_WAKE_LISTENER_ENABLE
 
+otError otThreadDirectSetGuestWakeKey(otInstance *aInstance, uint8_t aKeyIndex, const otThreadDirectWakeKey *aKey)
+{
+    otError              error = OT_ERROR_NONE;
+    ot::Mac::KeyMaterial material;
+
+    VerifyOrExit(aKey != nullptr, error = OT_ERROR_INVALID_ARGS);
+    VerifyOrExit(aKeyIndex >= OT_MAC_FRAME_GUEST_WAKE_KEY_INDEX_MIN &&
+                     aKeyIndex <= OT_MAC_FRAME_GUEST_WAKE_KEY_INDEX_MAX,
+                 error = OT_ERROR_INVALID_ARGS);
+
+    // Import the raw 16-byte key into a PSA-aware KeyMaterial. kExportable ensures
+    // the platform security layer can export the key bytes for hardware AES-CCM use.
+    material.SetFrom(*reinterpret_cast<const ot::Mac::Key *>(aKey),
+                     OPENTHREAD_CONFIG_PLATFORM_MAC_KEYS_EXPORTABLE_ENABLE);
+
+    error = AsCoreType(aInstance).Get<ot::Mac::SubMac>().SetWakeKey(aKeyIndex, &material);
+
+exit:
+    return error;
+}
+
+otError otThreadDirectRemoveGuestWakeKey(otInstance *aInstance, uint8_t aKeyIndex)
+{
+    otError error = OT_ERROR_NONE;
+
+    VerifyOrExit(aKeyIndex >= OT_MAC_FRAME_GUEST_WAKE_KEY_INDEX_MIN &&
+                     aKeyIndex <= OT_MAC_FRAME_GUEST_WAKE_KEY_INDEX_MAX,
+                 error = OT_ERROR_INVALID_ARGS);
+
+    IgnoreError(AsCoreType(aInstance).Get<ot::Mac::SubMac>().SetWakeKey(aKeyIndex, nullptr));
+
+exit:
+    return error;
+}
+
 #endif // OPENTHREAD_CONFIG_THREAD_DIRECT_WAKE_INITIATOR_ENABLE || OPENTHREAD_CONFIG_THREAD_DIRECT_WAKE_LISTENER_ENABLE

src/core/mac/mac.cpp

@@ -1555,7 +1555,8 @@ Error Mac::ProcessReceiveSecurity(RxFrame &aFrame, const Address &aSrcAddr, Neig
                 }
                 else
                 {
-                    ExitNow();
+                    macKey = keyManager.FindGuestWakeKey(maybeWakeKeyId);
+                    VerifyOrExit(macKey != nullptr); // drop frame if key not provisioned
                 }
 
                 extAddress = &aSrcAddr.GetExtended();

src/core/mac/sub_mac.cpp

@@ -437,7 +437,17 @@ void SubMac::ProcessTransmitSecurity(void)
     {
         extAddress = &GetExtAddress();
 
-        mTransmitFrame.SetAesKey(Get<KeyManager>().GetDefaultWakeKey());
+        if (mActiveBurstWakeKeyIndex == Frame::kWakeKeyIndex)
+        {
+            mTransmitFrame.SetAesKey(Get<KeyManager>().GetDefaultWakeKey());
+        }
+        else
+        {
+            const KeyMaterial *guestKey = Get<KeyManager>().FindGuestWakeKey(mActiveBurstWakeKeyIndex);
+
+            VerifyOrExit(guestKey != nullptr); // no key registered for this index; drop frame
+            mTransmitFrame.SetAesKey(*guestKey);
+        }
 
         mTransmitFrame.ProcessTransmitAesCcm(*extAddress);
         ExitNow();
@@ -1024,6 +1034,12 @@ Error SubMac::SetWakeKey(uint8_t aKeyIndex, const KeyMaterial *aWakeKey)
 {
     Error error = kErrorNone;
 
+    // Guest keys (130-192) are stored in KeyManager for RX decryption on all platforms.
+    if (aKeyIndex >= OT_MAC_FRAME_GUEST_WAKE_KEY_INDEX_MIN && aKeyIndex <= OT_MAC_FRAME_GUEST_WAKE_KEY_INDEX_MAX)
+    {
+        SuccessOrExit(error = Get<KeyManager>().SetGuestWakeKey(aKeyIndex, aWakeKey));
+    }
+
     if (!ShouldHandleTransmitSecurity())
     {
         Get<Radio>().SetWakeKey(aKeyIndex, aWakeKey);
@@ -1036,9 +1052,17 @@ Error SubMac::SetWakeKey(uint8_t aKeyIndex, const KeyMaterial *aWakeKey)
     }
 #endif
 
+exit:
     return error;
 }
 
+#if OPENTHREAD_CONFIG_THREAD_DIRECT_WAKE_INITIATOR_ENABLE
+bool SubMac::IsGuestWakeKeyRegistered(uint8_t aKeyIndex) const
+{
+    return Get<KeyManager>().FindGuestWakeKey(aKeyIndex) != nullptr;
+}
+#endif
+
 #endif
 
 void SubMac::SignalFrameCounterUsed(uint32_t aFrameCounter, uint8_t aKeyId)

src/core/mac/sub_mac.hpp

@@ -442,6 +442,13 @@ class SubMac : public InstanceLocator, private NonCopyable
     void    SetActiveBurstWakeKeyIndex(uint8_t aKeyIndex) { mActiveBurstWakeKeyIndex = aKeyIndex; }
     uint8_t GetActiveBurstWakeKeyIndex(void) const { return mActiveBurstWakeKeyIndex; }
 
+    /**
+     * Returns true if a guest Wake Key has been provisioned at @p aKeyIndex via SetWakeKey().
+     *
+     * Used by the wake API to return OT_ERROR_INVALID_STATE before starting a burst with an
+     * unprovisioned guest key index, rather than silently dropping every frame in the burst.
+     */
+    bool IsGuestWakeKeyRegistered(uint8_t aKeyIndex) const;
 #endif
 
     /**

src/core/mac/wakeup_tx_scheduler.cpp

@@ -71,6 +71,11 @@ Error WakeupTxScheduler::StartWakeup(const Mac::ExtAddress    &aWlExtAddress,
                                                             aKeyIndex <= OT_MAC_FRAME_GUEST_WAKE_KEY_INDEX_MAX),
                  error = kErrorInvalidArgs);
 
+    if (aKeyIndex >= OT_MAC_FRAME_GUEST_WAKE_KEY_INDEX_MIN && aKeyIndex <= OT_MAC_FRAME_GUEST_WAKE_KEY_INDEX_MAX)
+    {
+        VerifyOrExit(Get<Mac::SubMac>().IsGuestWakeKeyRegistered(aKeyIndex), error = kErrorInvalidState);
+    }
+
     mKeyIndex = aKeyIndex;
 
     // Inform SubMac of the key index so ProcessTransmitSecurity stamps the correct key ID.

src/core/thread/key_manager.cpp

@@ -176,6 +176,7 @@ KeyManager::KeyManager(Instance &aInstance)
     , mKeySequence(0)
 #if OPENTHREAD_CONFIG_THREAD_DIRECT_WAKE_INITIATOR_ENABLE || OPENTHREAD_CONFIG_THREAD_DIRECT_WAKE_LISTENER_ENABLE
     , mWakeKeyValid(false)
+    , mGuestWakeKeys()
 #endif
     , mMleFrameCounter(0)
     , mStoredMacFrameCounter(0)
@@ -351,6 +352,60 @@ const Mac::KeyMaterial &KeyManager::GetDefaultWakeKey(void)
     return mWakeKeyMaterial;
 }
 
+Error KeyManager::SetGuestWakeKey(uint8_t aKeyIndex, const Mac::KeyMaterial *aKey)
+{
+    Error error = kErrorNone;
+
+    for (GuestWakeKeyEntry &entry : mGuestWakeKeys)
+    {
+        if (entry.mKeyIndex == aKeyIndex)
+        {
+            if (aKey != nullptr)
+            {
+                entry.mKey = *aKey;
+            }
+            else
+            {
+                entry.mKeyIndex = 0;
+                entry.mKey.Clear();
+            }
+
+            ExitNow();
+        }
+    }
+
+    if (aKey != nullptr)
+    {
+        for (GuestWakeKeyEntry &entry : mGuestWakeKeys)
+        {
+            if (entry.mKeyIndex == 0)
+            {
+                entry.mKeyIndex = aKeyIndex;
+                entry.mKey      = *aKey;
+                ExitNow();
+            }
+        }
+
+        error = kErrorNoBufs;
+    }
+
+exit:
+    return error;
+}
+
+const Mac::KeyMaterial *KeyManager::FindGuestWakeKey(uint8_t aKeyIndex) const
+{
+    for (const GuestWakeKeyEntry &entry : mGuestWakeKeys)
+    {
+        if (entry.mKeyIndex == aKeyIndex)
+        {
+            return &entry.mKey;
+        }
+    }
+
+    return nullptr;
+}
+
 #endif // OPENTHREAD_CONFIG_THREAD_DIRECT_WAKE_INITIATOR_ENABLE || OPENTHREAD_CONFIG_THREAD_DIRECT_WAKE_LISTENER_ENABLE
 
 #if OPENTHREAD_CONFIG_RADIO_LINK_TREL_ENABLE

src/core/thread/key_manager.hpp

@@ -451,6 +451,26 @@ class KeyManager : public InstanceLocator, private NonCopyable
      */
     const Mac::KeyMaterial &GetDefaultWakeKey(void);
 
+    /**
+     * Stores or removes a pre-provisioned guest Wake Key.
+     *
+     * Guest keys use key indices in [OT_MAC_FRAME_GUEST_WAKE_KEY_INDEX_MIN,
+     * OT_MAC_FRAME_GUEST_WAKE_KEY_INDEX_MAX] (130-192). Passing @p aKey as nullptr
+     * removes any previously stored key at @p aKeyIndex.
+     *
+     * @param[in] aKeyIndex  Guest key index (130-192).
+     * @param[in] aKey       Key material to store, or nullptr to remove.
+     */
+    Error SetGuestWakeKey(uint8_t aKeyIndex, const Mac::KeyMaterial *aKey);
+
+    /**
+     * Looks up a pre-provisioned guest Wake Key by index.
+     *
+     * @param[in] aKeyIndex  Guest key index (130-192).
+     *
+     * @returns A pointer to the stored key material, or nullptr if not found.
+     */
+    const Mac::KeyMaterial *FindGuestWakeKey(uint8_t aKeyIndex) const;
 #endif
 
     /**
@@ -638,8 +658,19 @@ class KeyManager : public InstanceLocator, private NonCopyable
     Mle::KeyMaterial mTemporaryMleKey;
 
 #if OPENTHREAD_CONFIG_THREAD_DIRECT_WAKE_INITIATOR_ENABLE || OPENTHREAD_CONFIG_THREAD_DIRECT_WAKE_LISTENER_ENABLE
-    Mac::KeyMaterial mWakeKeyMaterial;
-    bool             mWakeKeyValid : 1;
+    // Guest wake keys keyed by Aux Security Header index (130-192).
+    // mKeyIndex == 0 marks an empty slot.
+    struct GuestWakeKeyEntry
+    {
+        uint8_t          mKeyIndex;
+        Mac::KeyMaterial mKey;
+    };
+
+    static constexpr uint8_t kMaxGuestWakeKeys = OPENTHREAD_CONFIG_THREAD_DIRECT_MAX_DIRECT_PEERS;
+
+    Mac::KeyMaterial  mWakeKeyMaterial;
+    bool              mWakeKeyValid : 1;
+    GuestWakeKeyEntry mGuestWakeKeys[kMaxGuestWakeKeys];
 #endif
 
 #if OPENTHREAD_CONFIG_RADIO_LINK_TREL_ENABLE