Skip to main content

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}