[border-agent] introduce BorderAgent::EphemeralKeyManager (openthre…

…ad#11166)

This commit introduces the `BorderAgent::EphemeralKeyManager` class,
which manages the use of the ephemeral key by the Border Agent.

The `EphemeralKeyManager` uses its own DTLS transport and CoAP secure
sessions. This allows the `EphemeralKeyManager` and the `BorderAgent`
service (which uses PSKc) to be enabled and used in parallel.
Previously, a single transport and session was shared between these
functions, requiring the normal BA service (with PSKc) to be stopped
before the ephemeral key could be used.

This is a fundamental change and improvement to the ephemeral key and
Border Agent functionality. Therefore some existing `otBorderAgent`
APIs need to be modified. For example, `otBorderAgentGetState()`,
which returned the Border Agent state to indicate whether there were
any active sessions, is no longer meaningful, as different
sessions/transports are now used for PSKc and ephemeral key, and
there can be multiple sessions. This commit intentionally renames and
changes the `otBorderAgent` public APIs, specifically all those
related to ephemeral key use, to highlight the fundamental change in
behavior. While this can cause backward incompatibility, it requires
app layer code that used the previous APIs to be updated to take into
account the new behavior.

This commit also updates `nexus/test_border_agent`, adding new tests
to validate the new behavior (e.g., BA service and ephemeral key
parallel sessions). It also includes and validates the Border Agent
counter updates under different scenarios (this enhances and replaces
`test_ephemeral_key_counters.py`).

include/openthread/instance.h

@@ -52,7 +52,7 @@ extern "C" {
  *
  * @note This number versions both OpenThread platform and user APIs.
  */
-#define OPENTHREAD_API_VERSION (474)
+#define OPENTHREAD_API_VERSION (475)
 
 /**
  * @addtogroup api-instance

src/cli/README.md

@@ -364,7 +364,7 @@ Show current Border Agent information.
 
 ### ba port
 
-Print border agent service port.
+Print Border Agent's service port.
 
 ```bash
 > ba port
@@ -374,135 +374,156 @@ Done
 
 ### ba state
 
-Print border agent state.
+Print Border Agent's state.
 
 Possible states are
 
-- `Stopped` : Border Agent is stopped.
-- `Started` : Border Agent is running with no active connection with external commissioner.
-- `Active` : Border Agent is running and is connected with an external commissioner.
+- `Active`: Border Agent is active.
+- `Inactive`: Border Agent is not active.
 
 ```bash
 > ba state
-Started
-Done
-```
-
-### ba disconnect
-
-Disconnects border agent from any active secure sessions.
-
-```bash
-> ba disconnect
+Active
 Done
 ```
 
 ### ba ephemeralkey
 
-Indicates if an ephemeral key is active.
+Print the Border Agent's Ephemeral Key Manager state.
 
 Requires `OPENTHREAD_CONFIG_BORDER_AGENT_EPHEMERAL_KEY_ENABLE`.
 
+Possible states are
+
+- `Disabled`: Ephemeral Key Manager is disabled.
+- `Stopped`: Enabled but no key is in use (not yet set or started).
+- `Started`: Ephemeral key is set. Listening to accept secure connections from commissioner candidates.
+- `Connected`: Secure session is established with an external commissioner candidate. Not yet accepted as full commissioner.
+- `Accepted`: Secure session is established and external candidate is accepted as full commissioner.
+
 ```bash
 > ba ephemeralkey
-inactive
+Stopped
 Done
 
-> ba ephemeralkey set Z10X20g3J15w1000P60m16 1000
+> ba ephemeralkey start Z10X20g3J15w1000P60m16 1000
 Done
 
 > ba ephemeralkey
-active
+Started
 Done
 ```
 
-### ba ephemeralkey set \<keystring\> \[timeout\] \[port\]
+### ba ephemeralkey enable
 
-Sets the ephemeral key for a given timeout duration.
+Enables the Border agent's Ephemeral Key Manager.
 
 Requires `OPENTHREAD_CONFIG_BORDER_AGENT_EPHEMERAL_KEY_ENABLE`.
 
-The ephemeral key can be set when Border Agent is already running and is not currently connected to any external commissioner (i.e., `ba state` gives `Started`).
-
-The `keystring` string is directly used as the ephemeral PSK (excluding the trailing null `\0` character). Its length MUST be between 6 and 32, inclusive.
-
-The `timeout` is in milliseconds. If not provided or set to zero, the default value of 2 minutes will be used. If the timeout value is larger than 10 minutes, the 10 minutes timeout value will be used instead.
+```bash
+> ba ephemeralkey enable
+Done
+```
 
-The `port` specifies the UDP port to use with the ephemeral key. If UDP port is zero or is not provided, an ephemeral port will be used. `ba port` will give the current UDP port in use by the Border Agent.
+### ba ephemeralkey disable
 
-Setting the ephemeral key again before a previously set one is timed out, will replace the previous one.
+Disables the Border Agent's Ephemeral Key Manager.
 
-During the timeout interval, the ephemeral key can be used only once by an external commissioner to establish a connection. After the commissioner disconnects, the ephemeral key is cleared, and the Border Agent reverts to using PSKc. If the timeout expires while a commissioner is still connected, the session will be terminated, and the Border Agent will cease using the ephemeral key and revert to PSKc.
+Requires `OPENTHREAD_CONFIG_BORDER_AGENT_EPHEMERAL_KEY_ENABLE`.
 
 ```bash
-> ba ephemeralkey set Z10X20g3J15w1000P60m16 5000 1234
+> ba ephemeralkey disable
+Done
+
+> ba ephemeralkey
+Disabled
 Done
 ```
 
-### ba ephemeralkey clear
+### ba ephemeralkey start \<keystring\> \[timeout\] \[port\]
 
-Cancels the ephemeral key in use if any.
+Starts using an ephemeral key for a given timeout duration.
 
 Requires `OPENTHREAD_CONFIG_BORDER_AGENT_EPHEMERAL_KEY_ENABLE`.
 
-Can be used to cancel a previously set ephemeral key before it is used or times out. If the Border Agent is not running or there is no ephemeral key in use, calling this function has no effect.
+An ephemeral key can only be set when current state is `Stopped`, i.e., it is enabled but not yet started. 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 using `ba ephemeralkey stop` before starting with a new key.
 
-If a commissioner is connected using the ephemeral key and is currently active, calling this method does not change its state. In this case the `ba ephemeralkey` will continue to return `active` until the commissioner disconnects.
+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.
 
-```bash
-> ba ephemeralkey clear
-Done
-```
+The `keystring` string is directly used as the ephemeral PSK (excluding the trailing null `\0` character). Its length MUST be between 6 and 32, inclusive.
 
-### ba ephemeralkey callback enable
+The `timeout` is in milliseconds. If not provided or set to zero, the default value of 2 minutes will be used. If the timeout value is larger than 10 minutes, the 10 minutes timeout value will be used instead.
+
+The `port` specifies the UDP port to use with the ephemeral key. If UDP port is zero or is not provided, an ephemeral port will be used. `ba ephemeralkey port` will give the current UDP port in use.
 
-Enables callback from Border Agent for ephemeral key state changes.
+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).
 
 ```bash
-> ba ephemeralkey callback enable
+> ba ephemeralkey start Z10X20g3J15w1000P60m16 5000 1234
 Done
 
-> ba ephemeralkey set W10X12 5000 49155
+> ba ephemeralkey
+Started
 Done
 
-BorderAgent callback: Ephemeral key active, port:49155
-BorderAgent callback: Ephemeral key inactive
+> ba ephemeralkey port
+1234
+Done
 ```
 
-### ba ephemeralkey callback disable
+### ba ephemeralkey stop
 
-Disables callback from Border Agent for ephemeral key state changes.
+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.
 
 ```bash
-> ba ephemeralkey callback disable
+> ba ephemeralkey stop
 Done
 ```
 
-### ba ephemeralkey feature
+### ba ephemeralkey port
+
+Print the port number in use by Ephemeral Key Manager.
 
-Displays if the Ephemeral Key feature is enabled. Note that this indicates whether the ephemeral key feature is ready to use, instead of whether an ephemeral key is active.
+Requires `OPENTHREAD_CONFIG_BORDER_AGENT_EPHEMERAL_KEY_ENABLE`.
 
 ```bash
-> ba ephemeralkey feature
-Enabled
+> ba ephemeralkey port
+1234
 Done
 ```
 
-### ba ephemeralkey feature enable
+### ba ephemeralkey callback enable
 
-Enables the Ephemeral Key feature.
+Enables callback from Border Agent to be notified of state changes of Border Agent's Ephemeral Key Manager.
+
+Requires `OPENTHREAD_CONFIG_BORDER_AGENT_EPHEMERAL_KEY_ENABLE`.
 
 ```bash
-> ba ephemeralkey feature enable
+> ba ephemeralkey callback enable
 Done
+
+> ba ephemeralkey start W10X120 5000 49155
+Done
+
+BorderAgentEphemeralKey callback - state:Started
+BorderAgentEphemeralKey callback - state:Connected
+BorderAgentEphemeralKey callback - state:Stopped
 ```
 
-### ba ephemeralkey feature disable
+### ba ephemeralkey callback disable
 
-Disables the Ephemeral Key feature.
+Disables callback from Border Agent to be notified of state changes of Border Agent's Ephemeral Key Manager.
+
+Requires `OPENTHREAD_CONFIG_BORDER_AGENT_EPHEMERAL_KEY_ENABLE`.
 
 ```bash
-> ba ephemeralkey feature disable
+> ba ephemeralkey callback disable
 Done
 ```