Border Agent

This module includes functions for the Thread Border Agent role.

Summary

Enumerations
otBorderAgentEphemeralKeyState{
  OT_BORDER_AGENT_STATE_DISABLED = 0,
  OT_BORDER_AGENT_STATE_STOPPED = 1,
  OT_BORDER_AGENT_STATE_STARTED = 2,
  OT_BORDER_AGENT_STATE_CONNECTED = 3,
  OT_BORDER_AGENT_STATE_ACCEPTED = 4
} 		enum
Represents Border Agent's Ephemeral Key Manager state.

Typedefs
otBorderAgentCounters typedef
Defines Border Agent counters.
otBorderAgentEphemeralKeyCallback)(void *aContext) typedef
void(*
Callback function pointer to signal state changes to the Border Agent's Ephemeral Key Manager.
otBorderAgentEphemeralKeyState typedef
Represents Border Agent's Ephemeral Key Manager state.
otBorderAgentId typedef
Represents a Border Agent Identifier.
otBorderAgentMeshCoPServiceChangedCallback)(const uint8_t *aTxtData, uint16_t aLength, void *aContext) typedef
void(*
This callback informs the application of the changes in the state of the MeshCoP service.
otBorderAgentSessionInfo typedef
Represents information about a Border Agent session.
otBorderAgentSessionIterator typedef
Represents an iterator for Border Agent sessions.

Functions
otBorderAgentEphemeralKeyGetState(otInstance *aInstance)
Gets the state of Border Agent's Ephemeral Key Manager.
otBorderAgentEphemeralKeyGetUdpPort(otInstance *aInstance)
uint16_t
Gets the UDP port used by Border Agent's Ephemeral Key Manager.
otBorderAgentEphemeralKeySetCallback(otInstance *aInstance, otBorderAgentEphemeralKeyCallback aCallback, void *aContext)
void
Sets the callback function to notify state changes of Border Agent's Ephemeral Key Manager.
otBorderAgentEphemeralKeySetEnabled(otInstance *aInstance, bool aEnabled)
void
Enables/disables the Border Agent's Ephemeral Key Manager.
otBorderAgentEphemeralKeyStart(otInstance *aInstance, const char *aKeyString, uint32_t aTimeout, uint16_t aUdpPort)
Starts using an ephemeral key for a given timeout duration.
otBorderAgentEphemeralKeyStateToString(otBorderAgentEphemeralKeyState aState)
const char *
Converts a given otBorderAgentEphemeralKeyState to a human-readable string.
otBorderAgentEphemeralKeyStop(otInstance *aInstance)
void
Stops the ephemeral key use and disconnects any session using it.
otBorderAgentGetCounters(otInstance *aInstance)
Gets the counters of the Thread Border Agent.
otBorderAgentGetId(otInstance *aInstance, otBorderAgentId *aId)
Gets the randomly generated Border Agent ID.
otBorderAgentGetNextSessionInfo(otBorderAgentSessionIterator *aIterator, otBorderAgentSessionInfo *aSessionInfo)
Retrieves the next Border Agent session information.
otBorderAgentGetUdpPort(otInstance *aInstance)
uint16_t
Gets the UDP port of the Thread Border Agent service.
otBorderAgentInitSessionIterator(otInstance *aInstance, otBorderAgentSessionIterator *aIterator)
void
Initializes a session iterator.
otBorderAgentIsActive(otInstance *aInstance)
bool
Indicates whether or not the Border Agent service is active and running.
otBorderAgentSetId(otInstance *aInstance, const otBorderAgentId *aId)
Sets the Border Agent ID.
otBorderAgentSetMeshCoPServiceChangedCallback(otInstance *aInstance, otBorderAgentMeshCoPServiceChangedCallback aCallback, void *aContext)
void
Sets the callback function used by the Border Agent to notify of any changes to the state of the MeshCoP service.

Macros
OT_BORDER_AGENT_DEFAULT_EPHEMERAL_KEY_TIMEOUT (2 * 60 * 1000u)
Default ephemeral key timeout interval in milliseconds.
OT_BORDER_AGENT_ID_LENGTH (16)
The length of Border Agent/Router ID in bytes.
OT_BORDER_AGENT_MAX_EPHEMERAL_KEY_LENGTH (32)
Maximum length of the ephemeral key string.
OT_BORDER_AGENT_MAX_EPHEMERAL_KEY_TIMEOUT (10 * 60 * 1000u)
Maximum ephemeral key timeout interval in milliseconds.
OT_BORDER_AGENT_MIN_EPHEMERAL_KEY_LENGTH (6)
Minimum length of the ephemeral key string.

Structs
otBorderAgentCounters

Defines Border Agent counters.

otBorderAgentId

Represents a Border Agent Identifier.

otBorderAgentSessionInfo

Represents information about a Border Agent session.

otBorderAgentSessionIterator

Represents an iterator for Border Agent sessions.

Enumerations

otBorderAgentEphemeralKeyState

 otBorderAgentEphemeralKeyState

Represents Border Agent's Ephemeral Key Manager state.

Properties
OT_BORDER_AGENT_STATE_ACCEPTED

Session is established and candidate is accepted as full commissioner.

OT_BORDER_AGENT_STATE_CONNECTED

Session is established with an external commissioner candidate.

OT_BORDER_AGENT_STATE_DISABLED

Ephemeral Key Manager is disabled.

OT_BORDER_AGENT_STATE_STARTED

Ephemeral key is set. Listening to accept secure connections.

OT_BORDER_AGENT_STATE_STOPPED

Enabled, but no ephemeral key is in use (not set or started).

Typedefs

otBorderAgentCounters

struct otBorderAgentCounters otBorderAgentCounters

Defines Border Agent counters.

The mEpskc related counters require OPENTHREAD_CONFIG_BORDER_AGENT_EPHEMERAL_KEY_ENABLE.

otBorderAgentEphemeralKeyCallback

void(* otBorderAgentEphemeralKeyCallback)(void *aContext)

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.

Details
Parameters
[in] aContext
A pointer to an arbitrary context (provided when callback is set).

otBorderAgentEphemeralKeyState

enum otBorderAgentEphemeralKeyState otBorderAgentEphemeralKeyState

Represents Border Agent's Ephemeral Key Manager state.

otBorderAgentId

struct otBorderAgentId otBorderAgentId

Represents a Border Agent Identifier.

otBorderAgentMeshCoPServiceChangedCallback

void(* otBorderAgentMeshCoPServiceChangedCallback)(const uint8_t *aTxtData, uint16_t aLength, void *aContext)

This callback informs the application of the changes in the state of the MeshCoP service.

In specific, the 'state' includes the MeshCoP TXT data originated from the Thread network and whether the Border Agent is Active (which can be obtained by otBorderAgentIsActive).

Details
Parameters
[in] aTxtData
A pointer to the encoded MeshCoP TXT data originated from the Thread network.
[in] aLength
The length of the encoded TXT data.
[in] aContext
A pointer to application-specific context.

otBorderAgentSessionInfo

struct otBorderAgentSessionInfo otBorderAgentSessionInfo

Represents information about a Border Agent session.

This structure is populated by otBorderAgentGetNextSessionInfo() during iteration over the list of sessions using an otBorderAgentSessionIterator.

To ensure consistent mLifetime calculations, the iterator's initialization time is stored within the iterator, and each session's mLifetime is calculated relative to this time.

otBorderAgentSessionIterator

struct otBorderAgentSessionIterator otBorderAgentSessionIterator

Represents an iterator for Border Agent sessions.

The caller MUST NOT access or update the fields in this struct. It is intended for OpenThread internal use only.

Functions

otBorderAgentEphemeralKeyGetState

otBorderAgentEphemeralKeyState otBorderAgentEphemeralKeyGetState(
  otInstance *aInstance
)

Gets the state of Border Agent's Ephemeral Key Manager.

Requires OPENTHREAD_CONFIG_BORDER_AGENT_EPHEMERAL_KEY_ENABLE.

Details
Parameters
[in] aInstance
A pointer to an OpenThread instance.
Returns
The current state of Ephemeral Key Manager.

otBorderAgentEphemeralKeyGetUdpPort

uint16_t otBorderAgentEphemeralKeyGetUdpPort(
  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.

Details
Parameters
[in] aInstance
A pointer to an OpenThread instance.
Returns
The UDP port being used by Border Agent's Ephemeral Key Manager (when active).

otBorderAgentEphemeralKeySetCallback

void otBorderAgentEphemeralKeySetCallback(
  otInstance *aInstance,
  otBorderAgentEphemeralKeyCallback aCallback,
  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.

Details
Parameters
[in] aInstance
The OpenThread instance.
[in] aCallback
The callback function pointer.
[in] aContext
The arbitrary context to use with callback.

otBorderAgentEphemeralKeySetEnabled

void otBorderAgentEphemeralKeySetEnabled(
  otInstance *aInstance,
  bool aEnabled
)

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).

Details
Parameters
[in] aInstance
The OpenThread instance.
[in] aEnabled
Whether to enable or disable the Ephemeral Key Manager.

otBorderAgentEphemeralKeyStart

otError otBorderAgentEphemeralKeyStart(
  otInstance *aInstance,
  const char *aKeyString,
  uint32_t aTimeout,
  uint16_t aUdpPort
)

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 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).

Details
Parameters
[in] aInstance
The OpenThread instance.
[in] aKeyString
The ephemeral key.
[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.
[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.
Return Values
OT_ERROR_NONE
Successfully started using the ephemeral key.
OT_ERROR_INVALID_STATE
A previously set ephemeral key is still in use or the feature is disabled.
OT_ERROR_INVALID_ARGS
The given aKeyString is not valid.
OT_ERROR_FAILED
Failed to start (e.g., it could not bind to the given UDP port).

otBorderAgentEphemeralKeyStateToString

const char * otBorderAgentEphemeralKeyStateToString(
  otBorderAgentEphemeralKeyState aState
)

Converts a given otBorderAgentEphemeralKeyState to a human-readable string.

Details
Parameters
[in] aState
The state to convert.
Returns
Human-readable string corresponding to aState.

otBorderAgentEphemeralKeyStop

void otBorderAgentEphemeralKeyStop(
  otInstance *aInstance
)

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.

Details
Parameters
[in] aInstance
The OpenThread instance.

otBorderAgentGetCounters

const otBorderAgentCounters * otBorderAgentGetCounters(
  otInstance *aInstance
)

Gets the counters of the Thread Border Agent.

Details
Parameters
[in] aInstance
A pointer to an OpenThread instance.
Returns
A pointer to the Border Agent counters.

otBorderAgentGetId

otError otBorderAgentGetId(
  otInstance *aInstance,
  otBorderAgentId *aId
)

Gets the randomly generated Border Agent ID.

Requires OPENTHREAD_CONFIG_BORDER_AGENT_ID_ENABLE.

The ID is saved in persistent storage and survives reboots. The typical use case of the ID is to be published in the MeshCoP mDNS service as the id TXT value for the client to identify this Border Router/Agent device.

Details
Parameters
[in] aInstance
A pointer to an OpenThread instance.
[out] aId
A pointer to buffer to receive the ID.
Return Values
OT_ERROR_NONE
If successfully retrieved the Border Agent ID.
...
If failed to retrieve the Border Agent ID.
See also:
otBorderAgentSetId

otBorderAgentGetNextSessionInfo

otError otBorderAgentGetNextSessionInfo(
  otBorderAgentSessionIterator *aIterator,
  otBorderAgentSessionInfo *aSessionInfo
)

Retrieves the next Border Agent session information.

Details
Parameters
[in] aIterator
The iterator to use.
[out] aSessionInfo
A pointer to an otBorderAgentSessionInfo to populate.
Return Values
OT_ERROR_NONE
Successfully retrieved the next session info.
OT_ERROR_NOT_FOUND
No more sessions are available. The end of the list has been reached.

otBorderAgentGetUdpPort

uint16_t otBorderAgentGetUdpPort(
  otInstance *aInstance
)

Gets the UDP port of the Thread Border Agent service.

Details
Parameters
[in] aInstance
A pointer to an OpenThread instance.
Returns
UDP port of the Border Agent.

otBorderAgentInitSessionIterator

void otBorderAgentInitSessionIterator(
  otInstance *aInstance,
  otBorderAgentSessionIterator *aIterator
)

Initializes a session iterator.

An iterator MUST be initialized before being used in otBorderAgentGetNextSessionInfo(). A previously initialized iterator can be re-initialized to start from the beginning of the session list.

Details
Parameters
[in] aInstance
A pointer to an OpenThread instance.
[in] aIterator
The iterator to initialize.

otBorderAgentIsActive

bool otBorderAgentIsActive(
  otInstance *aInstance
)

Indicates whether or not the Border Agent service is active and running.

While the Border Agent is active, external commissioner candidates can try to connect to and establish secure DTLS sessions with the Border Agent using PSKc. A connected commissioner can then petition to become a full commissioner.

If OPENTHREAD_CONFIG_BORDER_AGENT_EPHEMERAL_KEY_ENABLE is enabled, independent and separate DTLS transport and sessions are used for the ephemeral key. Therefore, the ephemeral key and Border Agent service can be enabled and used in parallel.

Details
Parameters
[in] aInstance
A pointer to an OpenThread instance.
Return Values
TRUE
The Border Agent is active.
FALSE
The Border Agent is not active.

otBorderAgentSetId

otError otBorderAgentSetId(
  otInstance *aInstance,
  const otBorderAgentId *aId
)

Sets the Border Agent ID.

Requires OPENTHREAD_CONFIG_BORDER_AGENT_ID_ENABLE.

The Border Agent ID will be saved in persistent storage and survive reboots. It's required to set the ID only once after factory reset. If the ID has never been set by calling this function, a random ID will be generated and returned when otBorderAgentGetId is called.

Details
Parameters
[in] aInstance
A pointer to an OpenThread instance.
[out] aId
A pointer to the Border Agent ID.
Return Values
OT_ERROR_NONE
If successfully set the Border Agent ID.
...
If failed to set the Border Agent ID.
See also:
otBorderAgentGetId

otBorderAgentSetMeshCoPServiceChangedCallback

void otBorderAgentSetMeshCoPServiceChangedCallback(
  otInstance *aInstance,
  otBorderAgentMeshCoPServiceChangedCallback aCallback,
  void *aContext
)

Sets the callback function used by the Border Agent to notify of any changes to the state of the MeshCoP service.

The callback is invoked when the 'Is Active' state of the Border Agent or the MeshCoP service TXT data values change. For example, it is invoked when the network name or the extended PAN ID changes and passes the updated encoded TXT data to the application layer.

This callback is invoked once right after this API is called to provide initial states of the MeshCoP service.

Details
Parameters
[in] aInstance
A pointer to an OpenThread instance.
[in] aCallback
The callback to be invoked when there are any changes of the MeshCoP service.
[in] aContext
A pointer to application-specific context.

Macros

OT_BORDER_AGENT_DEFAULT_EPHEMERAL_KEY_TIMEOUT

 OT_BORDER_AGENT_DEFAULT_EPHEMERAL_KEY_TIMEOUT (2 * 60 * 1000u)

Default ephemeral key timeout interval in milliseconds.

OT_BORDER_AGENT_ID_LENGTH

 OT_BORDER_AGENT_ID_LENGTH (16)

The length of Border Agent/Router ID in bytes.

OT_BORDER_AGENT_MAX_EPHEMERAL_KEY_LENGTH

 OT_BORDER_AGENT_MAX_EPHEMERAL_KEY_LENGTH (32)

Maximum length of the ephemeral key string.

OT_BORDER_AGENT_MAX_EPHEMERAL_KEY_TIMEOUT

 OT_BORDER_AGENT_MAX_EPHEMERAL_KEY_TIMEOUT (10 * 60 * 1000u)

Maximum ephemeral key timeout interval in milliseconds.

OT_BORDER_AGENT_MIN_EPHEMERAL_KEY_LENGTH

 OT_BORDER_AGENT_MIN_EPHEMERAL_KEY_LENGTH (6)

Minimum length of the ephemeral key string.

Resources

OpenThread API Reference topics originate from the source code, available on GitHub. For more information, or to contribute to our documentation, refer to Resources.