Crate umsh_mac

Expand description

UMSH MAC-layer coordinator and supporting state types.

Note: This reference implementation is a work in progress and was developed with the assistance of an LLM. It should be considered experimental.

This crate is the central runtime for the UMSH mesh protocol. It owns every piece of radio-facing state and drives the full MAC lifecycle: receiving and authenticating inbound frames, forwarding eligible frames as a repeater, issuing and verifying transport ACKs, retransmitting unacknowledged sends, suppressing duplicates, enforcing replay windows, managing frame-counter persistence, and servicing the outbound transmit queue.

The crate is no_std compatible. All data structures are backed by heapless fixed-capacity collections; capacity is controlled by const-generic parameters on Mac so the compiler enforces sizing at build time with zero heap allocation.

§Architecture overview

┌────────────────────────────────────────────────────────────────┐
│  Application / upper layers                                    │
│  queue_broadcast / queue_unicast / queue_multicast / …         │
└──────────────────────────┬─────────────────────────────────────┘
                           │  SendOptions  →  SendReceipt
                           ▼
┌────────────────────────────────────────────────────────────────┐
│  Mac<P>  (coordinator.rs)                                      │
│                                                                │
│  ┌─────────────────┐  ┌────────────────┐  ┌────────────────┐  │
│  │ IdentitySlot[N] │  │ PeerRegistry   │  │ ChannelTable   │  │
│  │  frame counters │  │  public keys   │  │  channel keys  │  │
│  │  pending ACKs   │  │  cached routes │  │  derived keys  │  │
│  │  pairwise keys  │  └────────────────┘  └────────────────┘  │
│  └─────────────────┘                                           │
│  ┌──────────────────────────────────────────────────────────┐  │
│  │ TxQueue  (priority-ordered outbound frame buffer)        │  │
│  └──────────────────────────────────────────────────────────┘  │
│  ┌──────────────────────────────────────────────────────────┐  │
│  │ DuplicateCache  │  ReplayWindow (per peer, per identity) │  │
│  └──────────────────────────────────────────────────────────┘  │
└──────────────────────────┬─────────────────────────────────────┘
                           │  async next_event()
                           ▼
┌────────────────────────────────────────────────────────────────┐
│  Platform  (umsh-hal + umsh-crypto)                            │
│  Radio · Clock · Rng · Aes/Sha · CounterStore · KeyValueStore  │
└────────────────────────────────────────────────────────────────┘

§Modules and key types

§[`coordinator`] — the top-level state machine

Mac is the single top-level type. Create one with Mac::new, register identities and peers, then drive it with Mac::run, Mac::run_quiet, or Mac::next_event depending on whether you want a long-lived driver loop or manual multiplexing with other async work. Everything else in this crate exists to support Mac.

Supporting types in this module:

LocalIdentityId — opaque slot index returned when registering a local keypair.
LocalIdentity — either a long-term platform identity or an ephemeral software identity for PFS sessions.
IdentitySlot — per-identity runtime state: keys, frame counter, pending ACKs.
OperatingPolicy — transmission-time rules for the local node (amateur-radio mode, operator callsign, per-channel overrides).
RepeaterConfig — controls whether and how inbound frames are forwarded.
AmateurRadioMode — shared enum governing encryption and identification requirements under ham-radio law.
ChannelPolicy — per-channel overrides within an OperatingPolicy.
SendError, MacError, CounterPersistenceError — error types for queuing, runtime event processing, and frame-counter store operations respectively.

§[`send`] — outbound transmission types

SendOptions — high-level parameters for a single send: MIC size, encryption, flood hops, ACK request, source route, salt, etc.
SendReceipt — opaque token returned for ACK-requested sends; matched against inbound MAC ACKs to confirm delivery.
TxQueue — priority-ordered, fixed-capacity queue of sealed frames waiting for radio transmission.
QueuedTx — one entry in the transmit queue; includes frame bytes, priority, not-before timestamp, and CAD retry count.
TxPriority — priority classes from highest (ImmediateAck) to lowest (Application).
AckState — ACK lifecycle state machine covering queued sends, forwarding confirmation, retry scheduling, and final destination ACK waiting.
PendingAck — full tracking record for one in-flight ACK-requested send, stored in the identity slot until delivery is confirmed or the deadline expires.
ResendRecord — verbatim sealed frame bytes retained for retransmission without re-sealing.

