sdk/fidl/fuchsia.lowpan.thread/epskc.fidl

// Copyright 2025 The Fuchsia Authors. All rights reserved.
// Use of this source code is governed by a BSD-style license that can be
// found in the LICENSE file.
library fuchsia.lowpan.thread;

using fuchsia.lowpan;
using zx;

/// Maximum length of the ephemeral key used by OpenThread Border Agent.
/// See https://openthread.io/reference/group/api-border-agent for more details.
@available(added=NEXT)
const OT_BORDER_AGENT_MAX_EPHEMERAL_KEY_LENGTH uint32 = 32;

/// Protocol for connecting to [`Epskc`] on a LoWPAN device.
@discoverable
@available(added=NEXT)
open protocol EpskcConnector {
    /// Connects to the [`Epskc`] protocol on the
    /// named LoWPAN device.
    ///
    /// The name of the interface can be learned by calling
    /// [`fuchsia.lowpan/Lookup.GetDevices`].
    ///
    /// If there is an error in processing this request
    /// the given channel is closed and an epitaph code used
    /// to describe the reason for the failure:
    ///
    /// * `ZX_ERR_INVALID_ARGUMENT`: The given interface name
    ///   was not formatted correctly or otherwise invalid.
    /// * `ZX_ERR_NOT_FOUND`: No interface was found with the
    ///   given name.
    /// * `ZX_ERR_NOT_SUPPORTED`: The interface exists but
    ///   does not support this protocol.
    Connect(resource struct {
        name fuchsia.lowpan.InterfaceName;
        server_end server_end:Epskc;
    });
};

/// ePSKc configuration protocol
///
/// This allows callers to interact with the Thread stack's ePSKc functionality
/// to produce or invalidate ephemeral keys.
@available(added=NEXT)
open protocol Epskc {
    /// Starts the ephemeral key handler.
    ///
    /// The ePSKc functionality must first be enabled via
    /// fuchsia.lowpan.thread/FeatureConnector.
    ///
    /// The lifetime is in units of milliseconds.
    ///
    /// From OpenThread:
    ///
    /// 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.
    ///
    /// The maximum ephemeral key lifetime is 10 minutes.
    ///
    /// If a lifetime of 0 is provided, OpenThread will use its default lifetime
    /// of 2 minutes.
    ///
    /// If the lifetime 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 lifetime has not yet expired).
    ///
    /// * `ZX_ERR_INVALID_ARGS`: The specified lifetime is greater than allowed.
    /// * `ZX_ERR_BAD_STATE`: The ePSKc functionality has not been enabled.
    /// * `ZX_ERR_INTERNAL`: There was a failure in generating the ephemeral key.`
    flexible StartEphemeralKey(struct {
        lifetime uint32;
    }) -> (struct {
        key vector<byte>:OT_BORDER_AGENT_MAX_EPHEMERAL_KEY_LENGTH;
    }) error zx.Status;

    /// Stops the ephemeral key use.
    ///
    /// Existing sessions are terminated if retain_active_session is false.
    /// If retain_active_session is true and there is an ongoing session, the
    /// ephemeral key is not stopped.
    ///
    /// The ePSKc functionality must first be enabled via
    /// fuchsia.lowpan.thread/FeatureConnector.
    ///
    /// * `ZX_ERR_BAD_STATE`: The ePSKc functionality has not been enabled or
    ///   `retain_active_session` is true and there is an active session.
    flexible StopEphemeralKey(struct {
        retain_active_session bool;
    }) -> () error zx.Status;
};