1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
//! Service advertising and discovery (Core §4.3) — how a Matter node is found.
//!
//! > Service Advertising and Discovery for Matter uses IETF Standard DNS-Based Service
//! > Discovery (DNS-SD) [RFC 6763]. **Matter requires no modifications to IETF Standard
//! > DNS-SD.**
//!
//! That sentence is the shape of this module: everything here is ordinary DNS-SD, and what
//! Matter adds is a naming convention and a set of TXT keys.
//!
//! | Context | Service type | Instance name |
//! |---|---|---|
//! | Commissionable Node (§4.3.1) | `_matterc._udp` | a random 64-bit value, 16 hex digits |
//! | Operational (§4.3.2) | `_matter._tcp` | `<compressed-fabric>-<node-id>` |
//! | Commissioner (§4.3.3) | `_matterd._udp` | vendor's choice |
//!
//! `_matter._tcp` is not a mistake: "the string `_tcp` is boilerplate text inherited from the
//! original DNS SRV specification … and doesn't necessarily mean that the advertised
//! application-layer protocol runs only over TCP" (§4.3.2.3). Matter's operational transport
//! is UDP with MRP.
//!
//! # Why the instance name is random, and why it changes
//!
//! §4.3.1: "the DNS-SD instance name SHALL be a dynamic, pseudo-randomly selected, 64-bit
//! temporary unique identifier … A new instance name SHALL be selected when the Node boots. A
//! new instance name SHALL be selected whenever the Node enters Commissioning mode."
//!
//! A stable name would be a tracking identifier — a device advertising the same sixteen hex
//! digits on every network it ever joins. The rule that it "SHALL NOT change while the Node is
//! in commissioning mode" is the other half: a commissioner that found the device must still
//! be able to reach it.
//!
//! # What is here and what is not
//!
//! The record model, the TXT keys, the DNS wire format, a responder that turns a query into a
//! response, and the *schedule* that says when anything may be sent at all — RFC 6762 §8's
//! probing and announcing, §9's conflict resolution and §6's rate limits, in [`schedule`].
//! [`responder`] decides what a message says; [`schedule`] decides when. Neither owns a socket
//! or a clock: the caller polls, sends, and sleeps until [`Schedule::wake_at`].
//!
//! What is not here: the `std` OS backends (Avahi, systemd-resolved, `dns-sd`) and the SRP
//! client Thread requires — platform code rather than protocol.
//!
//! ```
//! use matter_kit::discovery::{
//! self, CommissionableSubtypes, COMMISSIONABLE_SERVICE,
//! };
//! use matter_kit::discovery::responder::{Advertisement, Responder};
//! use matter_kit::discovery::txt::{CommissionableTxt, CommissioningMode};
//! use matter_kit::msg::VendorId;
//!
//! // §4.3.1.14's own example: discriminator 840, in commissioning mode after an
//! // OpenCommissioningWindow.
//! let txt = CommissionableTxt {
//! discriminator: 840,
//! commissioning_mode: CommissioningMode::Enhanced,
//! ..CommissionableTxt::default()
//! }
//! .encode()?;
//!
//! // The instance name is random and changes whenever the node enters commissioning mode;
//! // the host name comes from a link-layer address.
//! let instance = discovery::commissionable_instance_name(0xDD20_0C20_D25A_E5F7);
//! let host = discovery::host_name(&[0xB7, 0x5A, 0xFB, 0x45, 0x8E, 0xCD])?;
//! assert_eq!(instance.as_str(), "DD200C20D25AE5F7");
//!
//! // `_CM` is derived from the same commissioning mode the TXT key is, so the two cannot
//! // disagree — §4.3.1.3 forbids publishing it when `CM=0`.
//! let subtypes = CommissionableSubtypes::new(840, CommissioningMode::Enhanced);
//! let mut advertisement =
//! Advertisement::new(&instance, COMMISSIONABLE_SERVICE, &host, 11111, txt.finish());
//! for subtype in subtypes.labels() {
//! advertisement = advertisement.with_subtype(subtype)?;
//! }
//! advertisement = advertisement.with_address([
//! 0xFE, 0x80, 0, 0, 0, 0, 0, 0, 0xF5, 0x15, 0x57, 0x6F, 0x97, 0x83, 0x3F, 0x30,
//! ])?;
//!
//! let advertisements = [advertisement];
//! let responder = Responder::new(&advertisements);
//! let mut buf = [0u8; 1024];
//! let announcement = responder.announce(&mut buf)?;
//! assert!(!announcement.is_empty());
//! # Ok::<(), matter_kit::Error>(())
//! ```
pub use ;
pub use ;
pub use ;
pub use ;
use String;
use crate;
/// `_matterc._udp` — Commissionable Node Discovery (§4.3.1).
pub const COMMISSIONABLE_SERVICE: = ;
/// `_matter._tcp` — Operational Discovery (§4.3.2.3).
pub const OPERATIONAL_SERVICE: = ;
/// `_matterd._udp` — Commissioner Discovery (§4.3.3).
pub const COMMISSIONER_SERVICE: = ;
/// `local` — "For link-local Multicast DNS the service domain SHALL be local" (§4.3.1).
pub const LOCAL_DOMAIN: &str = "local";
/// `_sub` — RFC 6763 §7.1's subtype label.
pub const SUBTYPE_LABEL: &str = "_sub";
/// The port Multicast DNS runs on (RFC 6762 §5).
pub const MDNS_PORT: u16 = 5353;
/// `ff02::fb` — RFC 6762's link-local IPv6 multicast group.
///
/// IPv6 only: §4.3 asks that "announcements and answers for this service need only be
/// performed over IPv6", and "A Matter device that only supports IPv6 gets these
/// optimizations automatically, simply by virtue of not supporting IPv4 at all."
pub const MDNS_IPV6_GROUP: = ;
/// RFC 6762 §10's TTL for records that contain a host name — A, AAAA, SRV.
///
/// Two minutes, "so that stale data is quickly purged" when a device moves or its address
/// changes.
pub const HOST_RECORD_TTL: u32 = 120;
/// RFC 6762 §10's TTL for everything else — PTR, TXT.
///
/// Seventy-five minutes. These records do not go stale when an address changes, and a longer
/// TTL is what keeps a quiet network quiet.
pub const OTHER_RECORD_TTL: u32 = 4500;
/// The length of the hexadecimal instance name §4.3.1 and §4.3.2.1 both use.
///
/// Sixteen characters for commissionable discovery's 64-bit random value; thirty-three for
/// operational discovery's `<16>-<16>`.
pub const INSTANCE_NAME_LEN: usize = 16;
/// The longest instance name: operational discovery's `<compressed>-<node>`.
pub const INSTANCE_NAME_MAX: usize = 33;
/// The longest host name: §4.3.1.1's sixteen-character form, for a 64-bit MAC Extended
/// Address.
pub const HOST_NAME_MAX: usize = 16;
/// A commissionable node's instance name — §4.3.1's "dynamic, pseudo-randomly selected,
/// 64-bit temporary unique identifier, expressed as a fixed-length sixteen-character
/// hexadecimal string, encoded as ASCII (UTF-8) text using **capital letters**".
///
/// The randomness is a parameter rather than something this crate draws, for the same reason
/// every other source of entropy is: it comes from the one [`Rng`](crate::platform::Rng) the
/// integrator installed.
/// A node's host name — §4.3.1.1's "fixed-length twelve-character (or sixteen-character)
/// hexadecimal string" built from a link-layer address.
///
/// > In the event that a device performs MAC address randomization for privacy, then the
/// > target host name SHALL use the privacy-preserving randomized version and the hostname
/// > SHALL be updated in the record every time the underlying link-layer address rotates.
///
/// Accepts a 6-octet MAC (Ethernet, Wi-Fi) or an 8-octet MAC Extended Address (Thread).
/// Appends octets as uppercase hexadecimal.
pub
/// A DNS-SD subtype label, as §4.3.1.3 and §4.3.2.3 define them.
///
/// | Subtype | Meaning | Encoding |
/// |---|---|---|
/// | `_L<dddd>` | the full 12-bit discriminator | decimal, no leading zeroes |
/// | `_S<dd>` | its upper four bits | decimal, no leading zeroes |
/// | `_V<ddddd>` | the 16-bit Vendor ID | decimal, no leading zeroes |
/// | `_T<ddd>` | the primary device type | decimal, no leading zeroes |
/// | `_CM` | "currently in Commissioning Mode" | no value |
/// | `_I<hhhh>` | the Compressed Fabric Identifier | **exactly 16 uppercase hex** |
///
/// The two encodings are not interchangeable, and the difference is easy to miss: every
/// commissionable subtype is *decimal with leading zeroes omitted*, while the operational one
/// is *fixed-width hexadecimal*. A subtype in the wrong form is a name nobody browses for, and
/// the device is simply never found.
pub const SUBTYPE_MAX: usize = 18;
/// `_L<dddd>` — the long discriminator subtype (§4.3.1.3).
/// `_S<dd>` — the short discriminator subtype: "the upper 4 bits of the discriminator".
/// `_V<ddddd>` — the Vendor ID subtype.
/// `_T<ddd>` — the primary device type subtype.
/// `_CM` — "currently in Commissioning Mode".
///
/// §4.3.1.3: "the subtype is `_CM` regardless of whether the TXT record for commissioning mode
/// is set to 1 (CM=1), 2 (CM=2) or 3 (CM=3). A Commissionee that is not in commissioning mode
/// (CM=0) SHALL NOT publish this subtype."
pub const COMMISSIONING_MODE_SUBTYPE: &str = "_CM";
/// `_IC` — Incomplete Commissioning (§4.3.2.5), for NFC-based commissioning.
pub const INCOMPLETE_COMMISSIONING_SUBTYPE: &str = "_IC";
/// Appends a decimal number "omitting any leading zeroes" — which for zero means the single
/// digit `0`, not the empty string.
pub
/// Builds a commissionable advertisement's subtypes from what §4.3.1.3 says to publish.
///
/// The five subtypes are not independent: `_CM` appears only in commissioning mode, `_V` and
/// `_T` only if the device chooses to publish them at all ("a vendor MAY choose not to include
/// it at all, for privacy reasons"), and the two discriminator subtypes always. Assembling
/// them in one place is what keeps a device from publishing `_CM` while advertising `CM=0`,
/// which §4.3.1.3 forbids and which nothing else would catch.
/// The operational subtype for a fabric — `_I<hhhh>`, "exactly 16 uppercase hexadecimal
/// characters" (§4.3.2.3).
///
/// Not decimal, unlike every commissionable subtype, and not variable-width. A subtype in the
/// wrong form is a name nobody browses for, and the node is simply never found on its fabric.
///
/// [`CompressedFabricId::subtype`](crate::fabric::CompressedFabricId::subtype) is the same
/// value; this is here so the two naming conventions sit side by side, where the difference
/// between them is visible.