组密钥管理 Cluster（GroupKeyManagement）

Cluster ID: 0x003F  |  所在 Endpoint: Endpoint 0（根端点）

GroupKeyManagement 负责管理 Matter 网络中用于组播（multicast）通信的加密密钥。 当你需要向一组设备同时发送命令（比如「关闭客厅所有灯」）时，设备之间需要共享一套对称密钥来加密和验证组播消息。 这个 Cluster 就是用来写入、读取、删除和维护这些密钥集的。

命令（Commands）

GroupKeyManagement Cluster 共有 4 个命令，用于管理密钥集（KeySet）的完整生命周期： 写入、读取、删除和列举。点击下方表格中的命令 ID 可跳转到对应的详细说明。

KeySetWrite -- 写入密钥集（0x00）

写入一个完整的密钥集（GroupKeySet）到设备中。如果指定的 GroupKeySetID 已存在，则更新它。 每个密钥集包含最多三个 Epoch 密钥，用于支持密钥轮换时的平滑过渡。

↑ 返回命令列表

KeySetRead -- 读取密钥集（0x01）

读取指定 ID 的密钥集信息。返回 KeySetReadResponse， 其中包含密钥集的元数据（ID、安全策略、各 Epoch 起始时间），但不包含密钥明文。

KeySetReadResponse

↑ 返回命令列表

KeySetRemove -- 删除密钥集（0x03）

删除指定 ID 的密钥集。删除前需要确保没有 GroupKeyMap 条目仍在引用该密钥集， 否则相关组将无法正常收发加密组播消息。

↑ 返回命令列表

KeySetReadAllIndices -- 列举所有密钥集（0x04）

列出当前 Fabric 下所有已存储的密钥集 ID。返回 KeySetReadAllIndicesResponse。 不需要任何参数。

KeySetReadAllIndicesResponse

↑ 返回命令列表

属性详解

GroupKeyManagement Cluster 共有 4 个应用属性。点击下方汇总表中的属性 ID 可跳转到对应的详细说明。

GroupKeyMap -- 组密钥映射（0x0000）

这是本 Cluster 最核心的属性。它定义了「哪个组使用哪个密钥集」的映射关系。 每个条目将一个 GroupId 关联到一个 GroupKeySetID，设备根据这个映射来选择加解密组播消息所用的密钥。

可写属性 —— 管理端可以直接写入来建立或修改映射。 一个密钥集可以被多个组共享，也可以为每个组分配独立的密钥集。

GroupKeyMapStruct 结构

↑ 返回属性列表

GroupTable -- 组信息表（0x0001）

只读属性，展示设备上所有已注册组的详细信息。 这个表由设备根据 Groups Cluster 的操作和 GroupKeyMap 自动维护，不能直接写入。

GroupTableStruct 结构

↑ 返回属性列表

MaxGroupsPerFabric -- 最大组数（0x0002）

只读属性，标识每个 Fabric 最多可以注册多少个组。 这是设备的硬件/固件限制，管理端在规划组播拓扑时需要参考这个值。

↑ 返回属性列表

MaxGroupKeysPerFabric -- 最大密钥集数（0x0003）

只读属性，标识每个 Fabric 最多可以存储多少个密钥集。 包括 IPK（ID = 0）在内。如果值为 3，则除了 IPK 外还能存 2 个自定义密钥集。

↑ 返回属性列表

数据结构

GroupKeySetStruct（密钥集结构体）

描述一个完整的组播密钥集。包含密钥集 ID、安全策略、以及最多三组 Epoch 密钥和对应的起始时间。 三个 Epoch 插槽用于支持密钥轮换 —— 设备可以同时持有旧密钥和新密钥，实现无缝切换。

枚举类型

GroupKeySecurityPolicyEnum（安全策略）

定义密钥集使用的安全验证策略。决定设备如何验证组播消息的来源可信度。

Feature 位图

GroupKeyManagement Cluster 通过 FeatureMap（0xFFFC）声明设备支持的高级能力：

示例数据

一个已配置两个组的设备上，GroupKeyManagement Cluster 的属性读取结果：

{
  // --- GroupKeyMap（密钥映射表）---
  "0x0000": [
    {
      "GroupId": 1,
      "GroupKeySetID": 1,
      "FabricIndex": 1
    },
    {
      "GroupId": 2,
      "GroupKeySetID": 1,
      "FabricIndex": 1
    }
  ],

  // --- GroupTable（组信息表，只读）---
  "0x0001": [
    {
      "GroupId": 1,
      "Endpoints": [1, 2],
      "GroupName": "客厅灯组",
      "FabricIndex": 1
    },
    {
      "GroupId": 2,
      "Endpoints": [3],
      "GroupName": "卧室灯组",
      "FabricIndex": 1
    }
  ],

  // --- 容量限制 ---
  "0x0002": 4,               // MaxGroupsPerFabric = 4
  "0x0003": 3                // MaxGroupKeysPerFabric = 3
}

常见场景

场景 1：为一组设备建立组播密钥

当你需要让多个设备加入同一个组并支持组播通信时：

1. 先读取目标设备的 MaxGroupKeysPerFabric (0x0003)，确认还有密钥集配额
2. 通过 KeySetWrite (0x00) 向每个目标设备写入相同的密钥集（相同的 GroupKeySetID 和 EpochKey）
3. 在每个设备上写入 GroupKeyMap (0x0000) 属性，将 GroupId 映射到刚写入的 GroupKeySetID
4. 通过 Groups Cluster 的 AddGroup 命令将设备加入对应的组
5. 读取 GroupTable (0x0001) 确认组信息和 Endpoint 映射正确
6. 现在可以向该组发送组播命令了，所有成员设备都能用共享密钥解密和执行

场景 2：密钥轮换（Key Rotation）

定期更换组播密钥是安全最佳实践。Matter 的三 Epoch 机制让轮换可以无缝进行：

1. 通过 KeySetReadAllIndices (0x04) 列出当前所有密钥集 ID
2. 通过 KeySetRead (0x01) 读取目标密钥集，检查当前的 Epoch 时间窗口
3. 生成新的 128 位 AES 密钥作为下一个 Epoch 密钥
4. 通过 KeySetWrite (0x00) 更新密钥集 —— 保留当前活跃的 EpochKey，将新密钥写入下一个 Epoch 插槽，设置未来的 EpochStartTime
5. 依次向组内每个设备写入相同的更新后密钥集
6. 等待所有设备都更新完毕后，新 EpochStartTime 到达时自动切换到新密钥
7. 确认所有设备已切换后，可以移除不再使用的旧 Epoch 密钥（通过下一次 KeySetWrite 覆盖）