mod followups;
mod interactions;
mod outbox;
mod serve;
mod driver;
pub use driver::Mdns;
use core::cell::RefCell;
use heapless::{Deque, Vec};
use crate::acl::{AclAccess, SubjectDescriptor};
use crate::clusters::access_control::AccessControl as AccessControlCluster;
use crate::clusters::general_commissioning::GeneralCommissioning;
use crate::clusters::group_key_management::GroupTable;
use crate::clusters::operational_credentials::{OperationalCredentials, max_nocs_len};
use crate::config::{Config, DefaultConfig, MAX_UDP_MESSAGE, MAX_UDP_PAYLOAD};
use crate::crypto::{KeyStore, Spake2pVerifierData, SymmetricKey};
use crate::dm::events::{EventSource, EventStore, NewEvent, RecordError};
use crate::dm::{DataVersionSource, DataVersions, Node};
use crate::error::{Error, Result};
use crate::exchange::{ExchangeKey, Role};
use crate::fabric::CompressedFabricId;
use crate::group::{GroupKeySet, GroupKeys, PeerTable};
use crate::im::{
ClusterHandler, ClusterId, Dispatcher, EndpointId, InteractionContext, Status,
SubscriptionTable,
};
use crate::messaging::{Due, Evicted, Messaging, Received};
use crate::msg::{FabricIndex, GroupId, NodeId, ProtocolId, SessionId};
use crate::platform::{Duration, Instant, Peer, PeerAddr, Rng};
use crate::sc::{Channel, ChannelBuffers, ChannelContext, PbkdfParameters};
use crate::session::SessionKind;
use interactions::Interactions;
use outbox::{Outbox, Resend};
pub const SCRATCH: usize = max_nocs_len(DefaultConfig::FABRICS);
const REPORT_LIMIT: usize = 24;
pub const SUBSCRIPTIONS: usize = 15;
pub const SUBSCRIPTION_PATHS: usize = 3;
pub type Subscriptions<C> = SubscriptionTable<C, SUBSCRIPTIONS, SUBSCRIPTION_PATHS>;
pub const PASE_ABANDON_GRACE: Duration = Duration::from_secs(30);
mod sealed {
pub trait Sealed {}
}
pub trait AccessList: sealed::Sealed {
type Access<'b>: crate::im::AccessControl
where
Self: 'b;
fn access<'b>(&'b self, node: Node<'b>, subject: &'b SubjectDescriptor) -> Self::Access<'b>;
fn grant_admin(
&self,
fabric: FabricIndex,
subject: NodeId,
ctx: &InteractionContext<'_>,
) -> Result<()>;
fn drain_changes(&self, each: &mut dyn FnMut(FabricIndex, Result<&[u8]>));
}
impl<C: Config, const N: usize, const S: usize, const T: usize> sealed::Sealed
for AccessControlCluster<'_, C, N, S, T>
{
}
impl<C: Config, const N: usize, const S: usize, const T: usize> AccessList
for AccessControlCluster<'_, C, N, S, T>
{
type Access<'b>
= AclAccess<'b, C, N, S, T>
where
Self: 'b;
fn access<'b>(&'b self, node: Node<'b>, subject: &'b SubjectDescriptor) -> Self::Access<'b> {
AclAccess::new(self.acl(), node, subject)
}
fn grant_admin(
&self,
fabric: FabricIndex,
subject: NodeId,
ctx: &InteractionContext<'_>,
) -> Result<()> {
self.add_admin_for_fabric(fabric, subject, ctx)
}
fn drain_changes(&self, each: &mut dyn FnMut(FabricIndex, Result<&[u8]>)) {
for change in self.take_changes() {
let mut buf = [0u8; crate::dm::events::EVENT_DATA_MAX];
let mut w =
crate::tlv::TlvWriter::new_in(&mut buf, crate::tlv::ContainerKind::Structure);
let encoded = change
.encode(&mut w, crate::tlv::Tag::Context(7))
.and_then(|()| w.finish());
each(change.fabric_index, encoded);
}
}
}
pub trait GroupKeyStore: sealed::Sealed {
fn install_ipk(
&self,
fabric: FabricIndex,
ipk: SymmetricKey,
) -> core::result::Result<(), Status>;
fn open<'b>(
&self,
buf: &'b mut [u8],
from: PeerAddr,
peers: &mut GroupPeers,
compressed: &dyn Fn(FabricIndex) -> Option<CompressedFabricId>,
scratch: &mut [u8],
) -> Result<crate::group::wire::Received<'b>>;
}
pub type GroupPeers = PeerTable<4, 2>;
impl<C: Config, const K: usize, const M: usize> sealed::Sealed for RefCell<GroupKeys<C, K, M>> {}
impl<C: Config, const K: usize, const M: usize> GroupKeyStore for RefCell<GroupKeys<C, K, M>> {
fn install_ipk(
&self,
fabric: FabricIndex,
ipk: SymmetricKey,
) -> core::result::Result<(), Status> {
let set = GroupKeySet::single(
fabric,
crate::group::IPK_KEY_SET,
crate::group::GroupKeySecurityPolicy::TrustFirst,
ipk,
0,
);
self.borrow_mut().write_key_set(set)
}
fn open<'b>(
&self,
buf: &'b mut [u8],
from: PeerAddr,
peers: &mut GroupPeers,
compressed: &dyn Fn(FabricIndex) -> Option<CompressedFabricId>,
scratch: &mut [u8],
) -> Result<crate::group::wire::Received<'b>> {
crate::group::wire::receive(buf, from, &self.borrow(), peers, compressed, scratch)
}
}
pub trait EventLog: sealed::Sealed {
fn record(&self, event: &NewEvent<'_>) -> core::result::Result<u64, RecordError>;
fn source(&self) -> &dyn EventSource;
}
impl<const A: usize, const B: usize, const D: usize> sealed::Sealed
for RefCell<EventStore<A, B, D>>
{
}
impl<const A: usize, const B: usize, const D: usize> EventLog for RefCell<EventStore<A, B, D>> {
fn record(&self, event: &NewEvent<'_>) -> core::result::Result<u64, RecordError> {
self.borrow_mut().record(event)
}
fn source(&self) -> &dyn EventSource {
self
}
}
pub trait ChangeLog: DataVersionSource + sealed::Sealed {
fn drain(&self, each: &mut dyn FnMut(EndpointId, ClusterId));
}
impl<const N: usize> sealed::Sealed for DataVersions<N> {}
impl<const N: usize> ChangeLog for DataVersions<N> {
fn drain(&self, each: &mut dyn FnMut(EndpointId, ClusterId)) {
for (endpoint, cluster) in self.drain_changes() {
each(endpoint, cluster);
}
}
}
pub struct Device<'a, C, K, G, H, Ac, Gk, Ev, V, const F: usize>
where
C: Config,
K: KeyStore,
G: Rng,
H: ClusterHandler,
Ac: AccessList,
Gk: GroupKeyStore,
Ev: EventLog,
V: ChangeLog,
{
pub node: Node<'a>,
pub handler: &'a H,
pub credentials: &'a OperationalCredentials<'a, C, K, G, F>,
pub commissioning: &'a GeneralCommissioning<'a>,
pub access_control: &'a Ac,
pub group_keys: &'a Gk,
pub events: &'a Ev,
pub versions: &'a V,
pub verifier: &'a Spake2pVerifierData,
pub parameters: &'a PbkdfParameters,
pub memberships: Option<&'a dyn GroupTable>,
}
impl<C, K, G, H, Ac, Gk, Ev, V, const F: usize> core::fmt::Debug
for Device<'_, C, K, G, H, Ac, Gk, Ev, V, F>
where
C: Config,
K: KeyStore,
G: Rng,
H: ClusterHandler,
Ac: AccessList,
Gk: GroupKeyStore,
Ev: EventLog,
V: ChangeLog,
{
fn fmt(&self, f: &mut core::fmt::Formatter<'_>) -> core::fmt::Result {
f.debug_struct("Device")
.field("node", &self.node)
.field("groups", &self.memberships.is_some())
.finish_non_exhaustive()
}
}
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
#[non_exhaustive]
pub enum Notice {
Dropped(Error),
Refused(Error),
Established {
session: SessionId,
kind: SessionKind,
fabric: FabricIndex,
},
SessionClosed {
session: SessionId,
subscriptions: usize,
},
Evicted {
session: SessionId,
},
Subscribed {
id: u32,
max_interval_s: u16,
},
Granted {
id: u32,
},
ReportFailed {
id: u32,
error: Error,
},
FabricAdded(FabricIndex),
FabricUpdated(FabricIndex),
FabricRemoved(FabricIndex),
RolledBack,
Commissioned(FabricIndex),
WindowOpened,
ChannelReleased,
Groupcast(GroupId),
EventLost(Option<RecordError>),
OutboxFull,
Abandoned(ExchangeKey),
}
#[derive(Debug)]
struct Im<C: Config, const I: usize> {
dispatcher: Dispatcher<4>,
interactions: Interactions<I>,
subscriptions: Subscriptions<C>,
reporting: Vec<(u32, ExchangeKey), SUBSCRIPTIONS>,
backoff: Vec<(u32, Instant), SUBSCRIPTIONS>,
}
#[derive(Debug)]
struct Buffers<const B: usize> {
payload: [u8; MAX_UDP_PAYLOAD],
scratch: [u8; B],
frame: [u8; MAX_UDP_MESSAGE],
wire: [u8; MAX_UDP_MESSAGE],
evict: [u8; MAX_UDP_MESSAGE],
}
#[derive(Debug, Clone, Copy, Default)]
struct PaseProgress {
established_at: Option<Instant>,
armed_seen: bool,
}
#[derive(Debug)]
pub struct Runtime<
C: Config,
const S: usize = 16,
const X: usize = 64,
const I: usize = 8,
const R: usize = 4,
const Q: usize = 4,
const B: usize = SCRATCH,
> {
stack: Messaging<C, S, X>,
channel: Channel,
im: Im<C, I>,
outbox: Outbox<Q>,
resend: Resend<R>,
group_peers: GroupPeers,
notices: Deque<Notice, 16>,
window_was_open: bool,
pase: PaseProgress,
buf: Buffers<B>,
}
impl<
C: Config,
const S: usize,
const X: usize,
const I: usize,
const R: usize,
const Q: usize,
const B: usize,
> Runtime<C, S, X, I, R, Q, B>
{
pub fn new(rng: &impl Rng) -> Result<Self> {
const {
assert!(
B >= max_nocs_len(C::FABRICS),
"the scratch must hold a non-fabric-filtered NOCs read for every fabric"
);
assert!(Q > 1, "one input can owe a reply and an eviction report");
}
Ok(Self {
stack: Messaging::new(rng.next_u16()? | 1, rng.next_u16()?, rng.next_u32()?),
channel: Channel::new(),
im: Im {
dispatcher: Dispatcher::new(1),
interactions: Interactions::new(),
subscriptions: SubscriptionTable::new(),
reporting: Vec::new(),
backoff: Vec::new(),
},
outbox: Outbox::new(),
resend: Resend::new(),
group_peers: PeerTable::new(),
notices: Deque::new(),
window_was_open: false,
pase: PaseProgress::default(),
buf: Buffers {
payload: [0; MAX_UDP_PAYLOAD],
scratch: [0; B],
frame: [0; MAX_UDP_MESSAGE],
wire: [0; MAX_UDP_MESSAGE],
evict: [0; MAX_UDP_MESSAGE],
},
})
}
#[must_use]
pub fn with_max_paths_per_invoke(mut self, max: u16) -> Self {
self.im.dispatcher = Dispatcher::new(max);
self
}
#[must_use]
pub const fn messaging(&self) -> &Messaging<C, S, X> {
&self.stack
}
pub const fn messaging_mut(&mut self) -> &mut Messaging<C, S, X> {
&mut self.stack
}
#[must_use]
pub const fn subscriptions(&self) -> &Subscriptions<C> {
&self.im.subscriptions
}
#[must_use]
pub const fn channel(&self) -> &Channel {
&self.channel
}
pub fn transmit(&mut self) -> Option<(Peer, &[u8])> {
self.outbox.pop()
}
pub fn notice(&mut self) -> Option<Notice> {
self.notices.pop_front()
}
fn notify(&mut self, notice: Notice) {
#[cfg(feature = "log")]
log::debug!("{notice:?}");
#[cfg(all(feature = "defmt", not(feature = "log")))]
defmt::debug!("{}", defmt::Debug2Format(¬ice));
if self.notices.is_full() {
self.notices.pop_front();
}
let _ = self.notices.push_back(notice);
}
pub fn receive<K, G, H, Ac, Gk, Ev, V, const F: usize>(
&mut self,
device: &Device<'_, C, K, G, H, Ac, Gk, Ev, V, F>,
datagram: &mut [u8],
from: Peer,
now: Instant,
) where
K: KeyStore,
G: Rng,
H: ClusterHandler,
Ac: AccessList,
Gk: GroupKeyStore,
Ev: EventLog,
V: ChangeLog,
{
self.watch_window(device, now);
let received = match self.stack.receive(datagram, from, now) {
Ok(received) => received,
Err(e) => {
self.notify(Notice::Dropped(e));
return;
}
};
match received {
Received::Group { .. } => {
if let Peer::Udp(addr) = from {
self.groupcast(device, datagram, addr, now);
}
}
Received::Duplicate {
exchange,
needs_ack,
} => {
if needs_ack {
self.acknowledge(exchange, now);
}
}
Received::SessionClosed { session } => self.session_gone(session),
Received::Acknowledged { exchange } => {
if !self.stack.is_awaiting_ack(exchange) {
self.im.reporting.retain(|(_, on)| *on != exchange);
}
self.close_if_idle(exchange);
}
Received::Message {
exchange,
header,
payload,
..
} => self.message(
device,
exchange,
header.protocol,
header.opcode,
payload,
now,
),
}
self.drain_changes(device);
}
pub fn poll<K, G, H, Ac, Gk, Ev, V, const F: usize>(
&mut self,
device: &Device<'_, C, K, G, H, Ac, Gk, Ev, V, F>,
now: Instant,
) where
K: KeyStore,
G: Rng,
H: ClusterHandler,
Ac: AccessList,
Gk: GroupKeyStore,
Ev: EventLog,
V: ChangeLog,
{
self.watch_window(device, now);
if self.channel.deadline().is_some_and(|d| d <= now) {
self.channel.poll(now, device.commissioning.window);
}
self.expire_fail_safe(device, now);
self.drain_changes(device);
self.reports(device, now);
loop {
let randomness = random(device);
let Some(due) = self.stack.poll(now, randomness) else {
break;
};
match due {
Due::Acknowledge { exchange } => {
self.acknowledge(exchange, now);
if matches!(exchange.role, Role::Responder) {
self.close_if_idle(exchange);
}
}
Due::Retransmit { exchange, counter } => {
if let Some((peer, bytes)) = self.resend.find(exchange, counter)
&& !self.outbox.push(peer, bytes)
{
self.notify(Notice::OutboxFull);
}
}
Due::Abandoned { exchange } => {
self.im.reporting.retain(|(_, on)| *on != exchange);
self.im.interactions.forget(exchange);
self.resend.forget(exchange);
self.notify(Notice::Abandoned(exchange));
}
}
}
}
#[must_use]
pub fn next_deadline<K, G, H, Ac, Gk, Ev, V, const F: usize>(
&self,
device: &Device<'_, C, K, G, H, Ac, Gk, Ev, V, F>,
) -> Option<Instant>
where
K: KeyStore,
G: Rng,
H: ClusterHandler,
Ac: AccessList,
Gk: GroupKeyStore,
Ev: EventLog,
V: ChangeLog,
{
let reports = self
.im
.subscriptions
.iter()
.filter(|s| {
!self.im.interactions.priming(s.id)
&& !self.im.reporting.iter().any(|(id, _)| *id == s.id)
})
.map(|s| {
let at = s.next_deadline();
match self.im.backoff.iter().find(|(id, _)| *id == s.id) {
Some((_, retry)) => at.max(*retry),
None => at,
}
})
.min();
let pase_release = self
.pase
.established_at
.filter(|_| !self.pase.armed_seen)
.map(|at| at.saturating_add(PASE_ABANDON_GRACE));
[
self.stack.wake_at(),
self.channel.deadline(),
reports,
device.commissioning.fail_safe.borrow().next_deadline(),
device.commissioning.window.borrow().deadline(),
pase_release,
]
.into_iter()
.flatten()
.min()
}
fn message<K, G, H, Ac, Gk, Ev, V, const F: usize>(
&mut self,
device: &Device<'_, C, K, G, H, Ac, Gk, Ev, V, F>,
exchange: ExchangeKey,
protocol: ProtocolId,
opcode: u8,
body: &[u8],
now: Instant,
) where
K: KeyStore,
G: Rng,
H: ClusterHandler,
Ac: AccessList,
Gk: GroupKeyStore,
Ev: EventLog,
V: ChangeLog,
{
if protocol == ProtocolId::SECURE_CHANNEL {
self.secure_channel(device, exchange, opcode, body, now);
return;
}
if protocol != ProtocolId::INTERACTION_MODEL {
return;
}
if !self.stack.is_awaiting_ack(exchange) {
self.im.reporting.retain(|(_, on)| *on != exchange);
}
let reply = self.interaction(device, exchange, opcode, body, now);
let deferred = self.follow_up(device, exchange.session, now);
match reply {
Ok(Some((opcode, len))) => self.send(device, exchange, opcode, len, now),
Ok(None) => self.close_if_idle(exchange),
Err(e) => {
self.notify(Notice::Refused(e));
self.im.interactions.forget(exchange);
self.close_if_idle(exchange);
}
}
self.apply(deferred);
}
fn secure_channel<K, G, H, Ac, Gk, Ev, V, const F: usize>(
&mut self,
device: &Device<'_, C, K, G, H, Ac, Gk, Ev, V, F>,
exchange: ExchangeKey,
opcode: u8,
body: &[u8],
now: Instant,
) where
K: KeyStore,
G: Rng,
H: ClusterHandler,
Ac: AccessList,
Gk: GroupKeyStore,
Ev: EventLog,
V: ChangeLog,
{
let answered = {
let rng = device.credentials.rng.borrow();
let ctx = ChannelContext {
fabrics: device.credentials.fabrics,
keys: device.credentials.keys,
rng: &*rng,
window: device.commissioning.window,
verifier: device.verifier,
parameters: device.parameters,
now,
};
let mut buffers = ChannelBuffers {
reply: &mut self.buf.payload,
frame: &mut self.buf.frame,
evict: &mut self.buf.evict,
};
self.channel
.on_message(&mut self.stack, opcode, body, &ctx, &mut buffers)
};
let answered = match answered {
Ok(answered) => answered,
Err(e) => {
self.notify(Notice::Refused(e));
return;
}
};
if let Some(established) = &answered.established {
if established.kind == SessionKind::Pase {
self.pase = PaseProgress {
established_at: Some(now),
armed_seen: false,
};
}
self.notify(Notice::Established {
session: established.session,
kind: established.kind,
fabric: established.fabric,
});
}
if let Some((opcode, len)) = answered.reply {
self.send(device, exchange, opcode, len, now);
}
if let Some(evicted) = answered.evicted {
self.evicted(evicted);
}
}
fn send<K, G, H, Ac, Gk, Ev, V, const F: usize>(
&mut self,
device: &Device<'_, C, K, G, H, Ac, Gk, Ev, V, F>,
exchange: ExchangeKey,
opcode: u8,
len: usize,
now: Instant,
) where
K: KeyStore,
G: Rng,
H: ClusterHandler,
Ac: AccessList,
Gk: GroupKeyStore,
Ev: EventLog,
V: ChangeLog,
{
if let Err(e) = self.frame(exchange, opcode, len, random(device), now) {
self.notify(Notice::Refused(e));
}
}
fn frame(
&mut self,
exchange: ExchangeKey,
opcode: u8,
len: usize,
randomness: u32,
now: Instant,
) -> Result<()> {
let payload = self
.buf
.payload
.get(..len)
.ok_or(Error::new(crate::ErrorCode::BufferTooSmall))?;
let (n, counter) = self.stack.send(
exchange,
opcode,
true,
payload,
now,
randomness,
&mut self.buf.frame,
&mut self.buf.wire,
)?;
let peer = self
.stack
.peer(exchange)
.ok_or(Error::new(crate::ErrorCode::NoSession))?;
let bytes = self
.buf
.wire
.get(..n)
.ok_or(Error::new(crate::ErrorCode::BufferTooSmall))?;
let queued = self.outbox.push(peer, bytes);
self.resend.record(exchange, counter, peer, bytes);
if !queued {
self.notify(Notice::OutboxFull);
}
Ok(())
}
fn acknowledge(&mut self, exchange: ExchangeKey, now: Instant) {
let Ok(len) = self.stack.acknowledge(exchange, now, &mut self.buf.wire) else {
return;
};
if len == 0 {
return;
}
let (Some(peer), Some(bytes)) = (self.stack.peer(exchange), self.buf.wire.get(..len))
else {
return;
};
if !self.outbox.push(peer, bytes) {
self.notify(Notice::OutboxFull);
}
}
fn close_if_idle(&mut self, exchange: ExchangeKey) {
if !self.im.interactions.idle(exchange) {
return;
}
if self.im.reporting.iter().any(|(_, on)| *on == exchange) {
return;
}
if self.stack.is_awaiting_ack(exchange) {
return;
}
self.im.interactions.forget(exchange);
self.resend.forget(exchange);
self.stack.close(exchange);
}
fn session_gone(&mut self, session: SessionId) {
let dropped = self.im.subscriptions.remove_for_session(Some(session));
self.im.reporting.retain(|(_, on)| on.session != session);
self.im.interactions.forget_session(session);
self.resend.forget_session(session);
self.channel.closed(session);
if !self.channel.is_established() {
self.pase = PaseProgress::default();
}
self.notify(Notice::SessionClosed {
session,
subscriptions: dropped,
});
}
fn close_session(&mut self, session: SessionId) {
if self.stack.close_session(session) {
self.session_gone(session);
}
}
fn evicted(&mut self, evicted: Evicted) {
if let (Some(peer), Some(bytes)) = (evicted.peer, self.buf.evict.get(..evicted.len))
&& evicted.len > 0
&& !self.outbox.push(peer, bytes)
{
self.notify(Notice::OutboxFull);
}
self.notify(Notice::Evicted {
session: evicted.session,
});
self.session_gone(evicted.session);
}
fn watch_window<K, G, H, Ac, Gk, Ev, V, const F: usize>(
&mut self,
device: &Device<'_, C, K, G, H, Ac, Gk, Ev, V, F>,
now: Instant,
) where
K: KeyStore,
G: Rng,
H: ClusterHandler,
Ac: AccessList,
Gk: GroupKeyStore,
Ev: EventLog,
V: ChangeLog,
{
let open = device.commissioning.window.borrow().open(now).is_some();
if open && !self.window_was_open && !self.channel.is_established() {
self.channel.reopen();
self.pase = PaseProgress::default();
self.notify(Notice::WindowOpened);
}
self.window_was_open = open;
if !self.channel.is_established() {
return;
}
let armed = device.commissioning.fail_safe.borrow().armed(now).is_some();
if armed {
self.pase.armed_seen = true;
return;
}
let abandoned = self
.pase
.established_at
.is_some_and(|at| now.saturating_duration_since(at) >= PASE_ABANDON_GRACE);
if open && (self.pase.armed_seen || abandoned) {
self.channel.release();
self.pase = PaseProgress::default();
self.notify(Notice::ChannelReleased);
}
}
fn drain_changes<K, G, H, Ac, Gk, Ev, V, const F: usize>(
&mut self,
device: &Device<'_, C, K, G, H, Ac, Gk, Ev, V, F>,
) where
K: KeyStore,
G: Rng,
H: ClusterHandler,
Ac: AccessList,
Gk: GroupKeyStore,
Ev: EventLog,
V: ChangeLog,
{
let subscriptions = &mut self.im.subscriptions;
device.versions.drain(&mut |endpoint, cluster| {
subscriptions.note_cluster_change(endpoint, cluster);
});
}
}
fn random<C, K, G, H, Ac, Gk, Ev, V, const F: usize>(
device: &Device<'_, C, K, G, H, Ac, Gk, Ev, V, F>,
) -> u32
where
C: Config,
K: KeyStore,
G: Rng,
H: ClusterHandler,
Ac: AccessList,
Gk: GroupKeyStore,
Ev: EventLog,
V: ChangeLog,
{
device.credentials.rng.borrow().next_u32().unwrap_or(0)
}