GroupKeyManagement Cluster

Cluster ID: 0x003F  |  Endpoint: Endpoint 0 (Root Endpoint)

GroupKeyManagement manages the encryption keys used for multicast communication in Matter networks. When you need to send commands to a group of devices simultaneously (e.g., "turn off all living room lights"), devices need to share a set of symmetric keys to encrypt and verify multicast messages. This Cluster is used to write, read, delete, and maintain these key sets.

Commands

The GroupKeyManagement Cluster has 4 commands for managing the complete lifecycle of key sets (KeySets): write, read, delete, and enumerate. Click a command ID in the table below to jump to its detailed description.

KeySetWrite — Write Key Set(0x00)

Writes a complete key set (GroupKeySet) to the device. If the specified GroupKeySetID already exists, it is updated. Each key set contains up to three Epoch keys to support smooth transitions during key rotation.

↑ Back to Commands

KeySetRead — Read Key Set(0x01)

Reads key set information for the specified ID. Returns KeySetReadResponse, containing the key set's metadata (ID, security policy, Epoch start times) but not the plaintext keys.

KeySetReadResponse

↑ Back to Commands

KeySetRemove — Delete Key Set(0x03)

Deletes the key set with the specified ID. Before deletion, ensure no GroupKeyMap entries still reference this key set, otherwise the associated groups will be unable to send or receive encrypted multicast messages properly.

↑ Back to Commands

KeySetReadAllIndices — List All Key Sets(0x04)

Lists all stored key set IDs under the current Fabric. Returns KeySetReadAllIndicesResponse. No parameters required.

KeySetReadAllIndicesResponse

↑ Back to Commands

Attributes

The GroupKeyManagement Cluster has 4 application attributes. Click an attribute ID in the summary table below to jump to its detailed description.

GroupKeyMap — Group Key Mapping(0x0000)

This is the most core attribute of this Cluster. It defines the mapping of "which group uses which key set." Each entry associates a GroupId with a GroupKeySetID, and the device uses this mapping to select the key for encrypting and decrypting multicast messages.

Writable attribute — the management side can write directly to establish or modify mappings. A key set can be shared by multiple groups, or each group can be assigned an independent key set.

GroupKeyMapStruct Structure

↑ Back to Attributes

GroupTable — Group Information Table(0x0001)

Read-only attribute displaying detailed information for all registered groups on the device. This table is automatically maintained by the device based on Groups Cluster operations and GroupKeyMap; it cannot be written to directly.

GroupTableStruct Structure

↑ Back to Attributes

MaxGroupsPerFabric — Max Groups(0x0002)

Read-only attribute indicating the maximum number of groups each Fabric can register. This is a hardware/firmware limit of the device; the management side should reference this value when planning multicast topology.

↑ Back to Attributes

MaxGroupKeysPerFabric — Max Key Sets(0x0003)

Read-only attribute indicating the maximum number of key sets each Fabric can store. Including the IPK (ID = 0). If the value is 3, then besides the IPK, 2 custom key sets can be stored.

↑ Back to Attributes

Data Structures

GroupKeySetStruct (Key Set Structure)

Describes a complete multicast key set. Contains the key set ID, security policy, and up to three groups of Epoch keys with their start times. Three Epoch slots support key rotation — the device can hold both old and new keys simultaneously for seamless switching.

Enum Types

GroupKeySecurityPolicyEnum (Security Policy)

Defines the security verification policy used by the key set. Determines how the device verifies the trustworthiness of multicast message sources.

Feature Bitmap

The GroupKeyManagement Cluster declares the device's supported advanced capabilities through FeatureMap (0xFFFC):

Example Data

Attribute read results of the GroupKeyManagement Cluster on a device with two configured groups:

{
  // --- GroupKeyMap (Key Mapping Table) ---
  "0x0000": [
    {
      "GroupId": 1,
      "GroupKeySetID": 1,
      "FabricIndex": 1
    },
    {
      "GroupId": 2,
      "GroupKeySetID": 1,
      "FabricIndex": 1
    }
  ],

  // --- GroupTable (Group Info Table, Read-only) ---
  "0x0001": [
    {
      "GroupId": 1,
      "Endpoints": [1, 2],
      "GroupName": "Living Room Lights",
      "FabricIndex": 1
    },
    {
      "GroupId": 2,
      "Endpoints": [3],
      "GroupName": "Bedroom Lights",
      "FabricIndex": 1
    }
  ],

  // --- Capacity Limits ---
  "0x0002": 4,               // MaxGroupsPerFabric = 4
  "0x0003": 3                // MaxGroupKeysPerFabric = 3
}

Common Scenarios

Scenario 1: Establishing Multicast Keys for a Group of Devices

When you need multiple devices to join the same group and support multicast communication:

1. First read the target device's MaxGroupKeysPerFabric (0x0003) to confirm key set quota availability
2. Write the same key set (same GroupKeySetID and EpochKey) to each target device via KeySetWrite (0x00)
3. Write the GroupKeyMap (0x0000) attribute on each device, mapping GroupId to the just-written GroupKeySetID
4. Add the device to the corresponding group via the Groups Cluster's AddGroup command
5. Read GroupTable (0x0001) to confirm group information and Endpoint mapping are correct
6. Now you can send multicast commands to the group, and all member devices can decrypt and execute using the shared key

Scenario 2: Key Rotation

Regularly rotating multicast keys is a security best practice. Matter's three-Epoch mechanism allows rotation to proceed seamlessly:

1. List all current key set IDs via KeySetReadAllIndices (0x04)
2. Read the target key set via KeySetRead (0x01) and check the current Epoch time windows
3. Generate a new 128-bit AES key as the next Epoch key
4. Update the key set via KeySetWrite (0x00) — keep the currently active EpochKey, write the new key into the next Epoch slot, and set a future EpochStartTime
5. Write the same updated key set to each device in the group sequentially
6. After all devices have been updated, when the new EpochStartTime arrives, they automatically switch to the new key
7. After confirming all devices have switched, old Epoch keys no longer in use can be removed (overwritten in the next KeySetWrite)