matter_kit/lib.rs
1//! A Matter implementation in Rust: one crate, `no_std`, no allocation, and no runtime of
2//! its own.
3//!
4//! [Matter](https://csa-iot.org/all-solutions/matter/) is the CSA's smart-home standard —
5//! the protocol behind Apple Home, Google Home, Alexa and SmartThings. This crate targets
6//! **specification 1.6** (approved 2026-06-16) and is built to be *certifiable* rather
7//! than merely interoperable: the same data model the certification Test Harness reads is
8//! the data model this crate is generated from.
9//!
10//! # Status
11//!
12//! Under construction and pre-1.0. A device can be commissioned into a fabric end to end,
13//! answer Reads, Writes and Invokes against a `const` data model, hold subscriptions,
14//! enforce §6.6's access control, and advertise itself over DNS-SD — with
15//! [`messaging`] composing the layers, so a datagram finds its session, exchange and
16//! protocol. What is missing is the application clusters. The
17//! [README](https://github.com/hupe1980/matter-kit#status) carries the layer-by-layer table;
18//! each module here states which sections it implements.
19//!
20//! # Three things that shape the whole crate
21//!
22//! **Sizing is a type, not a build flag.** Every table in the stack — fabrics, sessions,
23//! exchanges, subscriptions, access-control entries — is a fixed-capacity array whose
24//! length comes from an associated constant on [`Config`]. The specification's minima
25//! (Core §2.11) are `const` assertions, so a configuration that could not pass
26//! certification does not compile. Two libraries in one binary cannot fight over it the
27//! way they fight over a Cargo feature.
28//!
29//! ```
30//! use matter_kit::{Config, DefaultConfig};
31//!
32//! struct Small;
33//! impl Config for Small {
34//! const FABRICS: usize = 5; // Core §11.18.5.3 constrains this to 5..=254
35//! const SESSIONS: usize = 16;
36//! // …everything else defaults.
37//! }
38//! assert!(Small::ACL_ENTRIES >= 4 * Small::FABRICS); // Core §2.11.1.1
39//! # let _ = DefaultConfig::FABRICS;
40//! ```
41//!
42//! **No runtime is chosen for you.** The crate is `async` over [`core::future`] and talks
43//! to the outside world through the traits in [`platform`]: sockets, timers, randomness,
44//! storage, cryptography. Embassy and Tokio appear in `examples/`, never in the dependency
45//! tree. One consequence worth having: every timeout in the specification — MRP backoff,
46//! the fail-safe, an intermittently-connected device's idle period — is driven by a
47//! [`platform::Timer`], so [`platform::sim`] runs an hour-long scenario in microseconds.
48//!
49//! **Nothing panics on network input.** `unwrap`, `expect`, `panic!` and slice indexing
50//! are denied crate-wide; every parser returns [`Error`]. Resource exhaustion is a value
51//! ([`ErrorCode::NoSpace`], [`ErrorCode::Busy`]), so a device that runs out of exchanges
52//! answers rather than aborts.
53//!
54//! # Commissioning, in miniature
55//!
56//! The whole of PASE: a printed passcode becomes three shared keys, without the passcode
57//! ever crossing the wire. Needs the `rustcrypto` feature, which is on by default.
58//!
59//! ```
60//! # #[cfg(feature = "rustcrypto")]
61//! # fn demo() -> Result<(), matter_kit::Error> {
62//! use matter_kit::crypto::Spake2pVerifierData;
63//! use matter_kit::msg::SessionId;
64//! use matter_kit::sc::{PaseInitiator, PaseResponder, PbkdfParameters, ResponderConfig};
65//!
66//! // What a factory burns into the device. The passcode itself is never stored.
67//! let parameters = PbkdfParameters::new(1_000, b"SPAKE2P Key Salt")?;
68//! let verifier =
69//! Spake2pVerifierData::from_passcode(20_202_021, ¶meters.salt, parameters.iterations)?;
70//!
71//! let mut device = PaseResponder::new(
72//! ResponderConfig { verifier, parameters: parameters.clone(), session_params: None },
73//! SessionId(1),
74//! );
75//! let mut commissioner =
76//! PaseInitiator::new(20_202_021, SessionId(2), Some(parameters), None);
77//!
78//! let (mut a, mut b) = ([0u8; 512], [0u8; 512]);
79//! let n = commissioner.start(&[0x11; 32], &mut a)?;
80//! let n = device.on_pbkdf_param_request(&a[..n], &[0x22; 32], &mut b)?;
81//! let n = commissioner.on_pbkdf_param_response(&b[..n], &[0x33; 32], &mut a)?;
82//! let n = device.on_pake1(&a[..n], &[0x44; 32], &mut b)?;
83//! let n = commissioner.on_pake2(&b[..n], &mut a)?;
84//! let (n, device_keys) = device.on_pake3(&a[..n], &mut b)?;
85//! let commissioner_keys = commissioner.on_pake_finished(&b[..n])?;
86//!
87//! // Both ends now hold the same three keys.
88//! assert_eq!(commissioner_keys.i2r, device_keys.i2r);
89//! # Ok(())
90//! # }
91//! # fn main() {
92//! # #[cfg(feature = "rustcrypto")]
93//! # demo().expect("the exchange completes");
94//! # }
95//! ```
96//!
97//! # Matching on an event
98//!
99//! Enums this crate *reports* through are `#[non_exhaustive]`; enums the **specification**
100//! closes are not. So a `match` on a protocol state is still checked for completeness —
101//! which is where you want to be told about a new variant — and a `match` on a stream of
102//! events does not break when a new one is worth reporting.
103//!
104//! ---
105//!
106//! Matter® is a registered trademark of the Connectivity Standards Alliance. This project
107//! is not affiliated with or endorsed by the Alliance, and nothing here is a certified
108//! implementation.
109
110#![cfg_attr(not(feature = "std"), no_std)]
111#![cfg_attr(docsrs, feature(doc_cfg))]
112// The crate-wide `deny` list in `Cargo.toml` is aimed at code that faces the network.
113// Test code faces a test: `unwrap` there is a legible assertion, and writing
114// `let Some(x) = .. else { panic!() }` around every fixture buys nothing and hides the
115// intent. The denials stay in force for everything that ships.
116#![cfg_attr(
117 test,
118 allow(
119 clippy::unwrap_used,
120 clippy::expect_used,
121 clippy::panic,
122 clippy::indexing_slicing,
123 clippy::arithmetic_side_effects,
124 )
125)]
126
127#[cfg(feature = "alloc")]
128extern crate alloc;
129
130mod bytes;
131
132pub mod acl;
133#[cfg(feature = "rustcrypto")]
134pub mod attestation;
135pub mod bdx;
136/// The fabric's certificate authority needs [`cert`] and [`crypto`]'s signing.
137#[cfg(feature = "rustcrypto")]
138#[cfg_attr(docsrs, doc(cfg(feature = "rustcrypto")))]
139pub mod ca;
140#[cfg(feature = "rustcrypto")]
141pub mod cert;
142pub mod clusters;
143pub mod commissioning;
144pub mod config;
145pub mod crypto;
146#[cfg(feature = "rustcrypto")]
147pub mod der;
148pub mod discovery;
149pub mod dm;
150pub mod error;
151pub mod exchange;
152#[cfg(feature = "rustcrypto")]
153pub mod fabric;
154#[cfg(feature = "rustcrypto")]
155#[cfg_attr(docsrs, doc(cfg(feature = "rustcrypto")))]
156pub mod group;
157#[cfg(feature = "rustcrypto")]
158#[cfg_attr(docsrs, doc(cfg(feature = "rustcrypto")))]
159pub mod icd;
160pub mod im;
161#[cfg(feature = "rustcrypto")]
162#[cfg_attr(docsrs, doc(cfg(feature = "rustcrypto")))]
163pub mod jf;
164#[cfg(feature = "rustcrypto")]
165#[cfg_attr(docsrs, doc(cfg(feature = "rustcrypto")))]
166pub mod messaging;
167pub mod msg;
168pub mod platform;
169pub mod sc;
170#[cfg(feature = "rustcrypto")]
171pub mod session;
172pub mod sync;
173pub mod tlv;
174pub mod transport;
175
176pub use config::{Config, DefaultConfig};
177pub use error::{Error, ErrorCode, Result};
178
179/// The Matter specification version this crate implements, in the encoding of the Basic
180/// Information cluster's `SpecificationVersion` attribute (Core §11.1.5.22).
181///
182/// The four component bytes are major, minor, patch and reserved: `0x01_06_00_00` is
183/// 1.6.0. A larger value is newer.
184pub const SPECIFICATION_VERSION: u32 = 0x0106_0000;
185
186/// The Data Model revision this crate implements — §7.1.1's revision 21, "Added Revision
187/// conformance".
188///
189/// §11.1.5.1 requires a node to report "the revision number of the Data Model against which
190/// the Node is certified", and "one of the valid values listed in Section 7.1.1". The table
191/// grew by one between releases and the split is easy to miss: 1.5.1 ends at
192/// `20 — Removed P quality and added Revision conformance`, and 1.6 divides that single row
193/// into `20 — Removed P quality` and `21 — Added Revision conformance`. A 1.6 node reports
194/// 21; carrying 20 forward advertises a 1.5.1 data model.
195///
196/// It lives here rather than in the Basic Information cluster because it is also
197/// `DATA_MODEL_REVISION` in the `session-parameter-struct` of §4.13.1, which is exchanged
198/// long before any cluster is readable. `clusters::basic_information` re-exports it.
199pub const DATA_MODEL_REVISION: u16 = 21;
200
201/// The IANA-assigned UDP port for Matter (Core §2.5.6.3).
202pub const PORT: u16 = 5540;
203
204/// The README's `rust` blocks, compiled as doctests.
205///
206/// Under `cfg(doctest)` only, so the README is not pulled into the crate's own
207/// documentation — this exists so a landing-page example cannot quietly stop compiling.
208#[cfg(doctest)]
209#[doc = include_str!("../README.md")]
210struct Readme;
211
212#[cfg(test)]
213mod tests {
214 use super::*;
215
216 #[test]
217 fn specification_version_is_1_6_0() {
218 assert_eq!(SPECIFICATION_VERSION.to_be_bytes(), [1, 6, 0, 0]);
219 }
220
221 /// The three revisions a peer reads out of `session-parameter-struct` (§4.13.1) move
222 /// independently of each other and of the crate version, and each is a number taken from
223 /// a table in a PDF. Asserting them here is what makes a spec uplift that forgets one
224 /// fail loudly: 1.6 split §7.1.1's last row and `DATA_MODEL_REVISION` silently stayed at
225 /// its 1.5.1 value until this test existed.
226 #[test]
227 fn the_revision_constants_are_the_1_6_values() {
228 // Core §7.1.1, last row: "21 — Added Revision conformance".
229 assert_eq!(DATA_MODEL_REVISION, 21);
230 // Core §8.1.1, last row: "13 — Added WildcardFilterConfigurationVersion (Matter 1.3)".
231 assert_eq!(crate::im::INTERACTION_MODEL_REVISION, 13);
232 // Core §11.1.5.22, as four component bytes.
233 assert_eq!(SPECIFICATION_VERSION, 0x0106_0000);
234 }
235}