class

Matter::Cluster::GroupKeyManagementCluster

Inherits Matter::Cluster::Base < Reference < Object

Group Key Management Cluster (0x003F) Matter Core Specification §11.2

Manages group keys for secure group communication:

  • Group key sets for shared encryption keys
  • Mapping between groups and key sets
  • Identity Protection Keys (IPK) for CASE session establishment
  • Operational group keys for group messaging

Key Features:

  • Fabric-scoped: All data isolated per fabric
  • IPK Protection: KeySet 0 (IPK) cannot be removed
  • Strict Validation: Epoch keys must be ordered, security policies enforced
  • Cryptographic Operations: HKDF-based key derivation for operational keys

Constants

ATTR_GROUP_KEY_MAP = 0_u32

Attribute IDs

ATTR_GROUP_TABLE = 1_u32
ATTR_MAX_GROUP_KEYS_PER_FABRIC = 3_u32
ATTR_MAX_GROUPS_PER_FABRIC = 2_u32
ATTRIBUTE_LIST = 65531_u32
CLUSTER_ID = 63_u32
CLUSTER_REVISION = 65533_u32

Global attributes

FEATURE_MAP = 65532_u32

Constructors

new(endpoint_id : DataType::EndpointNumber, features : Feature = Feature::None, max_groups_per_fabric : UInt16 = 12_u16, max_group_keys_per_fabric : UInt16 = 3_u16)

Initialize the cluster

Source

Class methods

cluster_id

Group Key Management Cluster (0x003F) Matter Core Specification §11.2

Manages group keys for secure group communication:

  • Group key sets for shared encryption keys
  • Mapping between groups and key sets
  • Identity Protection Keys (IPK) for CASE session establishment
  • Operational group keys for group messaging

Key Features:

  • Fabric-scoped: All data isolated per fabric
  • IPK Protection: KeySet 0 (IPK) cannot be removed
  • Strict Validation: Epoch keys must be ordered, security policies enforced
  • Cryptographic Operations: HKDF-based key derivation for operational keys
Source

Instance methods

add_group(group_id : UInt16, endpoint_id : UInt16, group_name : String | Nil, fabric_index : UInt8) : Nil

Add a group to the group table Called by Groups cluster when AddGroup command is executed

Validations:

  • Group must have a corresponding key map entry
  • Must not exceed max_groups_per_fabric
Source
add_group_key_map(group_id : UInt16, group_key_set_id : UInt16, fabric_index : UInt8) : Nil

Add or update a group key map entry Links a group to a key set within a fabric

Validations:

  • Group ID must not be 0
  • Key set must exist in the fabric
  • Must not exceed max_groups_per_fabric
Source
attributes

Get all attribute metadata

Source
commands

Get all command metadata

Source
features

Cluster state

Source
features=(features : Feature)

Cluster state

Source
get_key_set(group_key_set_id : UInt16, fabric_index : UInt8) : GroupKeySetStruct | Nil

Get a key set by ID (for cryptographic operations) Returns the actual key set with key material

Source
get_key_set_ids(fabric_index : UInt8) : Array(UInt16)

Get all key set IDs for a fabric (for testing)

Source
group_exists?(group_id : UInt16, fabric_index : UInt8) : Bool

Check if a group exists for a fabric

Source
group_key_map(fabric_index : UInt8) : Array(GroupKeyMapStruct)

Get group key map for the specified fabric

Source
group_key_map

Get all group key map entries (for testing)

Source
group_table(fabric_index : UInt8) : Array(GroupInfoMapStruct)

Get group table for the specified fabric

Source
group_table

Get all group table entries (for testing)

Source
handle_key_set_read(cmd : KeySetReadRequest, fabric_index : UInt8) : KeySetReadResponse | Nil

KeySetRead command handler Matter Core Spec §11.2.8.2

Returns a key set by ID, but with actual key material removed for security. Returns null if key set not found for this fabric.

Source
handle_key_set_read_all_indices(fabric_index : UInt8) : KeySetReadAllIndicesResponse

KeySetReadAllIndices command handler Matter Core Spec §11.2.8.4

Returns list of all key set IDs for the accessing fabric.

Source
handle_key_set_remove(cmd : KeySetRemoveRequest, fabric_index : UInt8) : Nil

KeySetRemove command handler Matter Core Spec §11.2.8.3

Removes a key set by ID. Special rules:

  • Cannot remove key set 0 (IPK - Identity Protection Key)
  • Removes any group key map entries referencing this key set
  • Returns error if key set not found
Source
handle_key_set_write(cmd : KeySetWriteRequest, fabric_index : UInt8) : Nil

KeySetWrite command handler Matter Core Spec §11.2.8.1

Creates or updates a group key set. Performs extensive validation:

  • Validates key set structure (epoch ordering, key lengths, etc.)
  • Enforces max_group_keys_per_fabric limit
  • Prevents creation of duplicate key set IDs within fabric
  • Security policy must be TrustFirst
Source
max_group_keys_per_fabric
Source
max_group_keys_per_fabric=(max_group_keys_per_fabric : UInt16)
Source
max_groups_per_fabric
Source
max_groups_per_fabric=(max_groups_per_fabric : UInt16)
Source
name

Get cluster name

Source
read_attribute(attribute_id : UInt32, fabric_index : UInt8 | Nil = nil) : InteractionModel::Status | Bytes

Read an attribute value The fabric_index parameter is optional and used for fabric-scoped attributes like CurrentFabricIndex in OperationalCredentialsCluster

Source
remove_fabric(fabric_index : UInt8) : Nil

Remove all groups for a fabric (fabric removal)

Source
remove_group(group_id : UInt16, endpoint_id : UInt16, fabric_index : UInt8) : Nil

Remove an endpoint from a group Called by Groups cluster when RemoveGroup command is executed

Source
remove_group_key_map(group_id : UInt16, fabric_index : UInt8) : Nil

Remove a group key map entry

Source
restore_state(json : String) : Nil

Restore cluster state from JSON. Override in subclasses that need to restore state. The json parameter is the string returned by save_state.

Source
save_state

Save cluster state to JSON for persistence. Override in subclasses that need to persist state (e.g., scenes, groups). Returns nil if no state needs to be persisted.

Source

Nested types