[joiner-router] set KEK after aborting previous entrust transaction (#13657)

When `JoinerRouter::SendDelayedJoinerEntrust()` dispatches a queued
`JOIN_ENT.ntf` message while an earlier `JOIN_ENT.ntf` CoAP transaction
is still awaiting a response, `SendDelayedJoinerEntrust()` previously
set the new joiner's KEK in `KeyManager` before calling
`SendJoinerEntrust()`. Because `SendJoinerEntrust()` calls
`AbortTransaction(HandleJoinerEntrustResponse, this)` synchronously,
the abort handler invoked `HandleJoinerEntrustResponse()` with
`kErrorAbort`, which called `KeyManager::ClearKek()` and cleared the
newly installed KEK (as well as recursively calling
`SendDelayedJoinerEntrust()`) before the new `JOIN_ENT.ntf` message was
sent.

This commit updates KEK handling for Joiner Entrust messages:
- `JoinerRouter::SendJoinerEntrust()` now aborts any previous entrust
  transaction before preparing the message and setting the new KEK in
  `KeyManager`, and clears the KEK if sending fails.
- `JoinerRouter::HandleJoinerEntrustResponse()` exits after clearing
  the KEK when `aResult == kErrorAbort` so aborting an in-flight
  transaction does not recursively trigger `SendDelayedJoinerEntrust()`.
- `MeshForwarder::UpdateIp6Route()` and `MeshForwarder::PrepareFrame()`
  verify `KeyManager::IsKekSet()` before routing or framing a
  `kSubTypeJoinerEntrust` message, and `Mac::ProcessTransmitSecurity()`
  asserts `keyManager.IsKekSet()` for `kKeyIdMode0`.
- Adds a Nexus test `joiner_entrust_kek` covering overlapping Joiner
  Entrust transactions.

src/core/mac/mac.cpp

@@ -796,6 +796,7 @@ void Mac::ProcessTransmitSecurity(TxFrame::ParseInfo &aFrameInfo)
     {
     //- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
     case Frame::kKeyIdMode0:
+        OT_ASSERT(keyManager.IsKekSet());
         aFrameInfo.GetTxFrame()->SetAesKey(keyManager.GetKek());
         extAddress = &GetExtAddress();
 

src/core/meshcop/joiner_router.cpp

@@ -231,9 +231,7 @@ void JoinerRouter::SendDelayedJoinerEntrust(void)
     {
         mDelayedJoinEnts.DequeueAndFree(*message);
 
-        Get<KeyManager>().SetKek(metadata.mKek);
-
-        if (SendJoinerEntrust(metadata.mMessageInfo) != kErrorNone)
+        if (SendJoinerEntrust(metadata) != kErrorNone)
         {
             mTimer.Start(0);
         }
@@ -243,23 +241,31 @@ exit:
     return;
 }
 
-Error JoinerRouter::SendJoinerEntrust(const Ip6::MessageInfo &aMessageInfo)
+Error JoinerRouter::SendJoinerEntrust(const JoinerEntrustMetadata &aMetadata)
 {
-    Error          error = kErrorNone;
-    Coap::Message *message;
+    Error          error   = kErrorNone;
+    Coap::Message *message = nullptr;
+
+    IgnoreError(Get<Tmf::Agent>().AbortTransaction(HandleJoinerEntrustResponse, this));
 
     message = PrepareJoinerEntrustMessage();
     VerifyOrExit(message != nullptr, error = kErrorNoBufs);
 
-    IgnoreError(Get<Tmf::Agent>().AbortTransaction(HandleJoinerEntrustResponse, this));
+    Get<KeyManager>().SetKek(aMetadata.mKek);
 
-    SuccessOrExit(error = Get<Tmf::Agent>().SendMessage(*message, aMessageInfo, HandleJoinerEntrustResponse, this));
+    SuccessOrExit(
+        error = Get<Tmf::Agent>().SendMessage(*message, aMetadata.mMessageInfo, HandleJoinerEntrustResponse, this));
 
     LogInfo("Sent %s (len= %d)", UriToString<kUriJoinerEntrust>(), message->GetLength());
     LogCert("[THCI] direction=send | type=JOIN_ENT.ntf");
 
 exit:
-    FreeMessageOnError(message, error);
+    if (error != kErrorNone)
+    {
+        Get<KeyManager>().ClearKek();
+        FreeMessage(message);
+    }
+
     return error;
 }
 
@@ -300,6 +306,8 @@ void JoinerRouter::HandleJoinerEntrustResponse(Coap::Msg *aMsg, Error aResult)
 {
     Get<KeyManager>().ClearKek();
 
+    VerifyOrExit(aResult != kErrorAbort);
+
     SendDelayedJoinerEntrust();
 
     VerifyOrExit(aResult == kErrorNone && aMsg != nullptr);

src/core/meshcop/joiner_router.hpp

@@ -105,7 +105,7 @@ private:
     void           Start(void);
     void           DelaySendingJoinerEntrust(const Ip6::MessageInfo &aMessageInfo, const Kek &aKek);
     void           SendDelayedJoinerEntrust(void);
-    Error          SendJoinerEntrust(const Ip6::MessageInfo &aMessageInfo);
+    Error          SendJoinerEntrust(const JoinerEntrustMetadata &aMetadata);
     Coap::Message *PrepareJoinerEntrustMessage(void);
 
     using JoinerRouterTimer = TimerMilliIn<JoinerRouter, &JoinerRouter::HandleTimer>;

src/core/thread/mesh_forwarder.cpp

@@ -607,6 +607,11 @@ Error MeshForwarder::UpdateIp6Route(Message &aMessage)
 
     mAddMeshHeader = false;
 
+    if (aMessage.GetSubType() == Message::kSubTypeJoinerEntrust)
+    {
+        VerifyOrExit(Get<KeyManager>().IsKekSet(), error = kErrorDrop);
+    }
+
     IgnoreError(aMessage.Read(0, ip6Header));
 
     VerifyOrExit(!ip6Header.GetSource().IsMulticast(), error = kErrorDrop);
@@ -723,6 +728,12 @@ Mac::TxFrame *MeshForwarder::PrepareFrame(Mac::TxFrames &aTxFrames)
             mSendMessage->SetLinkSecurityEnabled(true);
         }
 #endif
+        if ((mSendMessage->GetSubType() == Message::kSubTypeJoinerEntrust) && !Get<KeyManager>().IsKekSet())
+        {
+            mMessageNextOffset = mSendMessage->GetLength();
+            ExitNow(frame = nullptr);
+        }
+
         mMessageNextOffset = Get<MessageFramer>().PrepareFrame(*frame, *mSendMessage, mMacAddrs, mAddMeshHeader,
                                                                mMeshSource, mMeshDest, addFragHeader);
 

tests/nexus/CMakeLists.txt

@@ -513,4 +513,5 @@ if(TARGET nexus_live_demo)
     endif()
 endif()
 
+ot_nexus_test(joiner_entrust_kek "nexus")
 ot_nexus_test(joiner_finalize_reject "nexus")

tests/nexus/test_joiner_entrust_kek.cpp

@@ -0,0 +1,149 @@
+/*
+ *  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.
+ */
+
+/*
+ * Regression test for Joiner Router KEK handling on overlapping Joiner Entrust
+ * transactions:
+ *
+ * When Joiner A stops responding after its JOIN_ENT.ntf is transmitted (leaving
+ * the first JOIN_ENT.ntf CoAP transaction pending on the Joiner Router) and
+ * Joiner B commissions behind it, aborting Joiner A's pending transaction must
+ * not clear the KEK installed for Joiner B before Joiner B's JOIN_ENT.ntf is
+ * encrypted and sent.
+ */
+
+#include <stdio.h>
+#include <string.h>
+
+#include <openthread/commissioner.h>
+#include <openthread/dataset.h>
+#include <openthread/joiner.h>
+
+#include "platform/nexus_core.hpp"
+#include "platform/nexus_node.hpp"
+
+namespace ot {
+namespace Nexus {
+
+static constexpr uint32_t kFormNetworkTime = 13 * 1000;
+
+static bool  sJoinerBCallbackInvoked;
+static Error sJoinerBResult;
+
+static void HandleJoinerAComplete(otError, void *) {}
+
+static void HandleJoinerBComplete(otError aError, void *)
+{
+    sJoinerBCallbackInvoked = true;
+    sJoinerBResult          = static_cast<Error>(aError);
+}
+
+void TestJoinerEntrustKek(void)
+{
+    Core  nexus;
+    Node &router  = nexus.CreateNode();
+    Node &joinerA = nexus.CreateNode();
+    Node &joinerB = nexus.CreateNode();
+    Kek   kekA;
+    Kek   zeroKek;
+
+    zeroKek.Clear();
+    sJoinerBCallbackInvoked = false;
+    sJoinerBResult          = kErrorFailed;
+
+    nexus.AdvanceTime(0);
+    SuccessOrQuit(Instance::SetGlobalLogLevel(kLogLevelNote));
+
+    router.Form();
+    nexus.AdvanceTime(kFormNetworkTime);
+    VerifyOrQuit(router.Get<Mle::Mle>().IsLeader());
+
+    SuccessOrQuit(otCommissionerStart(&router.GetInstance(), nullptr, nullptr, nullptr));
+    nexus.AdvanceTime(10 * 1000);
+    VerifyOrQuit(otCommissionerGetState(&router.GetInstance()) == OT_COMMISSIONER_STATE_ACTIVE);
+
+    SuccessOrQuit(otCommissionerAddJoiner(&router.GetInstance(), nullptr, "J01NME", 600));
+    nexus.AdvanceTime(2 * 1000);
+
+    // Start Joiner A and advance until the router sets the KEK for Joiner A's JOIN_ENT.ntf.
+    SuccessOrQuit(otIp6SetEnabled(&joinerA.GetInstance(), true));
+    SuccessOrQuit(otJoinerStart(&joinerA.GetInstance(), "J01NME", nullptr, "VendorX", "ModelY", "1.0", nullptr,
+                                HandleJoinerAComplete, nullptr));
+
+    for (int i = 0; (i < 900) && !router.Get<KeyManager>().IsKekSet(); i++)
+    {
+        nexus.AdvanceTime(50);
+    }
+
+    VerifyOrQuit(router.Get<KeyManager>().IsKekSet());
+    router.Get<KeyManager>().ExtractKek(kekA);
+    VerifyOrQuit(kekA != zeroKek);
+
+    // Denylist Joiner A on the router so Joiner A's JOIN_ENT.rsp is dropped and
+    // Joiner A's JOIN_ENT.ntf CoAP transaction remains pending on the router.
+    router.Get<Mac::Filter>().SetMode(Mac::Filter::kModeDenylist);
+    SuccessOrQuit(router.Get<Mac::Filter>().AddAddress(joinerA.Get<Mac::Mac>().GetExtAddress()));
+
+    nexus.AdvanceTime(200);
+    VerifyOrQuit(router.Get<KeyManager>().IsKekSet());
+
+    // Commission Joiner B while Joiner A's JOIN_ENT.ntf transaction is still pending.
+    SuccessOrQuit(otIp6SetEnabled(&joinerB.GetInstance(), true));
+    SuccessOrQuit(otJoinerStart(&joinerB.GetInstance(), "J01NME", nullptr, "VendorX", "ModelZ", "1.0", nullptr,
+                                HandleJoinerBComplete, nullptr));
+
+    for (int i = 0; (i < 1200) && !sJoinerBCallbackInvoked; i++)
+    {
+        nexus.AdvanceTime(25);
+    }
+
+    VerifyOrQuit(sJoinerBCallbackInvoked);
+    VerifyOrQuit(sJoinerBResult == kErrorNone);
+
+    {
+        NetworkKey routerNetworkKey;
+        NetworkKey joinerBNetworkKey;
+
+        router.Get<KeyManager>().GetNetworkKey(routerNetworkKey);
+        joinerB.Get<KeyManager>().GetNetworkKey(joinerBNetworkKey);
+        VerifyOrQuit(joinerBNetworkKey == routerNetworkKey);
+    }
+
+    // Once Joiner B's JOIN_ENT.rsp has been received, the router must have cleared its KEK.
+    VerifyOrQuit(!router.Get<KeyManager>().IsKekSet());
+}
+
+} // namespace Nexus
+} // namespace ot
+
+int main(void)
+{
+    ot::Nexus::TestJoinerEntrustKek();
+    printf("All tests passed\n");
+    return 0;
+}