Skip to main content

Messaging

Struct Messaging 

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

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.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.

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 const fn close_unsecured(&mut self)

Forgets the Unsecured Session Context, so the next handshake starts a new one.

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 — how a completed PASE or CASE installs its keys.

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 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> Freeze for Messaging<C, S, X>
where SessionTable<C, S>: Freeze, ExchangeTable<C, X>: Freeze,

§

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.