Matter Cluster 63 — Group Key Management Cluster

Cluster Identity

Revision history

Shadow Path Format

Cluster 63 values in the device shadow use this format:

endpoint_id / 63 / attribute_id

Example:

{
  "0/63/2": 1
}

Cluster 63 Features

The FeatureMap attribute (0/63/65532) is a bitmap. Each bit set means the device implements that feature and the attributes and commands that depend on it.

Example: FeatureMap = 0 means no optional feature is enabled; 3 means every feature listed above is enabled.

Data Types

GroupKeyMulticastPolicyEnum

GroupKeySecurityPolicyEnum

GroupInfoMapStruct (struct) — fabric-scoped

GroupKeyMapStruct (struct) — fabric-scoped

GroupKeySetStruct (struct) — fabric-scoped

GroupcastAdoptionStruct (struct) — fabric-scoped

Cluster 63 Attributes

Cluster 63 defines 5 attributes plus the global attributes. Conformance: M mandatory, O optional, a feature code means "mandatory when that feature is present", square brackets mean "optional when …".

Global attributes

Attribute Details

Attribute 0 / 0x0000 — GroupKeyMap

Path example:

0/63/0

If the GCAST feature bit is set in the FeatureMap attribute, the following rules apply to the accessing Fabric: - When Groupcast is adopted (the GroupcastAdoption entry has GroupcastAdopted set to true): - This attribute is empty. - Any attempt to write to this attribute must fail with an INVALID_IN_STATE status code. - Otherwise (Groupcast is not adopted or the entry is missing): - This attribute contains the Group Key Set mappings derived from the Groupcast cluster's Membership attribute (one mapping per group per fabric). - GroupKeyMapStruct entry updates must cause the associated Groupcast cluster's Membership attribute (by GroupID) to be updated with the provided GroupKeySetID.

Each entry is a GroupKeyMapStruct (see Data Types).

Example:

{
  "0/63/0": []
}

Attribute 1 / 0x0001 — GroupTable

Path example:

0/63/1

If the GCAST feature is set in the FeatureMap: - If the GroupcastAdoption attribute has an entry for the accessing Fabric and that entry has the GroupcastAdopted field set to true, then this field is empty. - Else this attribute contains the Group mappings computed in equivalence to the Groupcast cluster's Membership attribute (one mapping per group per fabric). This attribute is a list of GroupInfoMapStruct entries. Each entry provides read-only information about how a given logical Group ID maps to a particular set of endpoints, and a name for the group.

Each entry is a GroupInfoMapStruct (see Data Types).

Example:

{
  "0/63/1": []
}

Attribute 2 / 0x0002 — MaxGroupsPerFabric

Path example:

0/63/2

If the Groupcast support is enabled (GCAST feature is set), this is set to 0 indicating group management is done using the Groupcast cluster and not the legacy Groups cluster. Indicates the maximum number of legacy groups that this node supports per fabric. For legacy usage, the value of this attribute is set to be no less than the required minimum supported groups. The length of the GroupKeyMap and GroupTable list attributes must NOT exceed the value of the MaxGroupsPerFabric attribute multiplied by the number of supported fabrics.

Example:

{
  "0/63/2": 1
}

Attribute 3 / 0x0003 — MaxGroupKeysPerFabric

Path example:

0/63/3

Indicates the maximum number of group key sets this node supports per fabric. The value of this attribute is set according to the minimum number of group key sets to support.

Example:

{
  "0/63/3": 1
}

Attribute 4 / 0x0004 — GroupcastAdoption

Path example:

0/63/4

Indicates whether the accessing fabric claims to have migrated to Groupcast. When a Fabric's entry has the GroupcastAdopted field set to true, the behavior of the GroupKeyMap and GroupTable attributes will change. There must NOT be more than 1 entry per fabric in this attribute. If a Fabric has not yet written an entry for themselves, the server must act as if that Fabric had written an entry with GroupcastAdopted set to false, even if not present in the list.

