class Matter::Cluster::GroupKeyManagementCluster

Overview

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

Manages group keys for secure group communication:

Key Features:

Defined in:

matter/cluster/group_key_management_cluster.cr

Constant Summary

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

Class Method Summary

Instance Method Summary

Instance methods inherited from class Matter::Cluster::Base

apply_scene_extension_field_set(field_set : ScenesManagementCluster::ExtensionFieldSet) : Bool apply_scene_extension_field_set, attributes : Array(AttributeMetadata) attributes, cluster_id : DataType::ClusterId cluster_id, cluster_id=(cluster_id : DataType::ClusterId) cluster_id=, commands : Array(CommandMetadata) commands, data_version : UInt32 data_version, data_version=(data_version : UInt32) data_version=, endpoint_id : DataType::EndpointNumber endpoint_id, endpoint_id=(endpoint_id : DataType::EndpointNumber) endpoint_id=, events : Array(EventMetadata) events, get_attribute_metadata(attribute_id : UInt32) : AttributeMetadata | Nil get_attribute_metadata, get_command_metadata(command_id : UInt32) : CommandMetadata | Nil get_command_metadata, invoke_command(command_id : UInt32, fields : Bytes = Bytes.new(0), session_id : UInt64 | Nil = nil, is_case_session : Bool = false, fabric_index : UInt8 | Nil = nil) : InteractionModel::Status | CommandResponse invoke_command, name : String name, on_attribute_changed : Proc(UInt16, UInt32, UInt32, Nil) | Nil on_attribute_changed, on_attribute_changed=(on_attribute_changed : Proc(UInt16, UInt32, UInt32, Nil) | Nil) on_attribute_changed=, persistence_key : String persistence_key, read_attribute(attribute_id : UInt32, fabric_index : UInt8 | Nil = nil) : InteractionModel::Status | Bytes read_attribute, request_fabric_index : UInt8 | Nil request_fabric_index, request_fabric_index=(request_fabric_index : UInt8 | Nil) request_fabric_index=, request_is_case_session=(request_is_case_session : Bool) request_is_case_session=, request_is_case_session? : Bool request_is_case_session?, request_peer_node_id : UInt64 | Nil request_peer_node_id, request_peer_node_id=(request_peer_node_id : UInt64 | Nil) request_peer_node_id=, request_session_id : UInt64 | Nil request_session_id, request_session_id=(request_session_id : UInt64 | Nil) request_session_id=, restore_state(json : String) : Nil restore_state, save_state : String | Nil save_state, store_scene_extension_field_set : ScenesManagementCluster::ExtensionFieldSet | Nil store_scene_extension_field_set, write_attribute(attribute_id : UInt32, value : Bytes) : InteractionModel::Status write_attribute

Constructor methods inherited from class Matter::Cluster::Base

new(endpoint_id : DataType::EndpointNumber, cluster_id : DataType::ClusterId) new

Constructor Detail

def self.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


[View source]

Class Method Detail

def self.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

[View source]

Instance Method Detail

def 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

[View source]
def 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

[View source]
def attributes : Array(AttributeMetadata) #
Description copied from class Matter::Cluster::Base

Get all attribute metadata


[View source]
def commands : Array(CommandMetadata) #
Description copied from class Matter::Cluster::Base

Get all command metadata


[View source]
def features : Feature #

Cluster state


[View source]
def features=(features : Feature) #

Cluster state


[View source]
def 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


[View source]
def get_key_set_ids(fabric_index : UInt8) : Array(UInt16) #

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


[View source]
def group_exists?(group_id : UInt16, fabric_index : UInt8) : Bool #

Check if a group exists for a fabric


[View source]
def group_key_map(fabric_index : UInt8) : Array(GroupKeyMapStruct) #

Get group key map for the specified fabric


[View source]
def group_key_map : Array(GroupKeyMapStruct) #

Get all group key map entries (for testing)


[View source]
def group_table(fabric_index : UInt8) : Array(GroupInfoMapStruct) #

Get group table for the specified fabric


[View source]
def group_table : Array(GroupInfoMapStruct) #

Get all group table entries (for testing)


[View source]
def 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.


[View source]
def 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.


[View source]
def 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

[View source]
def 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

[View source]
def max_group_keys_per_fabric : UInt16 #

[View source]
def max_group_keys_per_fabric=(max_group_keys_per_fabric : UInt16) #

[View source]
def max_groups_per_fabric : UInt16 #

[View source]
def max_groups_per_fabric=(max_groups_per_fabric : UInt16) #

[View source]
def name : String #
Description copied from class Matter::Cluster::Base

Get cluster name


[View source]
def read_attribute(attribute_id : UInt32, fabric_index : UInt8 | Nil = nil) : InteractionModel::Status | Bytes #
Description copied from class Matter::Cluster::Base

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


[View source]
def remove_fabric(fabric_index : UInt8) : Nil #

Remove all groups for a fabric (fabric removal)


[View source]
def 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


[View source]
def remove_group_key_map(group_id : UInt16, fabric_index : UInt8) : Nil #

Remove a group key map entry


[View source]
def restore_state(json : String) : Nil #
Description copied from class Matter::Cluster::Base

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


[View source]
def save_state : String | Nil #
Description copied from class Matter::Cluster::Base

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.


[View source]