1 /* 2 * Copyright (c) 2021-22, The OpenThread Authors. 3 * All rights reserved. 4 * 5 * Redistribution and use in source and binary forms, with or without 6 * modification, are permitted provided that the following conditions are met: 7 * 1. Redistributions of source code must retain the above copyright 8 * notice, this list of conditions and the following disclaimer. 9 * 2. Redistributions in binary form must reproduce the above copyright 10 * notice, this list of conditions and the following disclaimer in the 11 * documentation and/or other materials provided with the distribution. 12 * 3. Neither the name of the copyright holder nor the 13 * names of its contributors may be used to endorse or promote products 14 * derived from this software without specific prior written permission. 15 * 16 * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" 17 * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 18 * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 19 * ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE 20 * LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR 21 * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF 22 * SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS 23 * INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN 24 * CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) 25 * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE 26 * POSSIBILITY OF SUCH DAMAGE. 27 */ 28 29 /** 30 * @file 31 * @brief 32 * This file defines the OpenThread Border Routing Manager API. 33 */ 34 35 #ifndef OPENTHREAD_BORDER_ROUTING_H_ 36 #define OPENTHREAD_BORDER_ROUTING_H_ 37 38 #include <openthread/error.h> 39 #include <openthread/ip6.h> 40 #include <openthread/netdata.h> 41 42 #ifdef __cplusplus 43 extern "C" { 44 #endif 45 46 /** 47 * @addtogroup api-border-routing 48 * 49 * @brief 50 * This module includes definitions related to Border Routing Manager. 51 * 52 * 53 * @{ 54 * 55 * All the functions in this module require `OPENTHREAD_CONFIG_BORDER_ROUTING_ENABLE` to be enabled. 56 * 57 * Border Routing Manager handles bi-directional routing between Thread network and adjacent infrastructure link (AIL). 58 * 59 * It emits ICMRv6 ND Router Advertisement (RA) messages on AIL to advertise on-link and route prefixes. It also 60 * processes received RA messages from infrastructure and mirrors the discovered prefixes on the Thread Network Data to 61 * ensure devices on Thread mesh can reach AIL through the Border Router. 62 * 63 * Routing Manager manages the Off-Mesh Routable (OMR) prefix on the Thread Network data which configures Thread 64 * devices with a suitable Off-Mesh Routable IPv6 address. It announces the reachability of this prefix on AIL by 65 * including it in the emitted RA messages as an IPv6 Route Information Option (RIO). 66 * 67 * Routing Manager also monitors and adds on-link prefix on the infrastructure network. If a router on AIL is already 68 * providing RA messages containing an IPv6 Prefix Information Option (PIO) that enables IPv6 devices on the link to 69 * self-configure their own routable unicast IPv6 address, this address can be used by Thread devices to reach AIL. If 70 * Border Router finds no such RA message on AIL, it generates a ULA on-link prefix which it then advertises on AIL in 71 * the emitted RA messages. 72 * 73 */ 74 75 /** 76 * Represents an iterator to iterate through the Border Router's discovered prefix table. 77 * 78 * The fields in this type are opaque (intended for use by OpenThread core only) and therefore should not be 79 * accessed or used by caller. 80 * 81 * Before using an iterator, it MUST be initialized using `otBorderRoutingPrefixTableInitIterator()`. 82 * 83 */ 84 typedef struct otBorderRoutingPrefixTableIterator 85 { 86 const void *mPtr1; 87 const void *mPtr2; 88 uint32_t mData32; 89 } otBorderRoutingPrefixTableIterator; 90 91 /** 92 * Represents a discovered router on the infrastructure link. 93 * 94 */ 95 typedef struct otBorderRoutingRouterEntry 96 { 97 otIp6Address mAddress; ///< IPv6 address of the router. 98 bool mManagedAddressConfigFlag : 1; ///< The router's Managed Address Config flag (`M` flag). 99 bool mOtherConfigFlag : 1; ///< The router's Other Config flag (`O` flag). 100 bool mStubRouterFlag : 1; ///< The router's Stub Router flag. 101 } otBorderRoutingRouterEntry; 102 103 /** 104 * Represents an entry from the discovered prefix table. 105 * 106 * The entries in the discovered table track the Prefix/Route Info Options in the received Router Advertisement messages 107 * from other routers on the infrastructure link. 108 * 109 */ 110 typedef struct otBorderRoutingPrefixTableEntry 111 { 112 otBorderRoutingRouterEntry mRouter; ///< Information about the router advertising this prefix. 113 otIp6Prefix mPrefix; ///< The discovered IPv6 prefix. 114 bool mIsOnLink; ///< Indicates whether the prefix is on-link or route prefix. 115 uint32_t mMsecSinceLastUpdate; ///< Milliseconds since last update of this prefix. 116 uint32_t mValidLifetime; ///< Valid lifetime of the prefix (in seconds). 117 otRoutePreference mRoutePreference; ///< Route preference when `mIsOnlink` is false. 118 uint32_t mPreferredLifetime; ///< Preferred lifetime of the on-link prefix when `mIsOnLink`. 119 } otBorderRoutingPrefixTableEntry; 120 121 /** 122 * Represents a group of data of platform-generated RA messages processed. 123 * 124 */ 125 typedef struct otPdProcessedRaInfo 126 { 127 uint32_t mNumPlatformRaReceived; ///< The number of platform generated RA handled by ProcessPlatformGeneratedRa. 128 uint32_t mNumPlatformPioProcessed; ///< The number of PIO processed for adding OMR prefixes. 129 uint32_t mLastPlatformRaMsec; ///< The timestamp of last processed RA message. 130 } otPdProcessedRaInfo; 131 132 /** 133 * Represents the state of Border Routing Manager. 134 * 135 */ 136 typedef enum 137 { 138 OT_BORDER_ROUTING_STATE_UNINITIALIZED, ///< Routing Manager is uninitialized. 139 OT_BORDER_ROUTING_STATE_DISABLED, ///< Routing Manager is initialized but disabled. 140 OT_BORDER_ROUTING_STATE_STOPPED, ///< Routing Manager in initialized and enabled but currently stopped. 141 OT_BORDER_ROUTING_STATE_RUNNING, ///< Routing Manager is initialized, enabled, and running. 142 } otBorderRoutingState; 143 144 /** 145 * This enumeration represents the state of DHCPv6 Prefix Delegation State. 146 * 147 */ 148 typedef enum 149 { 150 OT_BORDER_ROUTING_DHCP6_PD_STATE_DISABLED, ///< DHCPv6 PD is disabled on the border router. 151 OT_BORDER_ROUTING_DHCP6_PD_STATE_STOPPED, ///< DHCPv6 PD in enabled but won't try to request and publish a prefix. 152 OT_BORDER_ROUTING_DHCP6_PD_STATE_RUNNING, ///< DHCPv6 PD is enabled and will try to request and publish a prefix. 153 } otBorderRoutingDhcp6PdState; 154 155 /** 156 * Initializes the Border Routing Manager on given infrastructure interface. 157 * 158 * @note This method MUST be called before any other otBorderRouting* APIs. 159 * @note This method can be re-called to change the infrastructure interface, but the Border Routing Manager should be 160 * disabled first, and re-enabled after. 161 * 162 * @param[in] aInstance A pointer to an OpenThread instance. 163 * @param[in] aInfraIfIndex The infrastructure interface index. 164 * @param[in] aInfraIfIsRunning A boolean that indicates whether the infrastructure 165 * interface is running. 166 * 167 * @retval OT_ERROR_NONE Successfully started the Border Routing Manager on given infrastructure. 168 * @retval OT_ERROR_INVALID_STATE The Border Routing Manager is in a state other than disabled or uninitialized. 169 * @retval OT_ERROR_INVALID_ARGS The index of the infrastructure interface is not valid. 170 * @retval OT_ERROR_FAILED Internal failure. Usually due to failure in generating random prefixes. 171 * 172 * @sa otPlatInfraIfStateChanged. 173 * @sa otBorderRoutingSetEnabled. 174 * 175 */ 176 otError otBorderRoutingInit(otInstance *aInstance, uint32_t aInfraIfIndex, bool aInfraIfIsRunning); 177 178 /** 179 * Enables or disables the Border Routing Manager. 180 * 181 * @note The Border Routing Manager is disabled by default. 182 * 183 * @param[in] aInstance A pointer to an OpenThread instance. 184 * @param[in] aEnabled A boolean to enable/disable the routing manager. 185 * 186 * @retval OT_ERROR_INVALID_STATE The Border Routing Manager is not initialized yet. 187 * @retval OT_ERROR_NONE Successfully enabled/disabled the Border Routing Manager. 188 * 189 */ 190 otError otBorderRoutingSetEnabled(otInstance *aInstance, bool aEnabled); 191 192 /** 193 * Gets the current state of Border Routing Manager. 194 * 195 * @param[in] aInstance A pointer to an OpenThread instance. 196 * 197 * @returns The current state of Border Routing Manager. 198 * 199 */ 200 otBorderRoutingState otBorderRoutingGetState(otInstance *aInstance); 201 202 /** 203 * Gets the current preference used when advertising Route Info Options (RIO) in Router Advertisement 204 * messages sent over the infrastructure link. 205 * 206 * The RIO preference is determined as follows: 207 * 208 * - If explicitly set by user by calling `otBorderRoutingSetRouteInfoOptionPreference()`, the given preference is 209 * used. 210 * - Otherwise, it is determined based on device's current role: Medium preference when in router/leader role and 211 * low preference when in child role. 212 * 213 * @returns The current Route Info Option preference. 214 * 215 */ 216 otRoutePreference otBorderRoutingGetRouteInfoOptionPreference(otInstance *aInstance); 217 218 /** 219 * Explicitly sets the preference to use when advertising Route Info Options (RIO) in Router 220 * Advertisement messages sent over the infrastructure link. 221 * 222 * After a call to this function, BR will use the given preference for all its advertised RIOs. The preference can be 223 * cleared by calling `otBorderRoutingClearRouteInfoOptionPreference()`. 224 * 225 * @param[in] aInstance A pointer to an OpenThread instance. 226 * @param[in] aPreference The route preference to use. 227 * 228 */ 229 void otBorderRoutingSetRouteInfoOptionPreference(otInstance *aInstance, otRoutePreference aPreference); 230 231 /** 232 * Clears a previously set preference value for advertised Route Info Options. 233 * 234 * After a call to this function, BR will use device's role to determine the RIO preference: Medium preference when 235 * in router/leader role and low preference when in child role. 236 * 237 * @param[in] aInstance A pointer to an OpenThread instance. 238 * 239 */ 240 void otBorderRoutingClearRouteInfoOptionPreference(otInstance *aInstance); 241 242 /** 243 * Sets additional options to append at the end of emitted Router Advertisement (RA) messages. 244 * 245 * The content of @p aOptions is copied internally, so it can be a temporary buffer (e.g., a stack allocated array). 246 * 247 * Subsequent calls to this function overwrite the previously set value. 248 * 249 * @param[in] aOptions A pointer to the encoded options. Can be `NULL` to clear. 250 * @param[in] aLength Number of bytes in @p aOptions. 251 * 252 * @retval OT_ERROR_NONE Successfully set the extra option bytes. 253 * @retval OT_ERROR_NO_BUFS Could not allocate buffer to save the buffer. 254 * 255 */ 256 otError otBorderRoutingSetExtraRouterAdvertOptions(otInstance *aInstance, const uint8_t *aOptions, uint16_t aLength); 257 258 /** 259 * Gets the current preference used for published routes in Network Data. 260 * 261 * The preference is determined as follows: 262 * 263 * - If explicitly set by user by calling `otBorderRoutingSetRoutePreference()`, the given preference is used. 264 * - Otherwise, it is determined automatically by `RoutingManager` based on the device's role and link quality. 265 * 266 * @param[in] aInstance A pointer to an OpenThread instance. 267 * 268 * @returns The current published route preference. 269 * 270 */ 271 otRoutePreference otBorderRoutingGetRoutePreference(otInstance *aInstance); 272 273 /** 274 * Explicitly sets the preference of published routes in Network Data. 275 * 276 * After a call to this function, BR will use the given preference. The preference can be cleared by calling 277 * `otBorderRoutingClearRoutePreference()`. 278 * 279 * @param[in] aInstance A pointer to an OpenThread instance. 280 * @param[in] aPreference The route preference to use. 281 * 282 */ 283 void otBorderRoutingSetRoutePreference(otInstance *aInstance, otRoutePreference aPreference); 284 285 /** 286 * Clears a previously set preference value for published routes in Network Data. 287 * 288 * After a call to this function, BR will determine the preference automatically based on the device's role and 289 * link quality (to the parent when acting as end-device). 290 * 291 * @param[in] aInstance A pointer to an OpenThread instance. 292 * 293 */ 294 void otBorderRoutingClearRoutePreference(otInstance *aInstance); 295 296 /** 297 * Gets the local Off-Mesh-Routable (OMR) Prefix, for example `fdfc:1ff5:1512:5622::/64`. 298 * 299 * An OMR Prefix is a randomly generated 64-bit prefix that's published in the 300 * Thread network if there isn't already an OMR prefix. This prefix can be reached 301 * from the local Wi-Fi or Ethernet network. 302 * 303 * Note: When DHCPv6 PD is enabled, the border router may publish the prefix from 304 * DHCPv6 PD. 305 * 306 * @param[in] aInstance A pointer to an OpenThread instance. 307 * @param[out] aPrefix A pointer to where the prefix will be output to. 308 * 309 * @retval OT_ERROR_INVALID_STATE The Border Routing Manager is not initialized yet. 310 * @retval OT_ERROR_NONE Successfully retrieved the OMR prefix. 311 * 312 * @sa otBorderRoutingGetPdOmrPrefix 313 * 314 */ 315 otError otBorderRoutingGetOmrPrefix(otInstance *aInstance, otIp6Prefix *aPrefix); 316 317 /** 318 * Gets the DHCPv6 Prefix Delegation (PD) provided off-mesh-routable (OMR) prefix. 319 * 320 * Only mPrefix, mValidLifetime and mPreferredLifetime fields are used in the returned prefix info. 321 * 322 * `OPENTHREAD_CONFIG_BORDER_ROUTING_DHCP6_PD_ENABLE` must be enabled. 323 * 324 * @param[in] aInstance A pointer to an OpenThread instance. 325 * @param[out] aPrefixInfo A pointer to where the prefix info will be output to. 326 * 327 * @retval OT_ERROR_NONE Successfully retrieved the OMR prefix. 328 * @retval OT_ERROR_INVALID_STATE The Border Routing Manager is not initialized yet. 329 * @retval OT_ERROR_NOT_FOUND There are no valid PD prefix on this BR. 330 * 331 * @sa otBorderRoutingGetOmrPrefix 332 * @sa otPlatBorderRoutingProcessIcmp6Ra 333 * 334 */ 335 otError otBorderRoutingGetPdOmrPrefix(otInstance *aInstance, otBorderRoutingPrefixTableEntry *aPrefixInfo); 336 337 /** 338 * Gets the data of platform generated RA message processed.. 339 * 340 * `OPENTHREAD_CONFIG_BORDER_ROUTING_DHCP6_PD_ENABLE` must be enabled. 341 * 342 * @param[in] aInstance A pointer to an OpenThread instance. 343 * @param[out] aPrefixInfo A pointer to where the prefix info will be output to. 344 * 345 * @retval OT_ERROR_NONE Successfully retrieved the Info. 346 * @retval OT_ERROR_INVALID_STATE The Border Routing Manager is not initialized yet. 347 * @retval OT_ERROR_NOT_FOUND There are no valid Info on this BR. 348 * 349 */ 350 otError otBorderRoutingGetPdProcessedRaInfo(otInstance *aInstance, otPdProcessedRaInfo *aPdProcessedRaInfo); 351 352 /** 353 * Gets the currently favored Off-Mesh-Routable (OMR) Prefix. 354 * 355 * The favored OMR prefix can be discovered from Network Data or can be this device's local OMR prefix. 356 * 357 * @param[in] aInstance A pointer to an OpenThread instance. 358 * @param[out] aPrefix A pointer to output the favored OMR prefix. 359 * @param[out] aPreference A pointer to output the preference associated the favored prefix. 360 * 361 * @retval OT_ERROR_INVALID_STATE The Border Routing Manager is not running yet. 362 * @retval OT_ERROR_NONE Successfully retrieved the favored OMR prefix. 363 * 364 */ 365 otError otBorderRoutingGetFavoredOmrPrefix(otInstance *aInstance, otIp6Prefix *aPrefix, otRoutePreference *aPreference); 366 367 /** 368 * Gets the local On-Link Prefix for the adjacent infrastructure link. 369 * 370 * The local On-Link Prefix is a 64-bit prefix that's advertised on the infrastructure link if there isn't already a 371 * usable on-link prefix being advertised on the link. 372 * 373 * @param[in] aInstance A pointer to an OpenThread instance. 374 * @param[out] aPrefix A pointer to where the prefix will be output to. 375 * 376 * @retval OT_ERROR_INVALID_STATE The Border Routing Manager is not initialized yet. 377 * @retval OT_ERROR_NONE Successfully retrieved the local on-link prefix. 378 * 379 */ 380 otError otBorderRoutingGetOnLinkPrefix(otInstance *aInstance, otIp6Prefix *aPrefix); 381 382 /** 383 * Gets the currently favored On-Link Prefix. 384 * 385 * The favored prefix is either a discovered on-link prefix on the infrastructure link or the local on-link prefix. 386 * 387 * @param[in] aInstance A pointer to an OpenThread instance. 388 * @param[out] aPrefix A pointer to where the prefix will be output to. 389 * 390 * @retval OT_ERROR_INVALID_STATE The Border Routing Manager is not initialized yet. 391 * @retval OT_ERROR_NONE Successfully retrieved the favored on-link prefix. 392 * 393 */ 394 otError otBorderRoutingGetFavoredOnLinkPrefix(otInstance *aInstance, otIp6Prefix *aPrefix); 395 396 /** 397 * Gets the local NAT64 Prefix of the Border Router. 398 * 399 * NAT64 Prefix might not be advertised in the Thread network. 400 * 401 * `OPENTHREAD_CONFIG_NAT64_BORDER_ROUTING_ENABLE` must be enabled. 402 * 403 * @param[in] aInstance A pointer to an OpenThread instance. 404 * @param[out] aPrefix A pointer to where the prefix will be output to. 405 * 406 * @retval OT_ERROR_INVALID_STATE The Border Routing Manager is not initialized yet. 407 * @retval OT_ERROR_NONE Successfully retrieved the NAT64 prefix. 408 * 409 */ 410 otError otBorderRoutingGetNat64Prefix(otInstance *aInstance, otIp6Prefix *aPrefix); 411 412 /** 413 * Gets the currently favored NAT64 prefix. 414 * 415 * The favored NAT64 prefix can be discovered from infrastructure link or can be this device's local NAT64 prefix. 416 * 417 * @param[in] aInstance A pointer to an OpenThread instance. 418 * @param[out] aPrefix A pointer to output the favored NAT64 prefix. 419 * @param[out] aPreference A pointer to output the preference associated the favored prefix. 420 * 421 * @retval OT_ERROR_INVALID_STATE The Border Routing Manager is not initialized yet. 422 * @retval OT_ERROR_NONE Successfully retrieved the favored NAT64 prefix. 423 * 424 */ 425 otError otBorderRoutingGetFavoredNat64Prefix(otInstance *aInstance, 426 otIp6Prefix *aPrefix, 427 otRoutePreference *aPreference); 428 429 /** 430 * Initializes an `otBorderRoutingPrefixTableIterator`. 431 * 432 * An iterator MUST be initialized before it is used. 433 * 434 * An iterator can be initialized again to restart from the beginning of the table. 435 * 436 * When iterating over entries in the table, to ensure the update times `mMsecSinceLastUpdate` of entries are 437 * consistent, they are given relative to the time the iterator was initialized. 438 * 439 * @param[in] aInstance The OpenThread instance. 440 * @param[out] aIterator A pointer to the iterator to initialize. 441 * 442 */ 443 void otBorderRoutingPrefixTableInitIterator(otInstance *aInstance, otBorderRoutingPrefixTableIterator *aIterator); 444 445 /** 446 * Iterates over the entries in the Border Router's discovered prefix table. 447 * 448 * Prefix entries associated with the same discovered router on an infrastructure link are guaranteed to be grouped 449 * together (retrieved back-to-back). 450 * 451 * @param[in] aInstance The OpenThread instance. 452 * @param[in,out] aIterator A pointer to the iterator. 453 * @param[out] aEntry A pointer to the entry to populate. 454 * 455 * @retval OT_ERROR_NONE Iterated to the next entry, @p aEntry and @p aIterator are updated. 456 * @retval OT_ERROR_NOT_FOUND No more entries in the table. 457 * 458 */ 459 otError otBorderRoutingGetNextPrefixTableEntry(otInstance *aInstance, 460 otBorderRoutingPrefixTableIterator *aIterator, 461 otBorderRoutingPrefixTableEntry *aEntry); 462 463 /** 464 * Iterates over the discovered router entries on the infrastructure link. 465 * 466 * @param[in] aInstance The OpenThread instance. 467 * @param[in,out] aIterator A pointer to the iterator. 468 * @param[out] aEntry A pointer to the entry to populate. 469 * 470 * @retval OT_ERROR_NONE Iterated to the next router, @p aEntry and @p aIterator are updated. 471 * @retval OT_ERROR_NOT_FOUND No more router entries. 472 * 473 */ 474 otError otBorderRoutingGetNextRouterEntry(otInstance *aInstance, 475 otBorderRoutingPrefixTableIterator *aIterator, 476 otBorderRoutingRouterEntry *aEntry); 477 478 /** 479 * Enables / Disables DHCPv6 Prefix Delegation. 480 * 481 * `OPENTHREAD_CONFIG_BORDER_ROUTING_DHCP6_PD_ENABLE` must be enabled. 482 * 483 * @param[in] aInstance A pointer to an OpenThread instance. 484 * @param[in] aEnabled Whether to accept platform generated RA messages. 485 * 486 */ 487 void otBorderRoutingDhcp6PdSetEnabled(otInstance *aInstance, bool aEnabled); 488 489 /** 490 * Gets the current state of DHCPv6 Prefix Delegation. 491 * 492 * Requires `OPENTHREAD_CONFIG_BORDER_ROUTING_DHCP6_PD_ENABLE` to be enabled. 493 * 494 * @param[in] aInstance A pointer to an OpenThread instance. 495 * 496 * @returns The current state of DHCPv6 Prefix Delegation. 497 * 498 */ 499 otBorderRoutingDhcp6PdState otBorderRoutingDhcp6PdGetState(otInstance *aInstance); 500 501 /** 502 * @} 503 * 504 */ 505 506 #ifdef __cplusplus 507 } // extern "C" 508 #endif 509 510 #endif // OPENTHREAD_BORDER_ROUTING_H_ 511