pub struct Messaging<C: Config, const S: usize, const X: usize> { /* private fields */ }rustcrypto only.Expand description
A node’s message processing: sessions, exchanges, and the framing between them.
S is Config::SESSIONS and X is SESSIONS * EXCHANGES_PER_SESSION.
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.4, §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 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.
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 — how a completed PASE or CASE installs its keys.
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 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.