Skip to main content

Crate matter_kit

Crate matter_kit 

Source
Expand description

A Matter implementation in Rust: one crate, no_std, no allocation, and no runtime of its own.

Matter is the CSA’s smart-home standard — the protocol behind Apple Home, Google Home, Alexa and SmartThings. This crate targets specification 1.6 (approved 2026-06-16) and is built to be certifiable rather than merely interoperable: the same data model the certification Test Harness reads is the data model this crate is generated from.

§Status

Under construction and pre-1.0. A device can be commissioned into a fabric end to end — over IPv6, BLE, Wi-Fi PAF or NFC — answer Reads, Writes and Invokes against a const data model, hold subscriptions, enforce §6.6’s access control, take part in groupcast, move a firmware image over BDX and advertise itself over DNS-SD, with messaging composing the layers so that a datagram finds its session, exchange and protocol. The CHIP SDK’s own chip-tool commissions the light example through the whole of §5.5, and eleven of the CSA Test Harness’s certification cases pass against it.

What is missing is most of the application clusters’ behaviour behind the generated descriptors, and the facades — Node::builder, Controller — that would turn the examples’ hand-assembly into three lines. The README carries the layer-by-layer table; each module here states which sections it implements.

§Three things that shape the whole crate

A capacity is declared once, and the specification checks it. Every table in the stack — fabrics, sessions, exchanges, subscriptions, access-control entries — is a fixed-capacity array whose length is its own const parameter, and each one carries a const assertion that the length can keep the promises Config makes to each fabric. A node that could not pass certification does not compile, and the failing rule is named in the build error. Two libraries in one binary cannot fight over it the way they fight over a Cargo feature.

ⓘ
use matter_kit::{Config, DefaultConfig, acl::Acl};

// Core §2.11.1.1 wants four access-control entries for each of five fabrics.
let too_small: Acl<DefaultConfig, 4, 4, 3> = Acl::new();
use matter_kit::{Capacity, Config, DefaultConfig, acl::Acl};

// The defaults are the specification's own minima, so naming none of them is conformant.
let acl: Acl<DefaultConfig> = Acl::new();
assert_eq!(<Acl<DefaultConfig> as Capacity>::PER_FABRIC, DefaultConfig::ACL_ENTRIES_PER_FABRIC);

No runtime is chosen for you. The crate is async over core::future and talks to the outside world through the traits in platform: sockets, timers, randomness, storage, cryptography. No executor crate is in the dependency tree at all; examples/ run on a block_on of their own. One consequence worth having: every timeout in the specification — MRP backoff, the fail-safe, an intermittently-connected device’s idle period — is driven by a platform::Timer, so platform::sim runs an hour-long scenario in microseconds.

Nothing panics on network input. unwrap, expect, panic! and slice indexing are denied crate-wide; every parser returns Error. Resource exhaustion is a value (ErrorCode::NoSpace, ErrorCode::Busy), so a device that runs out of exchanges answers rather than aborts.

§Commissioning, in miniature

The whole of PASE: a printed passcode becomes three shared keys, without the passcode ever crossing the wire. Needs the rustcrypto feature, which is on by default.

The salt and iteration count below are the CHIP test vectors, so that this example is the protocol and nothing else. A product’s are neither: §3.9 allows 1 000 to 100 000 iterations and the floor is what an offline attack on leaked verifier material is priced at, and a salt shared between devices shares its pre-computation with all of them. Draw the salt per device at manufacture and put the iteration count well above the minimum — examples/light does both.

use matter_kit::crypto::Spake2pVerifierData;
use matter_kit::msg::SessionId;
use matter_kit::sc::{PaseInitiator, PaseResponder, PbkdfParameters, ResponderConfig};

// What a factory burns into the device. The passcode itself is never stored.
let parameters = PbkdfParameters::new(1_000, b"SPAKE2P Key Salt")?;
let verifier =
    Spake2pVerifierData::from_passcode(20_202_021, &parameters.salt, parameters.iterations)?;

let mut device = PaseResponder::new(
    ResponderConfig { verifier, parameters: parameters.clone(), session_params: None },
    SessionId(1),
);
let mut commissioner =
    PaseInitiator::new(20_202_021, SessionId(2), Some(parameters), None);

