Function openthread_sys::otBorderAgentSetEphemeralKey

source ·

pub unsafe extern "C" fn otBorderAgentSetEphemeralKey(
    aInstance: *mut otInstance,
    aKeyString: *const c_char,
    aTimeout: u32,
    aUdpPort: u16
) -> otError

Expand description

Sets the ephemeral key for a given timeout duration.

Requires OPENTHREAD_CONFIG_BORDER_AGENT_EPHEMERAL_KEY_ENABLE.

The ephemeral key can be set when the Border Agent is already running and is not currently connected to any external commissioner (i.e., it is in OT_BORDER_AGENT_STATE_STARTED state). Otherwise OT_ERROR_INVALID_STATE is returned.

The given @p aKeyString is directly used as the ephemeral PSK (excluding the trailing null \0 character ). The @p aKeyString length must be between OT_BORDER_AGENT_MIN_EPHEMERAL_KEY_LENGTH and OT_BORDER_AGENT_MAX_EPHEMERAL_KEY_LENGTH, inclusive.

Setting the ephemeral key again before a previously set key has timed out will replace the previously set key and reset the timeout.

While the timeout interval is in effect, the ephemeral key can be used only once by an external commissioner to connect. Once the commissioner disconnects, the ephemeral key is cleared, and the Border Agent reverts to using PSKc.

@param[in] aInstance The OpenThread instance. @param[in] aKeyString The ephemeral key string (used as PSK excluding the trailing null \0 character). @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 will be used. If the given timeout value is larger than OT_BORDER_AGENT_MAX_EPHEMERAL_KEY_TIMEOUT, the max value OT_BORDER_AGENT_MAX_EPHEMERAL_KEY_TIMEOUT will be used instead. @param[in] aUdpPort The UDP port to use with ephemeral key. If zero, an ephemeral port will be used. otBorderAgentGetUdpPort() will return the current UDP port being used.

@retval OT_ERROR_NONE Successfully set the ephemeral key. @retval OT_ERROR_INVALID_STATE Border Agent is not running or it is connected to an external commissioner. @retval OT_ERROR_INVALID_ARGS The given @p aKeyString is not valid (too short or too long). @retval OT_ERROR_FAILED Failed to set the key (e.g., could not bind to UDP port).