Border Agent#

otBorderAgentEphemeralKeyState#

otBorderAgentEphemeralKeyState

Represents Border Agent's Ephemeral Key Manager state.

otBorderAgentId#

typedef struct otBorderAgentId otBorderAgentId

Represents a Border Agent Identifier.

otBorderAgentCounters#

typedef struct otBorderAgentCounters otBorderAgentCounters

Defines Border Agent counters.

The mEpskc related counters require OPENTHREAD_CONFIG_BORDER_AGENT_EPHEMERAL_KEY_ENABLE.

otBorderAgentEphemeralKeyState#

typedef enum otBorderAgentEphemeralKeyState otBorderAgentEphemeralKeyState

Represents Border Agent's Ephemeral Key Manager state.

otBorderAgentEphemeralKeyCallback#

typedef void(* otBorderAgentEphemeralKeyCallback) (void *aContext) )(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.

otBorderAgentGetCounters#

const otBorderAgentCounters * otBorderAgentGetCounters (otInstance * aInstance)

Gets the counters of the Thread Border Agent.

Returns

• A pointer to the Border Agent counters.

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.

otBorderAgentGetUdpPort#

uint16_t otBorderAgentGetUdpPort (otInstance * aInstance)

Gets the UDP port of the Thread Border Agent service.

Returns

• UDP port of the Border Agent.

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.

See Also

• otBorderAgentSetId

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.

See Also

• otBorderAgentGetId

otBorderAgentEphemeralKeyGetState#

otBorderAgentEphemeralKeyState otBorderAgentEphemeralKeyGetState (otInstance * aInstance)

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

Requires OPENTHREAD_CONFIG_BORDER_AGENT_EPHEMERAL_KEY_ENABLE.

Returns

• The current state of Ephemeral Key Manager.

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

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

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.

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.

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.

otBorderAgentEphemeralKeyStateToString#

const char * otBorderAgentEphemeralKeyStateToString (otBorderAgentEphemeralKeyState aState)

Converts a given otBorderAgentEphemeralKeyState to a human-readable string.

Returns

• Human-readable string corresponding to aState.