[dhcp6] implement DHCPv6 Prefix Delegation (PD) client (openthread#11584)

This commit introduces the `Dhcp6PdClient` class, which implements
DHCPv6 Prefix Delegation (PD) client functionality. It integrates
with `BorderRouter::RoutingManager` and its `PdPrefixManager`
sub-component. The CMake `OT_BORDER_ROUTING_DHCP6_PD_CLIENT` mapped
to `OPENTHREAD_CONFIG_BORDER_ROUTING_DHCP6_PD_CLIENT_ENABLE` config
enables this feature.

Previously, the platform layer was expected to implement client
functionality, acquiring and providing the delegated prefix(es) to
the OT stack using `otPlatBorderRouter*` callbacks. This approach
continues to be supported. The `Dhcp6PdClient` feature adds native
support for this functionality in the OpenThread core.

The `Dhcp6PdClient` implementation follows RFC 8415, focusing on
prefix delegation and all required behaviors. The client follows the
standard four-message Solicit/Advertise/Request/Reply exchange to
obtain a delegated prefix, followed by a two-message Renew/Reply or
Rebind/Reply exchange to extend the lifetime of the delegated prefix.
When the prefix is no longer needed, a two-message Release/Reply
exchange ends its lease. The current client implementation does not
support the optional "Reconfigure Accept" mechanism.

A set of `otPlatInfraIfDhcp6PdClient*` platform APIs are also
introduced for use by the `Dhcp6PdClient`. These APIs are used to
enable or disable listening for DHCPv6 messages and to handle sending
and receiving them on the standard client and server UDP ports
(546 and 547), effectively acting as a UDP socket.

This commit also includes a comprehensive unit test covering various
aspects of `Dhcp6PdClient`, including common behaviors and many
specific edge cases.

Author: abtink

etc/cmake/options.cmake

@@ -180,6 +180,7 @@ ot_option(OT_BORDER_AGENT_MESHCOP_SERVICE OPENTHREAD_CONFIG_BORDER_AGENT_MESHCOP
 ot_option(OT_BORDER_ROUTER OPENTHREAD_CONFIG_BORDER_ROUTER_ENABLE "border router")
 ot_option(OT_BORDER_ROUTING OPENTHREAD_CONFIG_BORDER_ROUTING_ENABLE "border routing")
 ot_option(OT_BORDER_ROUTING_DHCP6_PD OPENTHREAD_CONFIG_BORDER_ROUTING_DHCP6_PD_ENABLE "dhcpv6 pd support in border routing")
+ot_option(OT_BORDER_ROUTING_DHCP6_PD_CLIENT OPENTHREAD_CONFIG_BORDER_ROUTING_DHCP6_PD_CLIENT_ENABLE "dhcp6 pd client")
 ot_option(OT_BORDER_ROUTING_COUNTERS OPENTHREAD_CONFIG_IP6_BR_COUNTERS_ENABLE "border routing counters")
 ot_option(OT_CHANNEL_MANAGER OPENTHREAD_CONFIG_CHANNEL_MANAGER_ENABLE "channel manager")
 ot_option(OT_CHANNEL_MANAGER_CSL OPENTHREAD_CONFIG_CHANNEL_MANAGER_CSL_CHANNEL_SELECT_ENABLE "channel manager for csl channel")

examples/platforms/simulation/infra_if.c

@@ -214,6 +214,28 @@ otError otPlatInfraIfDiscoverNat64Prefix(uint32_t aInfraIfIndex)
     return OT_ERROR_NONE;
 }
 
+#if OPENTHREAD_CONFIG_BORDER_ROUTING_DHCP6_PD_ENABLE && OPENTHREAD_CONFIG_BORDER_ROUTING_DHCP6_PD_CLIENT_ENABLE
+
+void otPlatInfraIfDhcp6PdClientSetListeningEnabled(otInstance *aInstance, bool aEnable, uint32_t aInfraIfIndex)
+{
+    OT_UNUSED_VARIABLE(aInstance);
+    OT_UNUSED_VARIABLE(aEnable);
+    OT_UNUSED_VARIABLE(aInfraIfIndex);
+}
+
+void otPlatInfraIfDhcp6PdClientSend(otInstance   *aInstance,
+                                    otMessage    *aMessage,
+                                    otIp6Address *aDestAddress,
+                                    uint32_t      aInfraIfIndex)
+{
+    OT_UNUSED_VARIABLE(aInstance);
+    OT_UNUSED_VARIABLE(aDestAddress);
+    OT_UNUSED_VARIABLE(aInfraIfIndex);
+    otMessageFree(aMessage);
+}
+
+#endif // OPENTHREAD_CONFIG_BORDER_ROUTING_DHCP6_PD_ENABLE && OPENTHREAD_CONFIG_BORDER_ROUTING_DHCP6_PD_CLIENT_ENABLE
+
 //---------------------------------------------------------------------------------------------------------------------
 // platformInfraIf
 

include/openthread/instance.h

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

include/openthread/platform/border_routing.h

@@ -45,39 +45,53 @@ extern "C" {
 #endif
 
 /**
- * Handles ICMP6 RA messages received on the Thread interface on the platform.
+ * Callback from the platform to report DHCPv6 Prefix Delegation (PD) prefixes.
  *
- * The `aMessage` should point to a buffer of a valid ICMPv6 message (without IP headers) with router advertisement as
- * the value of type field of the message.
+ * Requires `OPENTHREAD_CONFIG_BORDER_ROUTING_ENABLE` and `OPENTHREAD_CONFIG_BORDER_ROUTING_DHCP6_PD_ENABLE` to
+ * be enabled, while `OPENTHREAD_CONFIG_BORDER_ROUTING_DHCP6_PD_CLIENT_ENABLE` should be disabled.
  *
- * When DHCPv6 PD is disabled, the message will be dropped silently.
+ * When `OPENTHREAD_CONFIG_BORDER_ROUTING_DHCP6_PD_CLIENT_ENABLE` is enabled, the OpenThread stack's native DHCPv6
+ * PD client will be used. Otherwise, the platform layer is expected to interact with DHCPv6 servers to acquire
+ * and provide the delegated prefix(es) using this callback or `otPlatBorderRoutingProcessDhcp6PdPrefix()`.
  *
- * Note: RA messages will not be forwarded into Thread networks, while for many platforms, RA messages is the way of
- * distributing a prefix and other infomations to the downstream network. The typical usecase of this function is to
- * handle the router advertisement messages sent by the platform as a result of DHCPv6 Prefix Delegation.
+ * In this function, an ICMPv6 Router Advertisement (received on the platform's Thread interface) is passed to the
+ * OpenThread stack. This RA message is intended as a mechanism to distribute DHCPv6 PD prefixes to a Thread Border
+ * Router. Each Prefix Information Option (PIO) in the RA is evaluated as a candidate DHCPv6 PD prefix.
  *
- * Requires `OPENTHREAD_CONFIG_BORDER_ROUTING_DHCP6_PD_ENABLE`.
+ * This function can be called again to renew/refresh the lifetimes of PD prefixes or to signal their deprecation
+ * (by setting a zero "preferred lifetime") or removal (by setting a zero "valid lifetime").
+ *
+ * Important note: it is not expected that the RA message will contain all currently valid PD prefixes. The OT stack
+ * will parse the RA and process all included PIOs as PD prefix candidates. Any previously reported PD prefix (from an
+ * earlier call to this function or `otPlatBorderRoutingProcessDhcp6PdPrefix()`) that does not appear in the new RA
+ * remains unchanged (i.e., it will be assumed valid until its previously indicated lifetime expires).
+ *
+ * The `aMessage` should point to a buffer containing the ICMPv6 message payload (excluding the IP headers but
+ * including the ICMPv6 header) with "Router Advertisement" (code 134) as the value of the `Type` field in the ICMPv6
+ * header.
  *
  * @param[in] aInstance A pointer to an OpenThread instance.
- * @param[in] aMessage  A pointer to an ICMPv6 RouterAdvertisement message.
- * @param[in] aLength   The length of ICMPv6 RouterAdvertisement message.
+ * @param[in] aMessage  A pointer to an ICMPv6 Router Advertisement message.
+ * @param[in] aLength   The length of the ICMPv6 Router Advertisement message.
  */
 extern void otPlatBorderRoutingProcessIcmp6Ra(otInstance *aInstance, const uint8_t *aMessage, uint16_t aLength);
 
 /**
- * Process a prefix received from the DHCPv6 PD Server. The prefix is received on
- * the DHCPv6 PD client callback and provided to the Routing Manager via this
- * API.
+ * Callback to report a single DHCPv6 Prefix Delegation (PD) prefix.
+ *
+ * Requires `OPENTHREAD_CONFIG_BORDER_ROUTING_ENABLE` and `OPENTHREAD_CONFIG_BORDER_ROUTING_DHCP6_PD_ENABLE` to
+ * be enabled, while `OPENTHREAD_CONFIG_BORDER_ROUTING_DHCP6_PD_CLIENT_ENABLE` should be disabled.
  *
- * The prefix lifetime can be updated by calling the function again with updated time values.
- * If the preferred lifetime of the prefix is set to 0, the prefix becomes deprecated.
- * When this function is called multiple times, the smallest prefix is preferred as this rule allows
- * choosing a GUA instead of a ULA.
+ * When `OPENTHREAD_CONFIG_BORDER_ROUTING_DHCP6_PD_CLIENT_ENABLE` is enabled, the OpenThread stack's native DHCPv6
+ * PD client will be used. Otherwise, the platform layer is expected to interact with DHCPv6 servers to acquire
+ * and provide the delegated prefix(es) using this callback or `otPlatBorderRoutingProcessIcmp6Ra()`.
  *
- * Requires `OPENTHREAD_CONFIG_BORDER_ROUTING_DHCP6_PD_ENABLE`.
+ * This function can be called again to renew/refresh the lifetimes of PD prefixes or to signal their deprecation
+ * (by setting a zero "preferred lifetime") or removal (by setting a zero "valid lifetime").  This function may be
+ * called multiple times to provide different PD prefixes.
  *
- * @param[in] aInstance   A pointer to an OpenThread instance.
- * @param[in] aPrefixInfo A pointer to the prefix information structure
+ * @param[in] aInstance     A pointer to an OpenThread instance.
+ * @param[in] aPrefixInfo   A pointer to the prefix information structure.
  */
 extern void otPlatBorderRoutingProcessDhcp6PdPrefix(otInstance                            *aInstance,
                                                     const otBorderRoutingPrefixTableEntry *aPrefixInfo);

include/openthread/platform/infra_if.h

@@ -41,6 +41,7 @@
 #include <openthread/error.h>
 #include <openthread/instance.h>
 #include <openthread/ip6.h>
+#include <openthread/message.h>
 
 #ifdef __cplusplus
 extern "C" {
@@ -183,6 +184,66 @@ otError otPlatGetInfraIfLinkLayerAddress(otInstance                    *aInstanc
                                          uint32_t                       aIfIndex,
                                          otPlatInfraIfLinkLayerAddress *aInfraIfLinkLayerAddress);
 
+//---------------------------------------------------------------------------------------------------------------------
+// DHCPv6 Prefix Delegation platform APIs (`OPENTHREAD_CONFIG_BORDER_ROUTING_DHCP6_PD_CLIENT_ENABLE`)
+
+/**
+ * Enables or disables listening for DHCPv6 Prefix Delegation (PD) messages on client.
+ *
+ * This function is only used when `OPENTHREAD_CONFIG_BORDER_ROUTING_DHCP6_PD_CLIENT_ENABLE` is enabled.
+ *
+ * When enabled, the platform must open a UDP socket on the specified infrastructure interface, binding to the DHCPv6
+ * client port 546 to receive messages from DHCPv6 servers.
+ *
+ * @param[in] aInstance      The OpenThread instance.
+ * @param[in] aEnable        A boolean to enable (`true`) or disable (`false`) listening.
+ * @param[in] aInfraIfIndex  The index of the infrastructure interface to operate on.
+ *
+ */
+void otPlatInfraIfDhcp6PdClientSetListeningEnabled(otInstance *aInstance, bool aEnable, uint32_t aInfraIfIndex);
+
+/**
+ * Sends a DHCPv6 message to a unicast or multicast destination address.
+ *
+ * This function is only used when `OPENTHREAD_CONFIG_BORDER_ROUTING_DHCP6_PD_CLIENT_ENABLE` is enabled.
+ *
+ * The platform is responsible for constructing a UDP datagram with the given DHCPv6 message as its payload. The
+ * datagram must be sent from the DHCPv6 client port (546) to the server port (547) on the specified infrastructure
+ * interface. The destination IPv6 address can be a unicast address or the multicast `All_DHCP_Relay_Agents_and_Servers`
+ * address (`ff02::1:2`).
+ *
+ * This function passes the ownership of @p aMessage to the platform layer. Platform MUST then free the message
+ * when no longer needed.
+ *
+ * @param[in] aInstance      The OpenThread instance.
+ * @param[in] aMessage       An `otMessage` containing the DHCPv6 payload. Ownership is passed to the platform layer.
+ * @param[in] aDestAddress   The IPv6 multicast or unicast destination address.
+ * @param[in] aInfraIfIndex  The index of the infrastructure interface from which to send the message.
+ */
+void otPlatInfraIfDhcp6PdClientSend(otInstance   *aInstance,
+                                    otMessage    *aMessage,
+                                    otIp6Address *aDestAddress,
+                                    uint32_t      aInfraIfIndex);
+
+/**
+ * Callback from the platform to notify the OpenThread stack of a received DHCPv6 message.
+ *
+ * This function is provided when `OPENTHREAD_CONFIG_BORDER_ROUTING_DHCP6_PD_CLIENT_ENABLE` is enabled.
+ *
+ * The platform calls this function whenever a DHCPv6 message is received on the client port (546) while listening on
+ * this port is enabled (refer to `otPlatInfraIfDhcp6PdClientSetListeningEnabled()`).
+ *
+ * The platform is responsible for allocating the `otMessage` to pass the received UDP payload. Ownership of the
+ * @p aMessage is passed to the OpenThread stack (which will free it once no longer needed).
+
+ * @param[in] aInstance      The OpenThread instance.
+ * @param[in] aMessage       The `otMessage` containing the received DHCPv6 payload. Ownership is passed to OT stack.
+ * @param[in] aInfraIfIndex  The index of the infrastructure interface from which the message was received..
+ */
+extern void otPlatInfraIfDhcp6PdClientHandleReceived(otInstance *aInstance,
+                                                     otMessage  *aMessage,
+                                                     uint32_t    aInfraIfIndex);
+
 /**
  * @}
  */

src/core/BUILD.gn

@@ -374,6 +374,8 @@ openthread_core_files = [
   "backbone_router/multicast_listeners_table.hpp",
   "backbone_router/ndproxy_table.cpp",
   "backbone_router/ndproxy_table.hpp",
+  "border_router/dhcp6_pd_client.cpp",
+  "border_router/dhcp6_pd_client.hpp",
   "border_router/infra_if.cpp",
   "border_router/infra_if.hpp",
   "border_router/routing_manager.cpp",

src/core/CMakeLists.txt

@@ -94,6 +94,7 @@ set(COMMON_SOURCES
     backbone_router/bbr_manager.cpp
     backbone_router/multicast_listeners_table.cpp
     backbone_router/ndproxy_table.cpp
+    border_router/dhcp6_pd_client.cpp
     border_router/infra_if.cpp
     border_router/routing_manager.cpp
     coap/coap.cpp