Skip to main content

Messaging

Struct Messaging 

Source
pub struct Messaging<C: Config, const S: usize = 16, const X: usize = 64> { /* private fields */ }
Available on crate feature 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>

Source

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.

Source

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.

Source

pub const fn protocols(&self) -> Protocols

Which protocols are registered.

Source

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.

Source

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.

Source

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.

Source

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.

Source

pub const fn unsecured_ephemeral_id(&self) -> Option<NodeId>

The Ephemeral Initiator Node ID of the current Unsecured Session Context, if there is one.

Source

pub const fn sessions(&self) -> &SessionTable<C, S>

The session table.

Source

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.

Source

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:

  1. the least recently used session, by SessionTimestamp;
  2. a StatusReport(SUCCESS, SECURE_CHANNEL, CLOSE_SESSION) to that peer, and only then “remove all state associated with the session”;
  3. 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.

Source

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.

Source

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.

Source

pub const fn exchanges(&self) -> &ExchangeTable<C, X>

The exchange table.

Source

pub const fn exchanges_mut(&mut self) -> &mut ExchangeTable<C, X>

The exchange table, mutably.

Source

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.

Source

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.

Source

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.

Source

pub fn peer(&self, exchange: ExchangeKey) -> Option<Peer>

Where an exchange’s peer is, once it is known.

Source

pub fn close(&mut self, exchange: ExchangeKey) -> bool

Closes an exchange.

Source

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.

Source

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.

Source

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.

Source

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.

Source

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.

Trait Implementations§

Source§

impl<C: Debug + Config, const S: usize, const X: usize> Debug for Messaging<C, S, X>

Source§

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter. Read more

Auto Trait Implementations§

§

impl<C, const S: usize, const X: usize> Forget for Messaging<C, S, X>

§

impl<C, const S: usize, const X: usize> Freeze for Messaging<C, S, X>
where SessionTable<C, S>: Freeze, ExchangeTable<C, X>: Freeze,

§

impl<C, const S: usize, const X: usize> Move for Messaging<C, S, X>

§

impl<C, const S: usize, const X: usize> RefUnwindSafe for Messaging<C, S, X>

§

impl<C, const S: usize, const X: usize> Send for Messaging<C, S, X>
where SessionTable<C, S>: Send, ExchangeTable<C, X>: Send,

§

impl<C, const S: usize, const X: usize> Sync for Messaging<C, S, X>
where SessionTable<C, S>: Sync, ExchangeTable<C, X>: Sync,

§

impl<C, const S: usize, const X: usize> Unpin for Messaging<C, S, X>
where SessionTable<C, S>: Unpin, ExchangeTable<C, X>: Unpin,

§

impl<C, const S: usize, const X: usize> UnsafeUnpin for Messaging<C, S, X>

§

impl<C, const S: usize, const X: usize> UnwindSafe for Messaging<C, S, X>

Blanket Implementations§

Source§

impl<T> Any for T
where T: 'static + ?Sized,

Source§

fn type_id(&self) -> TypeId

Gets the TypeId of self. Read more
Source§

impl<T> Borrow<T> for T
where T: ?Sized,

Source§

fn borrow(&self) -> &T

Immutably borrows from an owned value. Read more
Source§

impl<T> BorrowMut<T> for T
where T: ?Sized,

Source§

fn borrow_mut(&mut self) -> &mut T

Mutably borrows from an owned value. Read more
Source§

impl<T> From<T> for T

Source§

fn from(t: T) -> T

Returns the argument unchanged.

Source§

impl<T, U> Into<U> for T
where U: From<T>,

Source§

fn into(self) -> U

Calls U::from(self).

That is, this conversion is whatever the implementation of From<T> for U chooses to do.

Source§

impl<T> Same for T

Source§

type Output = T

Should always be Self
Source§

impl<T, U> TryFrom<U> for T
where U: Into<T>,

Source§

type Error = !

The type returned in the event of a conversion error.
Source§

fn try_from(value: U) -> Result<T, !>

Performs the conversion.
Source§

impl<T, U> TryInto<U> for T
where U: TryFrom<T>,

Source§

type Error = <U as TryFrom<T>>::Error

The type returned in the event of a conversion error.
Source§

fn try_into(self) -> Result<U, <U as TryFrom<T>>::Error>

Performs the conversion.