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
//! Group communication: one message, many nodes (Core §4.16, §4.17, §4.18).
//!
//! Needs the `rustcrypto` feature: every operational group key is derived with
//! [`crypto`](crate::crypto)'s KDF from [`fabric`](crate::fabric)'s compressed identifier.
//!
//! A wall switch that controls twenty lights cannot send twenty messages. §4.16 is the
//! alternative: one IPv6 multicast datagram addressed by a 16-bit **Group ID**, encrypted under
//! a symmetric key every member of the group holds.
//!
//! That one sentence is also the whole of the difficulty. A group message has no session, no
//! exchange, no acknowledgement and no reply — so everything a unicast session gives for free
//! has to be rebuilt:
//!
//! * **Which key?** §4.17.3.6's [`Group Session ID`](session_id) narrows the candidates, and
//! narrowing is all it does: "It SHALL NOT be used as the sole means to locate the associated
//! Operational Group Key, since it MAY collide within the fabric." Every candidate is tried
//! until the MIC passes.
//! * **Is it fresh?** There is no handshake to agree a starting counter, so §4.18's
//! [`PeerTable`] tracks one per sender, and the [`GroupKeySecurityPolicy`] on the key chooses
//! between trusting the first counter seen and synchronising over [`mcsp`].
//! * **Who sent it?** §4.16.1's [`GroupContext`] — fabric, group, source node — is what the
//! layer above is given in place of a session.
//!
//! # Keys are derived, not distributed
//!
//! §4.17.2: an **epoch key** is what an administrator installs, and the key a message is
//! actually encrypted under is
//! [`operational_group_key`](crate::fabric::operational_group_key) — the epoch key salted with
//! the fabric's compressed identifier. So the same epoch key gives different operational keys on
//! different fabrics, and a node that is removed from a group simply stops being sent new epoch
//! keys: §4.17.3, "denying access to updated versions of these keys serves as a means to eject
//! group members".
//!
//! A **key set** holds up to three epoch keys with start times, which is what makes rotation
//! possible without a flag day: a sender uses the newest key whose start time has passed, and a
//! receiver accepts "any key derived from one of the currently installed epoch keys", future
//! start times included.
//!
//! ```
//! use matter_kit::fabric::CompressedFabricId;
//! use matter_kit::group;
//!
//! // §4.17.2's worked example, and §4.17.3.6's, which continues it.
//! let epoch = [
//! 0x23, 0x5b, 0xf7, 0xe6, 0x28, 0x23, 0xd3, 0x58,
//! 0xdc, 0xa4, 0xba, 0x50, 0xb1, 0x53, 0x5f, 0x4b,
//! ];
//! let compressed = CompressedFabricId(0x87E1_B004_E235_A130);
//! let operational = matter_kit::fabric::operational_group_key(
//! &matter_kit::crypto::SymmetricKey::new(epoch),
//! compressed,
//! )?;
//! assert_eq!(operational.as_bytes()[..2], [0xa6, 0xf5]);
//! assert_eq!(group::session_id(&operational)?, 0xB9F7);
//! # Ok::<(), matter_kit::Error>(())
//! ```
pub use ;
pub use ;
pub use ;
pub use ;
use crate;
use crateResult;
use crate;
use cratePeerAddr;
/// §4.17.3.6's `Info`: the ASCII of `"GroupKeyHash"`.
pub const GROUP_KEY_HASH_INFO: & = b"GroupKeyHash";
/// The IANA-assigned site-scoped multicast address for Matter, `FF05::FA` (§2.5.6.2).
///
/// Required of "any device supporting the Groupcast cluster, whether as a Listener or Sender",
/// and the one address that does not depend on the fabric.
pub const IANA_MULTICAST: PeerAddr =
new;
/// §4.17.3.6's Group Session ID: which operational keys *might* have encrypted a message.
///
/// > The Group Session ID MAY help receiving nodes efficiently locate the Operational Group Key
/// > used to encrypt an incoming groupcast message. It SHALL NOT be used as the sole means to
/// > locate the associated Operational Group Key, since it MAY collide within the fabric.
///
/// Sixteen bits derived from the key, read big-endian — "GroupSessionId is computed by
/// considering the GroupKeyHash as a Big-Endian value" — which is the opposite of every other
/// scalar in the message header and the one thing to get wrong here.
/// §2.5.6.2's per-group IPv6 multicast address, `FF35:0040:FD<Fabric ID>00:<Group ID>`.
///
/// A unicast-prefix-based multicast address (RFC 3306) with site-local scope, so that "a low
/// probability of a node receiving a multicast message it is not interested in" comes from the
/// address rather than from decrypting everything. A collision needs two identical 64-bit
/// fabric ids *and* two identical group ids, and even then the MIC disambiguates.
/// §4.16.1's Groupcast Session Context: what a group message carries in place of a session.
///
/// > Together, Fabric Index, Group ID and Source Node ID comprise a unique identifier that
/// > upper layers may use to understand the source and destination of groupcast messages.
///
/// Built fresh on every message — "on ingress of each groupcast message, the following ephemeral
/// context SHALL be constructed" — because a group session is not a thing that is established,
/// only a membership that happens to still hold.