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
Sizing is a type, not a build flag. Every table in the stack — fabrics, sessions,
exchanges, subscriptions, access-control entries — is a fixed-capacity array whose
length comes from an associated constant on Config. The specification’s minima
(Core §2.11) are const assertions, so a configuration that could not pass
certification does not compile. Two libraries in one binary cannot fight over it the
way they fight over a Cargo feature.
use matter_kit::{Config, DefaultConfig};
struct Small;
impl Config for Small {
const FABRICS: usize = 5; // Core §11.18.5.3 constrains this to 5..=254
const SESSIONS: usize = 16;
// …everything else defaults.
}
assert!(Small::ACL_ENTRIES >= 4 * Small::FABRICS); // Core §2.11.1.1No 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::Config;pub use config::DefaultConfig;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
- How big everything is.
- 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).