openthread_sys

Function otBorderAgentEphemeralKeyStart

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

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