let (mut a, mut b) = ([0u8; 512], [0u8; 512]);
let n = commissioner.start(&[0x11; 32], &mut a)?;
let n = device.on_pbkdf_param_request(&a[..n], &[0x22; 32], &mut b)?;
let n = commissioner.on_pbkdf_param_response(&b[..n], &[0x33; 32], &mut a)?;
let n = device.on_pake1(&a[..n], &[0x44; 32], &mut b)?;
let n = commissioner.on_pake2(&b[..n], &mut a)?;
let (n, device_keys) = device.on_pake3(&a[..n], &mut b)?;
let commissioner_keys = commissioner.on_pake_finished(&b[..n])?;

// Both ends now hold the same three keys.
assert_eq!(commissioner_keys.i2r, device_keys.i2r);

§Matching on an event

Enums this crate reports through are #[non_exhaustive]; enums the specification closes are not. So a match on a protocol state is still checked for completeness — which is where you want to be told about a new variant — and a match on a stream of events does not break when a new one is worth reporting.


Matter® is a registered trademark of the Connectivity Standards Alliance. This project is not affiliated with or endorsed by the Alliance, and nothing here is a certified implementation.

Re-exports§

pub use config::Capacity;
pub use config::Config;
pub use config::DefaultConfig;
pub use config::SubscriptionCapacity;
pub use error::Error;
pub use error::ErrorCode;
pub use error::Result;

Modules§

acl
Who may do what to which element: the Access Control List (Core §6.6).
attestationrustcrypto
Device attestation: proving a device is what it says it is (Core §6.2, §6.3).
bdx
Bulk Data Exchange (Core §11.22): moving a file between two nodes.
carustcrypto
The fabric’s certificate authority needs cert and crypto’s signing. A fabric’s certificate authority (Core §6.5) — issuing the identities a fabric is made of.
certrustcrypto
Matter operational certificates (Core §6.1, §6.5).
clusters
Cluster behaviour, over the shapes in generated (Core ch. 9 and ch. 11).
commissioning
Commissioning: getting a device onto a fabric (Core ch. 5).
config
What the node promises, and how its promises are checked.
crypto
The cryptosuite (Core ch. 3), and where a node’s private keys live.
derrustcrypto
A minimal DER reader and writer, for the ASN.1 that Matter cannot avoid.
discovery
Service advertising and discovery (Core §4.3) — how a Matter node is found.
dm
The data model: what a node has (Core ch. 7).
error
One error type for the whole crate.
exchange
Exchanges and the Message Reliability Protocol (Core §4.10, §4.12).
fabricrustcrypto
Fabrics: the ecosystems a node belongs to, and the identifiers derived from them (Core §2.5.1, §4.3.2.2, §4.17.2, §11.18).
grouprustcrypto
Group communication: one message, many nodes (Core §4.16, §4.17, §4.18).
icdrustcrypto
Intermittently Connected Devices (Core §4.22, §9.16–9.17).
im
The interaction model: how anything actually says anything (Core ch. 8, ch. 10).
jfrustcrypto
Joint Fabric: two ecosystems, one root of trust (Core ch. 12).
messagingrustcrypto
Message processing: a datagram in, a protocol message out (Core §4.7).
msg
The Matter message frame: headers, identifiers, and the counters that keep a message from being replayed.
platform
The seams between this crate and the machine it runs on.
sc
The Secure Channel protocol: session establishment and status (Core §4.11, §4.14).
sessionrustcrypto
Secure sessions: what PASE and CASE produce, and what every later message rides on (Core §4.13).
sync
Shared state for a controller that runs on more than one thread.
tlv
Matter TLV — the tag-length-value encoding of Core Appendix A.
transport
The transports underneath the message layer.

Constants§

DATA_MODEL_REVISION
The Data Model revision this crate implements — §7.1.1’s revision 21, “Added Revision conformance”.
PORT
The IANA-assigned UDP port for Matter (Core §2.5.6.3).
SPECIFICATION_VERSION
The Matter specification version this crate implements, in the encoding of the Basic Information cluster’s SpecificationVersion attribute (Core §11.1.5.22).