matter_kit/commissioning/window.rs
1//! The commissioning window: node state three clusters share (Core §11.19.7).
2//!
3//! §11.19 opens and revokes it, §11.10.7.2 gives a PASE commissioner priority over a CASE
4//! administrator *while it is open*, and §11.10.7.6 step 2 closes it on
5//! `CommissioningComplete`. A flag per cluster would be three answers to "is a window open",
6//! and the priority rule is exactly where they would disagree — so it lives here, beside the
7//! fail-safe, and the clusters borrow it.
8//!
9//! # The PAKE material is bytes, not a verifier
10//!
11//! [`EphemeralVerifier`] holds the ninety-seven octets and the PBKDF parameters, not a
12//! decoded [`Spake2pVerifierData`](crate::crypto::Spake2pVerifierData). That is not laziness:
13//! it keeps this module free of cryptography, so a `no_std` build without the `rustcrypto`
14//! feature still has a window. The *validation* §11.19.8.1 requires happens in the cluster,
15//! which has the cryptography — and having happened, `Spake2pVerifierData::from_bytes` on
16//! these octets cannot fail.
17
18use heapless::Vec;
19
20use crate::msg::{FabricIndex, VendorId};
21use crate::platform::Instant;
22
23/// `CommissioningWindowStatusEnum` (§11.19.5.1).
24#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, Default)]
25#[repr(u8)]
26pub enum WindowStatus {
27 /// `0` — no commissioning window is open.
28 ///
29 /// §11.19.7.1's note is worth keeping in mind: "An initial commissioning window is not
30 /// opened using either the OpenCommissioningWindow command or the
31 /// OpenBasicCommissioningWindow command, and therefore this attribute SHALL be set to
32 /// WindowNotOpen on initial commissioning." A factory-new device reads zero here while
33 /// being perfectly commissionable.
34 #[default]
35 NotOpen = 0,
36 /// `1` — an Enhanced Commissioning Method window is open.
37 EnhancedOpen = 1,
38 /// `2` — a Basic Commissioning Method window is open. Requires the `BC` feature.
39 BasicOpen = 2,
40}
41
42impl WindowStatus {
43 /// The value the attribute carries.
44 #[must_use]
45 pub const fn value(self) -> u8 {
46 self as u8
47 }
48
49 /// Whether a window is open at all.
50 #[must_use]
51 pub const fn is_open(self) -> bool {
52 !matches!(self, Self::NotOpen)
53 }
54}
55
56/// §11.19.8.1's `PAKEPasscodeVerifier` length — `w0 || L`, exactly 97 octets.
57pub const PAKE_VERIFIER_LEN: usize = 97;
58
59/// §3.9's longest PBKDF salt.
60pub const SALT_MAX: usize = 32;
61
62/// An open commissioning window (§11.19.7).
63#[derive(Debug, Clone)]
64pub struct OpenWindow {
65 /// Which method opened it.
66 pub status: WindowStatus,
67 /// When it closes. §11.19.8.1.1: the timeout "applies only to cessation of any
68 /// announcements and to accepting of new commissioning sessions; it does not apply to
69 /// abortion of connections".
70 pub expires_at: Instant,
71 /// `AdminFabricIndex` — "the FabricIndex associated with the Fabric scoping of the
72 /// Administrator that opened the window".
73 ///
74 /// "If, during an open commissioning window, the fabric for the Administrator that opened
75 /// the window is removed, then this attribute SHALL be set to null" — which is why it is
76 /// an `Option` even while the window is open.
77 pub admin_fabric: Option<FabricIndex>,
78 /// `AdminVendorId`. Unlike the fabric index, this one is *not* cleared when the fabric
79 /// goes: "If the fabric for the Administrator that opened the window is removed from the
80 /// node while the commissioning window is still open, this attribute SHALL NOT be
81 /// updated." A user looking at the device still learns who opened it.
82 pub admin_vendor: Option<VendorId>,
83 /// `Discriminator` — "used by the Node as the long discriminator for DNS-SD
84 /// advertisement … for discovery by the new Administrator".
85 pub discriminator: u16,
86 /// The ephemeral PAKE verifier and its PBKDF parameters, for an Enhanced window.
87 ///
88 /// `None` for a Basic window, which runs against the device's own factory verifier.
89 pub ephemeral: Option<EphemeralVerifier>,
90}
91
92/// The PAKE material an `OpenCommissioningWindow` installed.
93///
94/// "It SHALL be deleted by the Node at the end of commissioning or expiration of the
95/// OpenCommissioningWindow command" — which is what [`CommissioningWindow::close`] does, and
96/// why this is owned by the window rather than handed to the device.
97///
98/// Zeroized on drop: `(w0, L)` is not a passcode, but it is what a PASE session is
99/// authenticated by for as long as the window lasts, and leaving it in freed memory would
100/// outlive the window it belongs to.
101#[derive(Debug, Clone, zeroize::Zeroize, zeroize::ZeroizeOnDrop)]
102pub struct EphemeralVerifier {
103 /// `(w0 || L)`, from the command's `PAKEPasscodeVerifier` field — already validated by
104 /// the cluster that accepted it.
105 pub verifier: [u8; PAKE_VERIFIER_LEN],
106 /// The PAKE iteration count to answer a `PBKDFParamRequest` with.
107 #[zeroize(skip)]
108 pub iterations: u32,
109 /// The PAKE salt to answer a `PBKDFParamRequest` with.
110 #[zeroize(skip)]
111 pub salt: Vec<u8, SALT_MAX>,
112}
113
114/// The node's commissioning window.
115#[derive(Debug, Default)]
116pub struct CommissioningWindow {
117 open: Option<OpenWindow>,
118}
119
120impl CommissioningWindow {
121 /// Installs a window. The cluster that calls this has already checked §11.19's
122 /// preconditions; this is the state change they guard.
123 pub fn install(&mut self, window: OpenWindow) {
124 self.open = Some(window);
125 }
126
127 /// A closed window — what a device boots with.
128 #[must_use]
129 pub const fn new() -> Self {
130 Self { open: None }
131 }
132
133 /// The window, if one is open as of `now`.
134 ///
135 /// Expiry is lazy, as everywhere else in this crate: a caller that never asks never learns,
136 /// and a device drives it from [`CommissioningWindow::deadline`].
137 #[must_use]
138 pub fn open(&self, now: Instant) -> Option<&OpenWindow> {
139 self.open.as_ref().filter(|window| now < window.expires_at)
140 }
141
142 /// `WindowStatus` (§11.19.7.1).
143 ///
144 /// "This attribute SHALL revert to WindowNotOpen upon expiry of a commissioning window."
145 #[must_use]
146 pub fn status(&self, now: Instant) -> WindowStatus {
147 self.open(now).map_or(WindowStatus::NotOpen, |w| w.status)
148 }
149
150 /// When the window closes, if one is open.
151 #[must_use]
152 pub fn deadline(&self) -> Option<Instant> {
153 self.open.as_ref().map(|window| window.expires_at)
154 }
155
156 /// Closes the window and destroys the ephemeral verifier with it.
157 ///
158 /// §11.19.8.1: the verifier "SHALL be deleted by the Node at the end of commissioning or
159 /// expiration of the OpenCommissioningWindow command". Dropping [`EphemeralVerifier`] is
160 /// what does it — it is `ZeroizeOnDrop`, so the material is wiped rather than merely
161 /// forgotten.
162 pub fn close(&mut self) {
163 self.open = None;
164 }
165
166 /// Clears `AdminFabricIndex` when the administrator's fabric is removed (§11.19.7.2).
167 ///
168 /// The vendor id stays: §11.19.7.3 is explicit that it "SHALL NOT be updated".
169 pub fn forget_fabric(&mut self, fabric: FabricIndex) {
170 if let Some(window) = self.open.as_mut()
171 && window.admin_fabric == Some(fabric)
172 {
173 window.admin_fabric = None;
174 }
175 }
176
177 /// The PAKE material a PASE responder should use for this window.
178 ///
179 /// `None` means "use the device's own factory verifier" — a Basic window, or no window at
180 /// all. A device must still check [`CommissioningWindow::status`] before accepting a PASE
181 /// session; this only says *which* verifier applies.
182 #[must_use]
183 pub fn ephemeral(&self, now: Instant) -> Option<&EphemeralVerifier> {
184 self.open(now)?.ephemeral.as_ref()
185 }
186}