pub struct Messaging<C: Config, const S: usize = 16, const X: usize = 64> { /* private fields */ }rustcrypto only.Expand description
A node’s message processing: sessions, exchanges, and the framing between them.
S sizes the session table and X the exchange table. Both default to a device-sized
node that satisfies every specification minimum for five fabrics, and
SessionTable::CHECK refuses an S that cannot.
Implementations§
Source§impl<C: Config, const S: usize, const X: usize> Messaging<C, S, X>
impl<C: Config, const S: usize, const X: usize> Messaging<C, S, X>
Sourcepub fn new(
first_session_id: u16,
first_exchange_id: u16,
initial_counter: u32,
) -> Self
pub fn new( first_session_id: u16, first_exchange_id: u16, initial_counter: u32, ) -> Self
A node with no sessions and no exchanges.
first_session_id, first_exchange_id and initial_counter should all come from
Rng. §4.6.1.1 requires the counter to start at random: one
that always starts at zero leaks how many times a device has rebooted and makes nonce
reuse across a factory reset far too easy. A full-width random number is what to pass —
MessageCounter::new narrows it to the twenty-eight
bits §4.6.1.1 allows, so the caller does not have to know that it must.
Sourcepub const fn register(&mut self, protocols: Protocols)
pub const fn register(&mut self, protocols: Protocols)
Registers the protocols this node’s upper layer will accept (§4.10.3.1).
Defaults to Protocols::DEVICE — Secure Channel and the Interaction Model — which is
what a node that serves clusters needs. A node that also transfers files registers
Protocols::BDX on top; one that does neither registers less.
Sourcepub const fn set_privacy(&mut self, privacy: bool)
pub const fn set_privacy(&mut self, privacy: bool)
Applies §4.9’s privacy processing to outgoing secure unicast messages.
Off by default, and deliberately. The P flag is only required on group messages (§4.16.2 step 2c, §4.18): on a secure unicast session it is the sender’s choice, and what it buys is hiding the message counter from a passive observer on the link — the counter is already authenticated, and anyone with the key can read it either way. What it costs is depending on every peer having exercised its deobfuscation path, which is not a bet worth making by default for a property this small.
Receiving a private message never needs this: the flag is in the message, and
Messaging::receive honours it whatever this is set to.
Sourcepub fn open_unsecured_as_initiator(&mut self, ephemeral: NodeId) -> Result<()>
pub fn open_unsecured_as_initiator(&mut self, ephemeral: NodeId) -> Result<()>
Opens §4.13.2.1’s Unsecured Session Context as the initiator.
ephemeral is the Ephemeral Initiator Node ID this node encloses as the Source Node ID
of every unsecured message it sends, and which the responder will echo back as the
Destination Node ID. §4.13.2.1: “Initiators SHALL select a new random ephemeral node ID
for each unsecured session”, from the Operational Node ID range — so it comes from
Rng and is not the node’s operational identity. A node that
reused one identity across sessions would let a passive observer link them.
§Errors
ErrorCode::InvalidArgument unless ephemeral is in the Operational Node ID range.
Sourcepub fn open_unsecured(
&mut self,
protocol: ProtocolId,
now: Instant,
randomness: u64,
) -> Result<ExchangeKey>
pub fn open_unsecured( &mut self, protocol: ProtocolId, now: Instant, randomness: u64, ) -> Result<ExchangeKey>
Opens an unsecured exchange as the initiator, establishing §4.13.2.1’s Unsecured Session Context in the same call.
This is how a commissioner starts PASE, and how any node starts CASE: both handshakes run on the unsecured session before there is a key. The context is not optional — §4.13.2.1 has the initiator “enclose” its Ephemeral Initiator Node ID as the Source Node ID of every message, and a message with neither a Source nor a Destination is one the specification tells the responder to discard.
randomness comes from the caller’s Rng and becomes the
ephemeral id, which is a new one for each unsecured session by §4.13.2.1.
Sourcepub const fn close_unsecured(&mut self)
pub const fn close_unsecured(&mut self)
Forgets the Unsecured Session Context, so the next handshake starts a new one.
§4.13.2.1 requires a new ephemeral id per unsecured session, so a node that runs PASE and then CASE against the same peer closes the first context before opening the second.
Sourcepub const fn unsecured_ephemeral_id(&self) -> Option<NodeId>
pub const fn unsecured_ephemeral_id(&self) -> Option<NodeId>
The Ephemeral Initiator Node ID of the current Unsecured Session Context, if there is one.
Sourcepub const fn sessions(&self) -> &SessionTable<C, S>
pub const fn sessions(&self) -> &SessionTable<C, S>
The session table.
Sourcepub const fn sessions_mut(&mut self) -> &mut SessionTable<C, S>
pub const fn sessions_mut(&mut self) -> &mut SessionTable<C, S>
The session table, mutably — for the fields a completed handshake fills in afterwards, such as §11.18.6.8 step 10a’s accessing fabric.
Installing a session goes through Messaging::install_session instead: a session
and its exchanges are one lifetime, and this reference only reaches one of them.
Sourcepub fn install_session(
&mut self,
session: SecureSession,
now: Instant,
randomness: u32,
scratch: &mut [u8],
out: &mut [u8],
) -> Result<Option<Evicted>>
pub fn install_session( &mut self, session: SecureSession, now: Instant, randomness: u32, scratch: &mut [u8], out: &mut [u8], ) -> Result<Option<Evicted>>
Installs the session a handshake produced, evicting one if there is no room (§4.11.1.1).
A session table that answers NoSpace is a node that can be commissioned exactly
as many times as the session table is long and then never again — and the failure appears at the
next administrator, not at the one who filled it. §4.11.1.1 is explicit about the
alternative and about its three steps, in order:
- the least recently used session, by
SessionTimestamp; - a
StatusReport(SUCCESS, SECURE_CHANNEL, CLOSE_SESSION)to that peer, and only then “remove all state associated with the session”; - the new session’s own establishment message, which the caller was sending anyway.
Step 2’s two halves are why this takes buffers and returns an Evicted: the report
has to be framed while the session that encrypts it still exists, and put on the wire
by whoever owns the socket. The removal has already happened when this returns; what
is left is a datagram the caller sends to Evicted::peer. Dropping it costs the
peer nothing worse than a session it believes in until its next message fails, which
is why this is must_use rather than an error.
Ok(None) is the ordinary case: there was room and nothing was evicted.
Sourcepub fn close_session(&mut self, session: SessionId) -> bool
pub fn close_session(&mut self, session: SessionId) -> bool
Removes a session and everything associated with it (§4.13.3.1).
Returns whether there was one. The exchanges on that session go with it: an exchange outlives its session only as an entry nothing can ever answer on, holding a slot in a fixed-capacity table until it times out.
Sourcepub fn remove_fabric(&mut self, fabric: FabricIndex) -> usize
pub fn remove_fabric(&mut self, fabric: FabricIndex) -> usize
Removes every session on a fabric, and their exchanges — what RemoveFabric
(§11.18.6.12) owes at the message layer.
Returns how many sessions went. The clusters’ half of the same command is
Lifecycle::FabricRemoved.
Sourcepub const fn exchanges(&self) -> &ExchangeTable<C, X>
pub const fn exchanges(&self) -> &ExchangeTable<C, X>
The exchange table.
Sourcepub const fn exchanges_mut(&mut self) -> &mut ExchangeTable<C, X>
pub const fn exchanges_mut(&mut self) -> &mut ExchangeTable<C, X>
The exchange table, mutably.
Sourcepub fn open(
&mut self,
session: SessionId,
protocol: ProtocolId,
now: Instant,
) -> Result<ExchangeKey>
pub fn open( &mut self, session: SessionId, protocol: ProtocolId, now: Instant, ) -> Result<ExchangeKey>
Opens an exchange this node initiates, to a peer it has not named yet.
The peer is learned from the first message that comes back. Prefer
Messaging::open_to where it is already known: until it is, this node assumes UDP
and runs MRP, which is right for UDP and one wasted round trip on BTP.
Sourcepub fn open_to(
&mut self,
session: SessionId,
protocol: ProtocolId,
peer: Peer,
now: Instant,
) -> Result<ExchangeKey>
pub fn open_to( &mut self, session: SessionId, protocol: ProtocolId, peer: Peer, now: Instant, ) -> Result<ExchangeKey>
Opens an exchange to a peer this node has already found.
Naming the transport is what lets §4.12.4 be honoured: a BLE peer’s exchange never sets the R flag, because BTP has already delivered the message or closed the session trying.
Sourcepub fn open_unsecured_to(
&mut self,
protocol: ProtocolId,
peer: Peer,
now: Instant,
randomness: u64,
) -> Result<ExchangeKey>
pub fn open_unsecured_to( &mut self, protocol: ProtocolId, peer: Peer, now: Instant, randomness: u64, ) -> Result<ExchangeKey>
Messaging::open_unsecured, to a peer whose address is already known.
What a commissioner uses: it found the device over BLE or mDNS, so it has somewhere to send before any session exists.
Sourcepub fn peer(&self, exchange: ExchangeKey) -> Option<Peer>
pub fn peer(&self, exchange: ExchangeKey) -> Option<Peer>
Where an exchange’s peer is, once it is known.
Sourcepub fn close(&mut self, exchange: ExchangeKey) -> bool
pub fn close(&mut self, exchange: ExchangeKey) -> bool
Closes an exchange.
Sourcepub fn receive<'b>(
&mut self,
buf: &'b mut [u8],
from: Peer,
now: Instant,
) -> Result<Received<'b>>
pub fn receive<'b>( &mut self, buf: &'b mut [u8], from: Peer, now: Instant, ) -> Result<Received<'b>>
Processes one arriving datagram, in place (§4.7.2).
buf is decrypted in place, so the returned payload borrows it. On any failure the
contents of buf are unspecified — §3.6.2 says a failed tag check leaves the payload
undefined — and nothing in this node’s state has moved.
Sourcepub fn send(
&mut self,
exchange: ExchangeKey,
opcode: u8,
reliable: bool,
payload: &[u8],
now: Instant,
randomness: u32,
scratch: &mut [u8],
out: &mut [u8],
) -> Result<(usize, u32)>
pub fn send( &mut self, exchange: ExchangeKey, opcode: u8, reliable: bool, payload: &[u8], now: Instant, randomness: u32, scratch: &mut [u8], out: &mut [u8], ) -> Result<(usize, u32)>
Builds an outgoing message on an exchange (§4.7.1).
reliable sets the MRP R flag; a reliable message is remembered for
retransmission until it is acknowledged, and Messaging::poll is what resends it.
randomness is the jitter draw of §4.12.2.1 and should come from
Rng.
Returns how many octets of out the datagram occupies, and the counter it was sent
with — which is what a retransmission is identified by.
Sourcepub fn acknowledge(
&mut self,
exchange: ExchangeKey,
now: Instant,
out: &mut [u8],
) -> Result<usize>
pub fn acknowledge( &mut self, exchange: ExchangeKey, now: Instant, out: &mut [u8], ) -> Result<usize>
Sends the standalone acknowledgement a Received said was owed (§4.12.1).
A standalone ack is not reliable — acknowledging an acknowledgement would never terminate — and carries no payload.
Sourcepub fn wake_at(&self) -> Option<Instant>
pub fn wake_at(&self) -> Option<Instant>
When Messaging::poll next needs to be called.
The earlier of a reliability deadline and the next moment an abandoned exchange could be reclaimed, so a node that honours this wake-up gets §4.10.5.3’s cleanup without scheduling anything of its own.
Sourcepub fn poll(&mut self, now: Instant, randomness: u32) -> Option<Due>
pub fn poll(&mut self, now: Instant, randomness: u32) -> Option<Due>
Drives the reliability timers (§4.12.2.1) and reclaims abandoned exchanges (§4.10.5.3).
Returns one action at a time; call until it returns None.
Reaping happens here rather than in a method a node has to remember to call, because an
exchange table reclaimed only on request is one an attacker fills at leisure: every
unsecured datagram with the I flag opens an entry (§4.10.5.2), and X of them
would otherwise deny every later session establishment for the node’s whole uptime.