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, ¶meters.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).
- attestation
rustcrypto - 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.
- ca
rustcrypto - The fabric’s certificate authority needs
certandcrypto’s signing. A fabric’s certificate authority (Core §6.5) — issuing the identities a fabric is made of. - cert
rustcrypto - 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.
- der
rustcrypto - 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).
- fabric
rustcrypto - 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).
- group
rustcrypto - Group communication: one message, many nodes (Core §4.16, §4.17, §4.18).
- icd
rustcrypto - Intermittently Connected Devices (Core §4.22, §9.16–9.17).
- im
- The interaction model: how anything actually says anything (Core ch. 8, ch. 10).
- jf
rustcrypto - Joint Fabric: two ecosystems, one root of trust (Core ch. 12).
- messaging
rustcrypto - 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).
- session
rustcrypto - 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
SpecificationVersionattribute (Core §11.1.5.22).