pub struct InteractionContext<'a> {Show 14 fields
pub timed: bool,
pub fabric_index: Option<FabricIndex>,
pub large_messages: bool,
pub fabric_filtered: bool,
pub now: Instant,
pub vendor_id_verified: bool,
pub session: Option<SessionId>,
pub atomic: Option<ClaimRef<'a>>,
pub peer_node_id: Option<NodeId>,
pub attestation_challenge: Option<&'a SymmetricKey>,
pub privilege: Option<Privilege>,
pub group: Option<GroupId>,
pub event_filters: Option<&'a [u8]>,
pub data_version_filters: Option<&'a [u8]>,
}Expand description
What a handler needs to know about the interaction it is running inside.
Everything here is a fact about the session and action, not about the node: a cluster cannot read any of it for itself, and several of §11.18’s commands are wrong without it.
Fields§
§timed: boolWhether this action is part of a Timed transaction (§8.7.4).
The server has already refused anything that requires one and did not get it, so a handler needs this only if it wants to impose its own rule.
fabric_index: Option<FabricIndex>The fabric this interaction is scoped to, if any.
None on a PASE session during commissioning, which is why §8.8.2.3 step b.v makes a
fabric-scoped command UNSUPPORTED_ACCESS when there is no accessing fabric.
large_messages: boolWhether the transport can carry Large Messages (§7.7.5) — that is, whether it is TCP.
fabric_filtered: boolWhether the request asked for fabric filtering (§7.19.1.8.2).
A fabric-scoped list read with filtering on reports only the accessing fabric’s
entries; with it off, the full list, each entry carrying its FabricIndex global
field. ReadRequest and SubscribeRequest both carry the flag, and a cluster that
ignored it would either leak every administrator’s entries to one of them or hide from
a verifier the entries §6.4.10 requires it to read.
Defaults to false — the unfiltered, full-list reading, which is what
AttributePathIB’s own default means.
now: InstantMonotonic time, as of the moment the action started.
Handed to the handler rather than read by it, because a cluster is not the thing that owns a clock — and because a single action must see a single instant: §11.10.7.2’s fail-safe decides whether it is armed, re-arms it, and records progress, all of which must agree about when.
Defaults to Instant::ZERO, which is correct for a
node whose clusters have no deadlines — nothing consults it.
vendor_id_verified: boolWhether §6.4.10’s Vendor ID Verification has been run against this peer.
Only §11.25.6.1 consults it, and the default of false is the cautious one: a node that
assumed verification had happened would cross-sign an intermediate CA for an ecosystem
whose vendor nobody had checked.
session: Option<SessionId>Which secure session this action arrived on.
§11.18.6.7 scopes the CSR state to a session — “If no context or memory exists of a
prior CSRRequest command having been invoked in the same secure session as that
which is receiving this AddNOC or UpdateNOC invocation, then the Node SHALL … respond
with a StatusCode of MissingCsr”. Without this, one administrator’s CSRRequest could
be consumed by another’s AddNOC.
atomic: Option<ClaimRef<'a>>The atomic write this action is part of, if any (§7.15.3).
An attribute with the Atomic quality is writable only inside a claim covering it —
§7.15.3: “If a server receives a Write Request for an attribute that is not associated
with an Atomic Write State that is also associated with the client making the request,
the server SHALL return the error code INVALID_IN_STATE.” Derived by the caller from
AtomicWrites::find, the same way timed is derived
from the window table, and asserted here.
peer_node_id: Option<NodeId>The peer’s operational Node ID, when the session authenticated one (§6.6.6.3).
None on a PASE session, which has no node id — only a passcode. §6.6.6.1.3’s
Incoming Subject Descriptor is “deterministic based on both incoming message fields and
session metadata fields”, and this is the session’s half: it is what CASE proved,
never what a message claimed, which is the difference between an access decision and a
suggestion from the sender.
attestation_challenge: Option<&'a SymmetricKey>The session’s AttestationChallenge — the third key it derived (§4.14.2.6.2).
§11.18.4.7, §11.18.4.9 and §11.18.6.16 all sign over it, and it “SHALL NOT be included in any of the payloads conveyed”: a signature made over it proves the signer is on this session, which is precisely what stops a recorded attestation being replayed.
Borrowed rather than copied, because it is key material with a
ZeroizeOnDrop owner and there is no reason for a second
copy to exist.
privilege: Option<Privilege>The strongest privilege the ISD holds over this path (§6.6.6.2), when the caller computed one.
The access check that admitted an action only proves the subject cleared the required
bar. A few clusters need to know how far above it the subject actually is, because the
specification gives administrators and managers different rules for the same command:
§9.16.7.1’s RegisterClient demands a verification key from a manager and ignores one
from an administrator, so a server that could not tell them apart would either lock
administrators out or let a manager overwrite any registration it liked.
Derived by the caller from the same access decision that admitted the action — with
Granted::highest where the ACL engine is in use —
the way timed and atomic are derived. None means the caller did not compute one,
and a cluster that needs it must then take the cautious branch.
group: Option<GroupId>The group this action was addressed to, when it arrived as a groupcast (§4.16.1).
None is a unicast. Several clusters branch on this rather than on anything in the
payload: §1.3.7.1.2 says the Groups cluster “SHALL NOT generate an AddGroupResponse
command” for a groupcast, and the reason is arithmetic — one multicast reaching twenty
lights would otherwise draw twenty unicast responses at once, on a network chosen for
low power rather than burst capacity.
§8.8.2.2 also forbids a groupcast Invoke from carrying a concrete endpoint or expecting any response at all, so a cluster that answered anyway would be answering a request the client is not listening for.
event_filters: Option<&'a [u8]>§8.4.3.3 step 6.a.i’s EventFilters, still encoded, as the request carried them.
A client that already holds events up to some number sends this so the node does not
resend them — the event log’s equivalent of DataVersionFilters, and the only way a
client resuming after a gap avoids re-reading the whole ring.
data_version_filters: Option<&'a [u8]>§8.4.3.2 step 3.a’s DataVersionFilters, still encoded, as the request carried them.
Kept as TLV rather than a decoded list because this type is Copy and the crate does
not allocate: the filters are walked once per reported attribute, which is cheap for the
handful a client sends and costs nothing when there are none.
A client sends these to say “do not send me a cluster I already have”, which is the only mechanism in the interaction model that makes a wildcard read cheap on a device that mostly has not changed. A server that decodes them and ignores them is correct about every value it sends and wrong about the bandwidth, on exactly the reads that matter most.
Implementations§
Source§impl<'a> InteractionContext<'a>
impl<'a> InteractionContext<'a>
Sourcepub const fn new() -> Self
pub const fn new() -> Self
The context of an action on an unauthenticated, untimed session.
A starting point for the with_* builders. This is const, and the builders are too,
because a device’s fixed set of contexts is const data — and a const struct literal
has to name every field, so every field added here would otherwise be a breaking change
for anyone who wrote one.
Sourcepub const fn with_event_filters(self, filters: &'a [u8]) -> Self
pub const fn with_event_filters(self, filters: &'a [u8]) -> Self
Carries §8.4.3.3 step 6.a.i’s EventFilters, as the request encoded them.
Sourcepub const fn with_data_version_filters(self, filters: &'a [u8]) -> Self
pub const fn with_data_version_filters(self, filters: &'a [u8]) -> Self
Carries §8.4.3.2 step 3.a’s DataVersionFilters, as the request encoded them.
Sourcepub const fn with_group(self, group: GroupId) -> Self
pub const fn with_group(self, group: GroupId) -> Self
Marks the action as a groupcast addressed to group (§4.16.1).
Sourcepub const fn with_privilege(self, privilege: Privilege) -> Self
pub const fn with_privilege(self, privilege: Privilege) -> Self
Records the strongest privilege the ISD holds over this path.
Sourcepub const fn with_vendor_id_verified(self) -> Self
pub const fn with_vendor_id_verified(self) -> Self
Records that §6.4.10’s Fabric Table Vendor ID Verification Procedure was run against the peer that sent this action.
§11.25.6.1 is the one place that asks: ICACCSRRequest refuses with JfVidNotVerified
until the peer has proved which vendor owns the fabric it is administering from. The
procedure itself is a challenge and a signature over an exchange this layer does not
see, so the answer comes in with the action rather than being derived here.
Sourcepub const fn with_fabric(self, fabric_index: FabricIndex) -> Self
pub const fn with_fabric(self, fabric_index: FabricIndex) -> Self
Sets the accessing fabric.
Sourcepub const fn with_large_messages(self) -> Self
pub const fn with_large_messages(self) -> Self
Marks the transport as able to carry Large Messages (§7.7.5) — that is, TCP.
Sourcepub const fn fabric_filtered(self) -> Self
pub const fn fabric_filtered(self) -> Self
Asks for §7.19.1.8.2’s fabric filtering on a fabric-scoped list read.
Sourcepub const fn on_session(self, session: SessionId) -> Self
pub const fn on_session(self, session: SessionId) -> Self
Sets the secure session this action arrived on.
Sourcepub const fn under_claim(self, claim: ClaimRef<'a>) -> Self
pub const fn under_claim(self, claim: ClaimRef<'a>) -> Self
Marks this action as writing under an open atomic claim (§7.15.3).
Sourcepub const fn from_peer(self, peer_node_id: NodeId) -> Self
pub const fn from_peer(self, peer_node_id: NodeId) -> Self
Sets the peer’s operational Node ID, as CASE proved it (§6.6.6.3).
Sourcepub const fn with_attestation_challenge(
self,
challenge: &'a SymmetricKey,
) -> Self
pub const fn with_attestation_challenge( self, challenge: &'a SymmetricKey, ) -> Self
Attaches the session’s AttestationChallenge (§4.14.2.6.2).
Trait Implementations§
Source§impl<'a> Clone for InteractionContext<'a>
impl<'a> Clone for InteractionContext<'a>
impl<'a> Copy for InteractionContext<'a>
Source§impl<'a> Debug for InteractionContext<'a>
impl<'a> Debug for InteractionContext<'a>
Source§impl Default for InteractionContext<'_>
impl Default for InteractionContext<'_>
Source§fn default() -> Self
fn default() -> Self
The same as InteractionContext::new, so the two cannot drift apart.