diff --git a/include/openthread/BUILD.gn b/include/openthread/BUILD.gn index d7ccf5215..94ffbd4d1 100644 --- a/include/openthread/BUILD.gn +++ b/include/openthread/BUILD.gn @@ -43,6 +43,7 @@ source_set("openthread") { "backbone_router_ftd.h", "ble_secure.h", "border_agent.h", + "border_agent_ephemeral_key.h", "border_agent_tracker.h", "border_agent_txt_data.h", "border_router.h", diff --git a/include/openthread/border_agent.h b/include/openthread/border_agent.h index 952a405d2..8f04e570c 100644 --- a/include/openthread/border_agent.h +++ b/include/openthread/border_agent.h @@ -38,6 +38,7 @@ #include #include +#include // IWYU pragma: keep #include #include #include @@ -400,213 +401,6 @@ const otBorderAgentCounters *otBorderAgentGetCounters(otInstance *aInstance); */ otError otBorderAgentEvictActiveCommissioner(otInstance *aInstance); -/*-------------------------------------------------------------------------------------------------------------------- - * Border Agent Ephemeral Key feature */ - -/** - * Minimum length of the ephemeral key string. - */ -#define OT_BORDER_AGENT_MIN_EPHEMERAL_KEY_LENGTH (6) - -/** - * Maximum length of the ephemeral key string. - */ -#define OT_BORDER_AGENT_MAX_EPHEMERAL_KEY_LENGTH (32) - -/** - * Default ephemeral key timeout interval in milliseconds. - */ -#define OT_BORDER_AGENT_DEFAULT_EPHEMERAL_KEY_TIMEOUT (2 * 60 * 1000u) - -/** - * Maximum ephemeral key timeout interval in milliseconds. - */ -#define OT_BORDER_AGENT_MAX_EPHEMERAL_KEY_TIMEOUT (10 * 60 * 1000u) - -/** - * The string length of Thread Administration One-Time Passcode (TAP). - */ -#define OT_BORDER_AGENT_EPHEMERAL_KEY_TAP_STRING_LENGTH 9 - -/** - * Represents Border Agent's Ephemeral Key Manager state. - */ -typedef enum otBorderAgentEphemeralKeyState -{ - OT_BORDER_AGENT_STATE_DISABLED = 0, ///< Ephemeral Key Manager is disabled. - OT_BORDER_AGENT_STATE_STOPPED = 1, ///< Enabled, but no ephemeral key is in use (not set or started). - OT_BORDER_AGENT_STATE_STARTED = 2, ///< Ephemeral key is set. Listening to accept secure connections. - OT_BORDER_AGENT_STATE_CONNECTED = 3, ///< Session is established with an external commissioner candidate. - OT_BORDER_AGENT_STATE_ACCEPTED = 4, ///< Session is established and candidate is accepted as full commissioner. -} otBorderAgentEphemeralKeyState; - -/** - * Represents a Thread Administration One-Time Passcode (TAP). - */ -typedef struct otBorderAgentEphemeralKeyTap -{ - char mTap[OT_BORDER_AGENT_EPHEMERAL_KEY_TAP_STRING_LENGTH + 1]; ///< TAP string buffer (including `\0` character). -} otBorderAgentEphemeralKeyTap; - -/** - * Gets the state of Border Agent's Ephemeral Key Manager. - * - * Requires `OPENTHREAD_CONFIG_BORDER_AGENT_EPHEMERAL_KEY_ENABLE`. - * - * @param[in] aInstance A pointer to an OpenThread instance. - * - * @returns The current state of Ephemeral Key Manager. - */ -otBorderAgentEphemeralKeyState otBorderAgentEphemeralKeyGetState(otInstance *aInstance); - -/** - * Enables/disables the Border Agent's Ephemeral Key Manager. - * - * Requires `OPENTHREAD_CONFIG_BORDER_AGENT_EPHEMERAL_KEY_ENABLE`. - * - * If this function is called to disable, while an an ephemeral key is in use, the ephemeral key use will be stopped - * (as if `otBorderAgentEphemeralKeyStop()` is called). - * - * @param[in] aInstance The OpenThread instance. - * @param[in] aEnabled Whether to enable or disable the Ephemeral Key Manager. - */ -void otBorderAgentEphemeralKeySetEnabled(otInstance *aInstance, bool aEnabled); - -/** - * Starts using an ephemeral key for a given timeout duration. - * - * Requires `OPENTHREAD_CONFIG_BORDER_AGENT_EPHEMERAL_KEY_ENABLE`. - * - * An ephemeral key can only be set when `otBorderAgentEphemeralKeyGetState()` is `OT_BORDER_AGENT_STATE_STOPPED`, - * i.e., enabled but not yet started. Otherwise, `OT_ERROR_INVALID_STATE` is returned. This means that setting the - * ephemeral key again while a previously set key is still in use will fail. Callers can stop the previous key by - * calling `otBorderAgentEphemeralKeyStop()` before starting with a new key. - * - * The Ephemeral Key Manager and the Border Agent service (which uses PSKc) can be enabled and used in parallel, as - * they use independent and separate DTLS transport and sessions. - * - * The given @p aKeyString is used directly as the ephemeral PSK (excluding the trailing null `\0` character). - * Its length must be between `OT_BORDER_AGENT_MIN_EPHEMERAL_KEY_LENGTH` and `OT_BORDER_AGENT_MAX_EPHEMERAL_KEY_LENGTH`, - * inclusive. Otherwise `OT_ERROR_INVALID_ARGS` is returned. - * - * When successfully set, the ephemeral key can be used only once by an external commissioner candidate to establish a - * secure session. After the commissioner candidate disconnects, the use of the ephemeral key is stopped. If the - * timeout expires, the use of the ephemeral key is stopped, and any connected session using the key is immediately - * disconnected. - * - * The Ephemeral Key Manager limits the number of failed DTLS connections to 10 attempts. After the 10th failed - * attempt, the use of the ephemeral key is automatically stopped (even if the timeout has not yet expired). - * - * @param[in] aInstance The OpenThread instance. - * @param[in] aKeyString The ephemeral key. - * @param[in] aTimeout The timeout duration, in milliseconds, to use the ephemeral key. - * If zero, the default `OT_BORDER_AGENT_DEFAULT_EPHEMERAL_KEY_TIMEOUT` value is used. If the - * timeout value is larger than `OT_BORDER_AGENT_MAX_EPHEMERAL_KEY_TIMEOUT`, the maximum value - * is used instead. - * @param[in] aUdpPort The UDP port to use with the ephemeral key. If the UDP port is zero, an ephemeral port will - * be used. `otBorderAgentEphemeralKeyGetUdpPort()` returns the current UDP port being used. - * - * @retval OT_ERROR_NONE Successfully started using the ephemeral key. - * @retval OT_ERROR_INVALID_STATE A previously set ephemeral key is still in use or the feature is disabled. - * @retval OT_ERROR_INVALID_ARGS The given @p aKeyString is not valid. - * @retval OT_ERROR_FAILED Failed to start (e.g., it could not bind to the given UDP port). - */ -otError otBorderAgentEphemeralKeyStart(otInstance *aInstance, - const char *aKeyString, - uint32_t aTimeout, - uint16_t aUdpPort); - -/** - * Stops the ephemeral key use and disconnects any session using it. - * - * Requires `OPENTHREAD_CONFIG_BORDER_AGENT_EPHEMERAL_KEY_ENABLE`. - * - * If there is no ephemeral key in use, calling this function has no effect. - * - * @param[in] aInstance The OpenThread instance. - */ -void otBorderAgentEphemeralKeyStop(otInstance *aInstance); - -/** - * Gets the UDP port used by Border Agent's Ephemeral Key Manager. - * - * Requires `OPENTHREAD_CONFIG_BORDER_AGENT_EPHEMERAL_KEY_ENABLE`. - * - * The port is applicable if an ephemeral key is in use, i.e., the state is not `OT_BORDER_AGENT_STATE_DISABLED` or - * `OT_BORDER_AGENT_STATE_STOPPED`. - * - * @param[in] aInstance A pointer to an OpenThread instance. - * - * @returns The UDP port being used by Border Agent's Ephemeral Key Manager (when active). - */ -uint16_t otBorderAgentEphemeralKeyGetUdpPort(otInstance *aInstance); - -/** - * Callback function pointer to signal state changes to the Border Agent's Ephemeral Key Manager. - * - * This callback is invoked whenever the `otBorderAgentEphemeralKeyGetState()` gets changed. - * - * Any OpenThread API, including `otBorderAgent` APIs, can be safely called from this callback. - * - * @param[in] aContext A pointer to an arbitrary context (provided when callback is set). - */ -typedef void (*otBorderAgentEphemeralKeyCallback)(void *aContext); - -/** - * Sets the callback function to notify state changes of Border Agent's Ephemeral Key Manager. - * - * Requires `OPENTHREAD_CONFIG_BORDER_AGENT_EPHEMERAL_KEY_ENABLE`. - * - * A subsequent call to this function will replace any previously set callback. - * - * @param[in] aInstance The OpenThread instance. - * @param[in] aCallback The callback function pointer. - * @param[in] aContext The arbitrary context to use with callback. - */ -void otBorderAgentEphemeralKeySetCallback(otInstance *aInstance, - otBorderAgentEphemeralKeyCallback aCallback, - void *aContext); - -/** - * Converts a given `otBorderAgentEphemeralKeyState` to a human-readable string. - * - * @param[in] aState The state to convert. - * - * @returns Human-readable string corresponding to @p aState. - */ -const char *otBorderAgentEphemeralKeyStateToString(otBorderAgentEphemeralKeyState aState); - -/** - * Generates a cryptographically secure random Thread Administration One-Time Passcode (TAP) string. - * - * Requires `OPENTHREAD_CONFIG_BORDER_AGENT_EPHEMERAL_KEY_ENABLE` and `OPENTHREAD_CONFIG_VERHOEFF_CHECKSUM_ENABLE`. - * - * The TAP is a string of 9 characters, generated as a sequence of eight cryptographically secure random - * numeric digits [`0`-`9`] followed by a single check digit determined using the Verhoeff algorithm. - * - * @param[out] aTap A pointer to an `otBorderAgentEphemeralKeyTap` to output the generated TAP. - * - * @retval OT_ERROR_NONE Successfully generated a random TAP. @p aTap is updated. - * @retval OT_ERROR_FAILED Failed to generate a random TAP. - */ -otError otBorderAgentEphemeralKeyGenerateTap(otBorderAgentEphemeralKeyTap *aTap); - -/** - * Validates a given Thread Administration One-Time Passcode (TAP) string. - * - * Requires `OPENTHREAD_CONFIG_BORDER_AGENT_EPHEMERAL_KEY_ENABLE` and `OPENTHREAD_CONFIG_VERHOEFF_CHECKSUM_ENABLE`. - * - * Validates that the TAP string has the proper length, contains digit characters [`0`-`9`], and validates the - * Verhoeff checksum. - * - * @param[in] aTap The `otBorderAgentEphemeralKeyTap` to validate. - * - * @retval OT_ERROR_NONE Successfully validated the @p aTap. - * @retval OT_ERROR_INVALID_ARGS The @p aTap string has an invalid length or contains non-digit characters. - * @retval OT_ERROR_FAILED Checksum validation failed. - */ -otError otBorderAgentEphemeralKeyValidateTap(const otBorderAgentEphemeralKeyTap *aTap); - /** * @} */ diff --git a/include/openthread/border_agent_ephemeral_key.h b/include/openthread/border_agent_ephemeral_key.h new file mode 100644 index 000000000..c463f9939 --- /dev/null +++ b/include/openthread/border_agent_ephemeral_key.h @@ -0,0 +1,268 @@ +/* + * Copyright (c) 2025, 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. + */ + +/** + * @file + * @brief + * This file includes functions for the Thread Border Agent Ephemeral Key. */ + +#ifndef OPENTHREAD_BORDER_AGENT_EPHEMERAL_KEY_H_ +#define OPENTHREAD_BORDER_AGENT_EPHEMERAL_KEY_H_ + +#include +#include + +#include +#include + +#ifdef __cplusplus +extern "C" { +#endif + +/** + * @addtogroup api-border-agent + * + * @brief + * This module includes functions for the Thread Border Agent role. + * + * @{ + */ + +/** + * Minimum length of the ephemeral key string. + */ +#define OT_BORDER_AGENT_MIN_EPHEMERAL_KEY_LENGTH (6) + +/** + * Maximum length of the ephemeral key string. + */ +#define OT_BORDER_AGENT_MAX_EPHEMERAL_KEY_LENGTH (32) + +/** + * Default ephemeral key timeout interval in milliseconds. + */ +#define OT_BORDER_AGENT_DEFAULT_EPHEMERAL_KEY_TIMEOUT (2 * 60 * 1000u) + +/** + * Maximum ephemeral key timeout interval in milliseconds. + */ +#define OT_BORDER_AGENT_MAX_EPHEMERAL_KEY_TIMEOUT (10 * 60 * 1000u) + +/** + * The string length of Thread Administration One-Time Passcode (TAP). + */ +#define OT_BORDER_AGENT_EPHEMERAL_KEY_TAP_STRING_LENGTH 9 + +/** + * Represents Border Agent's Ephemeral Key Manager state. + */ +typedef enum otBorderAgentEphemeralKeyState +{ + OT_BORDER_AGENT_STATE_DISABLED = 0, ///< Ephemeral Key Manager is disabled. + OT_BORDER_AGENT_STATE_STOPPED = 1, ///< Enabled, but no ephemeral key is in use (not set or started). + OT_BORDER_AGENT_STATE_STARTED = 2, ///< Ephemeral key is set. Listening to accept secure connections. + OT_BORDER_AGENT_STATE_CONNECTED = 3, ///< Session is established with an external commissioner candidate. + OT_BORDER_AGENT_STATE_ACCEPTED = 4, ///< Session is established and candidate is accepted as full commissioner. +} otBorderAgentEphemeralKeyState; + +/** + * Represents a Thread Administration One-Time Passcode (TAP). + */ +typedef struct otBorderAgentEphemeralKeyTap +{ + char mTap[OT_BORDER_AGENT_EPHEMERAL_KEY_TAP_STRING_LENGTH + 1]; ///< TAP string buffer (including `\0` character). +} otBorderAgentEphemeralKeyTap; + +/** + * Gets the state of Border Agent's Ephemeral Key Manager. + * + * Requires `OPENTHREAD_CONFIG_BORDER_AGENT_EPHEMERAL_KEY_ENABLE`. + * + * @param[in] aInstance A pointer to an OpenThread instance. + * + * @returns The current state of Ephemeral Key Manager. + */ +otBorderAgentEphemeralKeyState otBorderAgentEphemeralKeyGetState(otInstance *aInstance); + +/** + * Enables/disables the Border Agent's Ephemeral Key Manager. + * + * Requires `OPENTHREAD_CONFIG_BORDER_AGENT_EPHEMERAL_KEY_ENABLE`. + * + * If this function is called to disable, while an an ephemeral key is in use, the ephemeral key use will be stopped + * (as if `otBorderAgentEphemeralKeyStop()` is called). + * + * @param[in] aInstance The OpenThread instance. + * @param[in] aEnabled Whether to enable or disable the Ephemeral Key Manager. + */ +void otBorderAgentEphemeralKeySetEnabled(otInstance *aInstance, bool aEnabled); + +/** + * Starts using an ephemeral key for a given timeout duration. + * + * Requires `OPENTHREAD_CONFIG_BORDER_AGENT_EPHEMERAL_KEY_ENABLE`. + * + * An ephemeral key can only be set when `otBorderAgentEphemeralKeyGetState()` is `OT_BORDER_AGENT_STATE_STOPPED`, + * i.e., enabled but not yet started. Otherwise, `OT_ERROR_INVALID_STATE` is returned. This means that setting the + * ephemeral key again while a previously set key is still in use will fail. Callers can stop the previous key by + * calling `otBorderAgentEphemeralKeyStop()` before starting with a new key. + * + * The Ephemeral Key Manager and the Border Agent service (which uses PSKc) can be enabled and used in parallel, as + * they use independent and separate DTLS transport and sessions. + * + * The given @p aKeyString is used directly as the ephemeral PSK (excluding the trailing null `\0` character). + * Its length must be between `OT_BORDER_AGENT_MIN_EPHEMERAL_KEY_LENGTH` and `OT_BORDER_AGENT_MAX_EPHEMERAL_KEY_LENGTH`, + * inclusive. Otherwise `OT_ERROR_INVALID_ARGS` is returned. + * + * When successfully set, the ephemeral key can be used only once by an external commissioner candidate to establish a + * secure session. After the commissioner candidate disconnects, the use of the ephemeral key is stopped. If the + * timeout expires, the use of the ephemeral key is stopped, and any connected session using the key is immediately + * disconnected. + * + * The Ephemeral Key Manager limits the number of failed DTLS connections to 10 attempts. After the 10th failed + * attempt, the use of the ephemeral key is automatically stopped (even if the timeout has not yet expired). + * + * @param[in] aInstance The OpenThread instance. + * @param[in] aKeyString The ephemeral key. + * @param[in] aTimeout The timeout duration, in milliseconds, to use the ephemeral key. + * If zero, the default `OT_BORDER_AGENT_DEFAULT_EPHEMERAL_KEY_TIMEOUT` value is used. If the + * timeout value is larger than `OT_BORDER_AGENT_MAX_EPHEMERAL_KEY_TIMEOUT`, the maximum value + * is used instead. + * @param[in] aUdpPort The UDP port to use with the ephemeral key. If the UDP port is zero, an ephemeral port will + * be used. `otBorderAgentEphemeralKeyGetUdpPort()` returns the current UDP port being used. + * + * @retval OT_ERROR_NONE Successfully started using the ephemeral key. + * @retval OT_ERROR_INVALID_STATE A previously set ephemeral key is still in use or the feature is disabled. + * @retval OT_ERROR_INVALID_ARGS The given @p aKeyString is not valid. + * @retval OT_ERROR_FAILED Failed to start (e.g., it could not bind to the given UDP port). + */ +otError otBorderAgentEphemeralKeyStart(otInstance *aInstance, + const char *aKeyString, + uint32_t aTimeout, + uint16_t aUdpPort); + +/** + * Stops the ephemeral key use and disconnects any session using it. + * + * Requires `OPENTHREAD_CONFIG_BORDER_AGENT_EPHEMERAL_KEY_ENABLE`. + * + * If there is no ephemeral key in use, calling this function has no effect. + * + * @param[in] aInstance The OpenThread instance. + */ +void otBorderAgentEphemeralKeyStop(otInstance *aInstance); + +/** + * Gets the UDP port used by Border Agent's Ephemeral Key Manager. + * + * Requires `OPENTHREAD_CONFIG_BORDER_AGENT_EPHEMERAL_KEY_ENABLE`. + * + * The port is applicable if an ephemeral key is in use, i.e., the state is not `OT_BORDER_AGENT_STATE_DISABLED` or + * `OT_BORDER_AGENT_STATE_STOPPED`. + * + * @param[in] aInstance A pointer to an OpenThread instance. + * + * @returns The UDP port being used by Border Agent's Ephemeral Key Manager (when active). + */ +uint16_t otBorderAgentEphemeralKeyGetUdpPort(otInstance *aInstance); + +/** + * Callback function pointer to signal state changes to the Border Agent's Ephemeral Key Manager. + * + * This callback is invoked whenever the `otBorderAgentEphemeralKeyGetState()` gets changed. + * + * Any OpenThread API, including `otBorderAgent` APIs, can be safely called from this callback. + * + * @param[in] aContext A pointer to an arbitrary context (provided when callback is set). + */ +typedef void (*otBorderAgentEphemeralKeyCallback)(void *aContext); + +/** + * Sets the callback function to notify state changes of Border Agent's Ephemeral Key Manager. + * + * Requires `OPENTHREAD_CONFIG_BORDER_AGENT_EPHEMERAL_KEY_ENABLE`. + * + * A subsequent call to this function will replace any previously set callback. + * + * @param[in] aInstance The OpenThread instance. + * @param[in] aCallback The callback function pointer. + * @param[in] aContext The arbitrary context to use with callback. + */ +void otBorderAgentEphemeralKeySetCallback(otInstance *aInstance, + otBorderAgentEphemeralKeyCallback aCallback, + void *aContext); + +/** + * Converts a given `otBorderAgentEphemeralKeyState` to a human-readable string. + * + * @param[in] aState The state to convert. + * + * @returns Human-readable string corresponding to @p aState. + */ +const char *otBorderAgentEphemeralKeyStateToString(otBorderAgentEphemeralKeyState aState); + +/** + * Generates a cryptographically secure random Thread Administration One-Time Passcode (TAP) string. + * + * Requires `OPENTHREAD_CONFIG_BORDER_AGENT_EPHEMERAL_KEY_ENABLE` and `OPENTHREAD_CONFIG_VERHOEFF_CHECKSUM_ENABLE`. + * + * The TAP is a string of 9 characters, generated as a sequence of eight cryptographically secure random + * numeric digits [`0`-`9`] followed by a single check digit determined using the Verhoeff algorithm. + * + * @param[out] aTap A pointer to an `otBorderAgentEphemeralKeyTap` to output the generated TAP. + * + * @retval OT_ERROR_NONE Successfully generated a random TAP. @p aTap is updated. + * @retval OT_ERROR_FAILED Failed to generate a random TAP. + */ +otError otBorderAgentEphemeralKeyGenerateTap(otBorderAgentEphemeralKeyTap *aTap); + +/** + * Validates a given Thread Administration One-Time Passcode (TAP) string. + * + * Requires `OPENTHREAD_CONFIG_BORDER_AGENT_EPHEMERAL_KEY_ENABLE` and `OPENTHREAD_CONFIG_VERHOEFF_CHECKSUM_ENABLE`. + * + * Validates that the TAP string has the proper length, contains digit characters [`0`-`9`], and validates the + * Verhoeff checksum. + * + * @param[in] aTap The `otBorderAgentEphemeralKeyTap` to validate. + * + * @retval OT_ERROR_NONE Successfully validated the @p aTap. + * @retval OT_ERROR_INVALID_ARGS The @p aTap string has an invalid length or contains non-digit characters. + * @retval OT_ERROR_FAILED Checksum validation failed. + */ +otError otBorderAgentEphemeralKeyValidateTap(const otBorderAgentEphemeralKeyTap *aTap); + +/** + * @} + */ + +#ifdef __cplusplus +} // end of extern "C" +#endif + +#endif // OPENTHREAD_BORDER_AGENT_EPHEMERAL_KEY_H_ diff --git a/include/openthread/instance.h b/include/openthread/instance.h index 360f76523..095db491c 100644 --- a/include/openthread/instance.h +++ b/include/openthread/instance.h @@ -52,7 +52,7 @@ extern "C" { * * @note This number versions both OpenThread platform and user APIs. */ -#define OPENTHREAD_API_VERSION (561) +#define OPENTHREAD_API_VERSION (562) /** * @addtogroup api-instance diff --git a/src/core/BUILD.gn b/src/core/BUILD.gn index 25720cd3d..800fe7282 100644 --- a/src/core/BUILD.gn +++ b/src/core/BUILD.gn @@ -165,6 +165,7 @@ openthread_core_files = [ "api/backbone_router_ftd_api.cpp", "api/ble_secure_api.cpp", "api/border_agent_api.cpp", + "api/border_agent_ephemeral_key_api.cpp", "api/border_agent_tracker_api.cpp", "api/border_agent_txt_data_api.cpp", "api/border_router_api.cpp", diff --git a/src/core/CMakeLists.txt b/src/core/CMakeLists.txt index 1707d4436..8c186953d 100644 --- a/src/core/CMakeLists.txt +++ b/src/core/CMakeLists.txt @@ -35,6 +35,7 @@ set(COMMON_SOURCES api/backbone_router_ftd_api.cpp api/ble_secure_api.cpp api/border_agent_api.cpp + api/border_agent_ephemeral_key_api.cpp api/border_agent_tracker_api.cpp api/border_agent_txt_data_api.cpp api/border_router_api.cpp diff --git a/src/core/api/border_agent_api.cpp b/src/core/api/border_agent_api.cpp index 2dde67c70..8e755893e 100644 --- a/src/core/api/border_agent_api.cpp +++ b/src/core/api/border_agent_api.cpp @@ -126,66 +126,4 @@ otError otBorderAgentEvictActiveCommissioner(otInstance *aInstance) } #endif -#if OPENTHREAD_CONFIG_BORDER_AGENT_EPHEMERAL_KEY_ENABLE - -otBorderAgentEphemeralKeyState otBorderAgentEphemeralKeyGetState(otInstance *aInstance) -{ - return MapEnum(AsCoreType(aInstance).Get().GetState()); -} - -void otBorderAgentEphemeralKeySetEnabled(otInstance *aInstance, bool aEnabled) -{ - AsCoreType(aInstance).Get().SetEnabled(aEnabled); -} - -otError otBorderAgentEphemeralKeyStart(otInstance *aInstance, - const char *aKeyString, - uint32_t aTimeout, - uint16_t aUdpPort) -{ - AssertPointerIsNotNull(aKeyString); - - return AsCoreType(aInstance).Get().Start(aKeyString, aTimeout, aUdpPort); -} - -void otBorderAgentEphemeralKeyStop(otInstance *aInstance) -{ - AsCoreType(aInstance).Get().Stop(); -} - -uint16_t otBorderAgentEphemeralKeyGetUdpPort(otInstance *aInstance) -{ - return AsCoreType(aInstance).Get().GetUdpPort(); -} - -void otBorderAgentEphemeralKeySetCallback(otInstance *aInstance, - otBorderAgentEphemeralKeyCallback aCallback, - void *aContext) -{ - AsCoreType(aInstance).Get().SetCallback(aCallback, aContext); -} - -const char *otBorderAgentEphemeralKeyStateToString(otBorderAgentEphemeralKeyState aState) -{ - OT_ASSERT(aState <= OT_BORDER_AGENT_STATE_ACCEPTED); - - return MeshCoP::BorderAgent::EphemeralKeyManager::StateToString(MapEnum(aState)); -} - -#if OPENTHREAD_CONFIG_VERHOEFF_CHECKSUM_ENABLE - -otError otBorderAgentEphemeralKeyGenerateTap(otBorderAgentEphemeralKeyTap *aTap) -{ - return AsCoreType(aTap).GenerateRandom(); -} - -otError otBorderAgentEphemeralKeyValidateTap(const otBorderAgentEphemeralKeyTap *aTap) -{ - return AsCoreType(aTap).Validate(); -} - -#endif - -#endif // OPENTHREAD_CONFIG_BORDER_AGENT_EPHEMERAL_KEY_ENABLE - #endif // OPENTHREAD_CONFIG_BORDER_AGENT_ENABLE diff --git a/src/core/api/border_agent_ephemeral_key_api.cpp b/src/core/api/border_agent_ephemeral_key_api.cpp new file mode 100644 index 000000000..548adc74f --- /dev/null +++ b/src/core/api/border_agent_ephemeral_key_api.cpp @@ -0,0 +1,102 @@ +/* + * Copyright (c) 2025, 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. + */ + +/** + * @file + * This file implements the OpenThread Border Agent Ephemeral Key APIs. + */ + +#include "openthread-core-config.h" + +#if OPENTHREAD_CONFIG_BORDER_AGENT_ENABLE && OPENTHREAD_CONFIG_BORDER_AGENT_EPHEMERAL_KEY_ENABLE + +#include + +#include "instance/instance.hpp" + +using namespace ot; + +otBorderAgentEphemeralKeyState otBorderAgentEphemeralKeyGetState(otInstance *aInstance) +{ + return MapEnum(AsCoreType(aInstance).Get().GetState()); +} + +void otBorderAgentEphemeralKeySetEnabled(otInstance *aInstance, bool aEnabled) +{ + AsCoreType(aInstance).Get().SetEnabled(aEnabled); +} + +otError otBorderAgentEphemeralKeyStart(otInstance *aInstance, + const char *aKeyString, + uint32_t aTimeout, + uint16_t aUdpPort) +{ + AssertPointerIsNotNull(aKeyString); + + return AsCoreType(aInstance).Get().Start(aKeyString, aTimeout, aUdpPort); +} + +void otBorderAgentEphemeralKeyStop(otInstance *aInstance) +{ + AsCoreType(aInstance).Get().Stop(); +} + +uint16_t otBorderAgentEphemeralKeyGetUdpPort(otInstance *aInstance) +{ + return AsCoreType(aInstance).Get().GetUdpPort(); +} + +void otBorderAgentEphemeralKeySetCallback(otInstance *aInstance, + otBorderAgentEphemeralKeyCallback aCallback, + void *aContext) +{ + AsCoreType(aInstance).Get().SetCallback(aCallback, aContext); +} + +const char *otBorderAgentEphemeralKeyStateToString(otBorderAgentEphemeralKeyState aState) +{ + OT_ASSERT(aState <= OT_BORDER_AGENT_STATE_ACCEPTED); + + return MeshCoP::BorderAgent::EphemeralKeyManager::StateToString(MapEnum(aState)); +} + +#if OPENTHREAD_CONFIG_VERHOEFF_CHECKSUM_ENABLE + +otError otBorderAgentEphemeralKeyGenerateTap(otBorderAgentEphemeralKeyTap *aTap) +{ + return AsCoreType(aTap).GenerateRandom(); +} + +otError otBorderAgentEphemeralKeyValidateTap(const otBorderAgentEphemeralKeyTap *aTap) +{ + return AsCoreType(aTap).Validate(); +} + +#endif + +#endif // OPENTHREAD_CONFIG_BORDER_AGENT_ENABLE && OPENTHREAD_CONFIG_BORDER_AGENT_EPHEMERAL_KEY_ENABLE