Each entry is a GroupcastAdoptionStruct (see Data Types).

Example:

{
  "0/63/4": []
}

Cluster 63 Commands

Cluster 63 has 4 client-to-server commands and 2 responses.

AcceptedCommandList

The AcceptedCommandList attribute lists the command IDs the endpoint actually implements:

endpoint_id / 63 / 65529

{
  "0/63/65529": [
    0,
    1,
    3,
    4
  ]
}

Bridge Command Payload Format

The bridge accepts Matter commands in this structure:

{
  "message_id": "1",
  "command": "device_command",
  "args": {
    "endpoint_id": 0,
    "cluster_id": 63,
    "command_name": "KeySetWrite",
    "payload": {},
    "timed_request_timeout_ms": 1000
  }
}

For Cluster 63, always use "cluster_id": 63. Payload keys are the command field names in lowerCamelCase. Octet-string fields are base64-encoded. timed_request_timeout_ms is required for timed commands and ignored otherwise.

Command: KeySetWrite

Purpose

This command is used by Administrators to set the state of a given Group Key Set, including atomically updating the state of all epoch keys.

Command Identity

Payload Fields

Bridge Command Example

{
  "message_id": "1",
  "command": "device_command",
  "args": {
    "endpoint_id": 0,
    "cluster_id": 63,
    "command_name": "KeySetWrite",
    "payload": {
      "groupKeySet": {
        "groupKeySetID": 1,
        "groupKeySecurityPolicy": 0,
        "epochKey0": "AQID",
        "epochStartTime0": 0
      }
    }
  }
}

Command: KeySetRead

Purpose

This command is used by Administrators to read the state of a given Group Key Set.

Command Identity

Payload Fields

Bridge Command Example

{
  "message_id": "1",
  "command": "device_command",
  "args": {
    "endpoint_id": 0,
    "cluster_id": 63,
    "command_name": "KeySetRead",
    "payload": {
      "groupKeySetID": 1
    }
  }
}

The device answers with KeySetReadResponse (see below).

Command: KeySetReadResponse

Purpose

This command is generated in response to the KeySetRead command, if a valid Group Key Set was found. It contains the configuration of the requested Group Key Set, with the EpochKey0, EpochKey1 and EpochKey2 key contents replaced by null.

Command Identity

Response Fields

Command: KeySetRemove

Purpose

This command is used by Administrators to remove all state of a given Group Key Set.

Command Identity

Payload Fields

Bridge Command Example

{
  "message_id": "1",
  "command": "device_command",
  "args": {
    "endpoint_id": 0,
    "cluster_id": 63,
    "command_name": "KeySetRemove",
    "payload": {
      "groupKeySetID": 1
    }
  }
}

Command: KeySetReadAllIndices

Purpose

This command is used by Administrators to query a list of all Group Key Sets associated with the accessing fabric.

Command Identity

Payload Fields

Bridge Command Example

{
  "message_id": "1",
  "command": "device_command",
  "args": {
    "endpoint_id": 0,
    "cluster_id": 63,
    "command_name": "KeySetReadAllIndices",
    "payload": {
      "doNotUse": 0
    }
  }
}

The device answers with KeySetReadAllIndicesResponse (see below).

Command: KeySetReadAllIndicesResponse

Purpose

This command is generated in response to KeySetReadAllIndices and it contains the list of GroupKeySetID for all Group Key Sets associated with the scoped Fabric.

Command Identity

Response Fields

Cluster 63 Events

Cluster 63 defines no events.

SmartphoneKey Notes

• Cluster 63 is present on SmartphoneKey devices or hubs today. See Matter Bridge Clusters — Detailed Reference and Matter Device Attributes & Commands for the values the bridge actually reports.
• Shadow paths follow endpoint/63/attribute; attribute values that the device reports as unreadable are written as n/a.
• Attribute IDs, command IDs and enum values on this page come from the CSA Matter 1.6.1 data model; descriptions are condensed from the specification text.