§[`cache`] — duplicate suppression and replay protection

DuplicateCache — a fixed-size FIFO ring that records recently-seen DupCacheKey values. Before forwarding or delivering any received frame, the coordinator checks this cache; matching entries are silently dropped. Prevents re-delivery of frames that echoed back via multiple repeater paths.
DupCacheKey — keyed on the truncated MIC for authenticated packets (unforgeable and compact) or a 32-bit hash of the frame body for unauthenticated ones (broadcast).
ReplayWindow — per-peer, per-identity sliding window over frame counters. Rejects exact counter replays and frames older than the backtrack window, while tolerating a small amount of out-of-order delivery. Backed by a RecentMic ring for backward-window disambiguation.
ReplayVerdict — outcome of a replay check: Accept, Duplicate, or Replay.

§[`peers`] — remote peer and channel registries

PeerRegistry — a flat list of PeerInfo records (public key + last-seen time + cached route). Looked up by hint or full key when matching inbound packets and routing outbound sends.
PeerId — opaque index into the peer registry.
CachedRoute — either an explicit source route or a flood-distance estimate, learned from successfully received packets and used to route future sends without flooding.
PeerCryptoMap — per-identity map from PeerId to PeerCryptoState (established pairwise keys + replay window). One map per IdentitySlot.
ChannelTable — flat list of registered multicast channels. Each entry stores the raw channel key, the derived k_enc/k_mic keys (precomputed at registration time), and the 2-byte channel ID (also precomputed). Looked up by channel ID when authenticating inbound multicast and blind-unicast frames.

§[`handle`] — shared-ownership coordinator access

MacHandle — a Copy-able, lifetime-bounded reference to a RefCell<Mac>. Designed for multi-task environments (e.g., tokio or RTOS task pairs) where one task runs the next_event loop while another enqueues sends or updates configuration without holding a long-lived mutable borrow.

§Platform trait

Platform is the single integration point. Implement it once per deployment target to supply concrete driver types for all hardware abstractions:

struct MyPlatform;

impl umsh_mac::Platform for MyPlatform {
    type Identity = MyHsmIdentity;
    type Aes      = MyAesDriver;
    type Sha      = MyShaDriver;
    type Radio    = MySx1262Driver;
    type Delay    = MyDelay;
    type Clock    = MyMonotonicClock;
    type Rng      = MyTrng;
    type CounterStore = MyFlashStore;
    type KeyValueStore = MyNvmStore;
}

The umsh workspace crate provides a std/tokio-backed implementation (tokio_support::StdPlatform) suitable for desktop development and testing.

§Frame-counter persistence

UMSH uses a monotonic frame counter (not a timestamp) for replay protection. Because the counter must never reuse a value, it must be committed to non-volatile storage before the corresponding value is used on-air, or after a power cycle the counter could reset to a previously-seen value, allowing old ciphertexts to replay. The coordinator manages this automatically:

On startup, call Mac::load_persisted_counter for each long-term identity to read the last-committed boundary from the umsh_hal::CounterStore and set the live counter to the next safe starting point.
At runtime, the coordinator schedules a persist whenever the live counter crosses a block boundary (every [COUNTER_PERSIST_BLOCK_SIZE] frames, default 128). While a persist is pending, sends will eventually block with SendError::CounterPersistenceLag if the store is not flushed in time.
The application calls Mac::service_counter_persistence (typically from the next_event callback or a background task) to drain the pending write queue.

§`no_std` usage

Enable default-features = false in Cargo.toml. The crate compiles without the standard library. All capacity limits are compile-time const generics. The std feature enables test_support, which provides software-backed driver stubs for unit testing.

Modules§

test_support: Std-only simulated radio network and dummy platform components for tests.

Structs§

CapacityError: Error returned when a fixed-capacity MAC data structure is full.
ChannelInfoRef: Borrowing view of an inbound MAC event.
ChannelPolicy: Per-channel operating-policy overrides enforced on outgoing traffic.
ChannelState: Shared state for one multicast channel.
ChannelTable: Fixed-capacity channel table shared by the MAC coordinator.
DuplicateCache: Fixed-capacity cache of recently observed duplicate keys.
HintReplayState: Replay state for a sender known only by hint.
IdentitySlot: Per-identity runtime state owned by the Mac coordinator.
LocalIdentityId: Opaque handle that identifies a locally registered identity within the Mac coordinator.
Mac: Central MAC coordinator that owns and drives the full UMSH radio-facing state machine.
MacHandle: Lightweight, cloneable handle for queuing MAC operations against shared state.
OperatingPolicy: Local transmission policy enforced by the Mac coordinator on all outgoing frames.
PeerCryptoMap: Fixed-capacity map of per-peer secure transport state.
PeerCryptoState: Per-peer secure transport state.
PeerId: Opaque identifier for one remote peer.
PeerInfo: Shared metadata tracked for a remote peer.
PeerRegistry: Fixed-capacity registry of remote peers.
PendingAck: Complete tracking state for one in-flight ACK-requested transmission.
QueuedTx: One entry in the TxQueue waiting to be transmitted by the Mac coordinator.
ReceivedPacketRef: Borrowed view of one accepted inbound packet together with parsed on-wire metadata.
RecentMic: Recently accepted MIC tracked for backward-window replay handling.
RepeaterConfig: Configuration governing whether and how the node forwards received frames.
ReplayWindow: Replay-detection window for secure traffic from one sender.
ResendRecord: Sealed frame bytes and optional source route retained for retransmission.
RouteHops: Iterator over packed two-byte route hops from a source-route or trace-route option.
RxMetadata: Local physical-layer observations captured when a frame was received.
SendOptions: High-level transmission options passed to Mac send helpers.
SendReceipt: Opaque tracking token returned for ACK-requested transmissions.
Snr: Signal-to-noise ratio represented in centibels (0.1 dB units).
TxQueue: Fixed-capacity, priority-ordered transmit queue owned by the Mac coordinator.

Enums§

AckState: Tracks which phase of the two-stage ACK lifecycle a pending transmission is in.
AmateurRadioMode: Controls how the coordinator and optional repeater handle amateur-radio legal requirements.
CachedRoute: Learned routing information for a remote peer.
CounterPersistenceError: Errors returned while loading persisted frame-counter boundaries via Mac::load_persisted_counter.
DupCacheKey: Duplicate-suppression key derived from an accepted packet.
LocalIdentity: A local node identity that the Mac coordinator owns and acts on behalf of.
MacError: Runtime errors produced by the Mac coordinator’s async event loop.
MacEventRef: Borrowing view of an inbound MAC event.
MacHandleError: Error returned when a MacHandle operation cannot access the shared coordinator.
PacketFamily: Coarser grouping of on-wire packet types.
PendingAckError: Errors returned when recording pending-ACK state in an identity slot.
ReplayVerdict: Result of checking a packet against a replay window.
SendError: Errors returned by the Mac coordinator when queueing an outbound send.
TxPriority: Priority class assigned to entries in the TxQueue.

Constants§

DEFAULT_ACKS: Default pending-ACK capacity for the common Mac configuration.
DEFAULT_CHANNELS: Default shared-channel capacity for the common Mac configuration.
DEFAULT_DUP: Default duplicate-cache capacity for the common Mac configuration.
DEFAULT_FRAME: Default frame-buffer capacity for the common Mac configuration.
DEFAULT_IDENTITIES: Default identity-slot capacity for the common Mac configuration.
DEFAULT_PEERS: Default remote-peer capacity for the common Mac configuration.
DEFAULT_TX: Default transmit-queue depth for the common Mac configuration.

Traits§

Platform: Bundle of platform-specific associated types used by the higher layers.

Crate umsh_mac

Crate umsh_mac Copy item path

§Architecture overview

§Modules and key types

§[coordinator] — the top-level state machine

§[send] — outbound transmission types

§[cache] — duplicate suppression and replay protection

§[peers] — remote peer and channel registries

§[handle] — shared-ownership coordinator access

§Platform trait

§Frame-counter persistence

§no_std usage

Modules§

Structs§

Enums§

Constants§

Traits§

Crate umsh_mac

§[`coordinator`] — the top-level state machine

§[`send`] — outbound transmission types

§[`cache`] — duplicate suppression and replay protection

§[`peers`] — remote peer and channel registries

§[`handle`] — shared-ownership coordinator access

§`no_std` usage