Matter Cluster 31 — Access Control Cluster

Cluster Identity

Revision history

Shadow Path Format

Cluster 31 values in the device shadow use this format:

endpoint_id / 31 / attribute_id

Example:

{
  "0/31/2": 4
}

Cluster 31 Features

The FeatureMap attribute (0/31/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; 7 means every feature listed above is enabled.

Data Types

AccessControlAuxiliaryTypeEnum

AccessControlEntryAuthModeEnum

AccessControlEntryPrivilegeEnum

AccessRestrictionTypeEnum

ChangeTypeEnum

AccessControlEntryStruct (struct) — fabric-scoped

AccessControlExtensionStruct (struct) — fabric-scoped

AccessControlTargetStruct (struct)

AccessRestrictionEntryStruct (struct) — fabric-scoped

This structure describes a current access restriction on the fabric.

AccessRestrictionStruct (struct)

This structure describes an access restriction that would be applied to a specific data model element on a given endpoint/cluster pair.

CommissioningAccessRestrictionEntryStruct (struct)

This structure describes a current access restriction when there is no accessing fabric.

Cluster 31 Attributes

Cluster 31 defines 8 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 — ACL

Path example:

0/31/0

No condensed specification text is available for ACL; use the type, conformance and constraint below together with the cluster description above.

Each entry is a AccessControlEntryStruct (see Data Types).

Example:

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

Attribute 1 / 0x0001 — Extension

Path example:

0/31/1

If present, the Access Control Extensions may be used by Administrators to store arbitrary data related to fabric's Access Control Entries. The Access Control Extension list must support a single extension entry per supported fabric.

Each entry is a AccessControlExtensionStruct (see Data Types).

Example:

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

Attribute 2 / 0x0002 — SubjectsPerAccessControlEntry

Path example:

0/31/2

This attribute provides the minimum number of Subjects per entry that are supported by this server. Since reducing this value over time may invalidate ACL entries already written, this value must NOT decrease across time as software updates occur that could impact this value. If this is a concern for a given implementation, it is recommended to only use the minimum value required and avoid reporting a higher value than the required minimum.

Example:

{
  "0/31/2": 4
}

Attribute 3 / 0x0003 — TargetsPerAccessControlEntry

Path example:

0/31/3

This attribute provides the minimum number of Targets per entry that are supported by this server. Since reducing this value over time may invalidate ACL entries already written, this value must NOT decrease across time as software updates occur that could impact this value. If this is a concern for a given implementation, it is recommended to only use the minimum value required and avoid reporting a higher value than the required minimum.

Example:

{
  "0/31/3": 3
}

Attribute 4 / 0x0004 — AccessControlEntriesPerFabric

Path example:

0/31/4

This attribute provides the minimum number of ACL Entries per fabric that are supported by this server. Since reducing this value over time may invalidate ACL entries already written, this value must NOT decrease across time as software updates occur that could impact this value. If this is a concern for a given implementation, it is recommended to only use the minimum value required and avoid reporting a higher value than the required minimum.

Example:

{
  "0/31/4": 4
}

Attribute 5 / 0x0005 — CommissioningARL

Path example:

0/31/5

No condensed specification text is available for CommissioningARL; use the type, conformance and constraint below together with the cluster description above.

Each entry is a CommissioningAccessRestrictionEntryStruct (see Data Types).

Example:

{
  "0/31/5": []
}

Attribute 6 / 0x0006 — ARL

Path example:

0/31/6

No condensed specification text is available for ARL; use the type, conformance and constraint below together with the cluster description above.

Each entry is a AccessRestrictionEntryStruct (see Data Types).

Example:

{
  "0/31/6": []
}

Attribute 7 / 0x0007 — AuxiliaryACL

Path example:

0/31/7

No condensed specification text is available for AuxiliaryACL; use the type, conformance and constraint below together with the cluster description above.

Each entry is a AccessControlEntryStruct (see Data Types).

Example:

{
  "0/31/7": []
}

Cluster 31 Commands

Cluster 31 has 1 client-to-server command and 1 response.

AcceptedCommandList

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

endpoint_id / 31 / 65529

{
  "0/31/65529": [
    0
  ]
}

Bridge Command Payload Format

The bridge accepts Matter commands in this structure:

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

For Cluster 31, always use "cluster_id": 31. 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: ReviewFabricRestrictions

Purpose

This command signals to the service associated with the device vendor that the fabric administrator would like a review of the current restrictions on the accessing fabric. This command includes an optional list of ARL entries that the fabric administrator would like removed. In response, a ReviewFabricRestrictionsResponse is sent which contains a token that can be used to correlate a review request with a FabricRestrictionReviewUpdate event. Within 1 hour of the ReviewFabricRestrictionsResponse, the FabricRestrictionReviewUpdate event is generated, in order to indicate completion of the review and any additional steps required by the user for the review.

Command Identity

Payload Fields

Bridge Command Example

{
  "message_id": "1",
  "command": "device_command",
  "args": {
    "endpoint_id": 0,
    "cluster_id": 31,
    "command_name": "ReviewFabricRestrictions",
    "payload": {
      "arl": []
    }
  }
}

The device answers with ReviewFabricRestrictionsResponse (see below).

Command: ReviewFabricRestrictionsResponse

Purpose

Returns the review token for the request, which can be used to correlate with a FabricRestrictionReviewUpdate event.

Command Identity

Response Fields

Cluster 31 Events

Event 0 — AccessControlEntryChanged

The server must generate AccessControlEntryChanged events whenever its ACL attribute data is changed by an Administrator. - Each added entry must generate an event with ChangeType Added. - Each changed entry must generate an event with ChangeType Changed. - Each removed entry must generate an event with ChangeType Removed.

Event 1 — AccessControlExtensionChanged

The server must generate AccessControlExtensionChanged events whenever its extension attribute data is changed by an Administrator. - Each added extension must generate an event with ChangeType Added. - Each changed extension must generate an event with ChangeType Changed. - Each removed extension must generate an event with ChangeType Removed.

Event 2 — FabricRestrictionReviewUpdate

The server must generate a FabricRestrictionReviewUpdate event to indicate completion of a fabric restriction review. Due to the requirement to generate this event within a bound time frame of successful receipt of the ReviewFabricRestrictions command, this event may include additional steps that the client may present to the user in order to help the user locate the user interface for the Managed Device feature.

Event 3 — AuxiliaryAccessUpdated

The server must generate AuxiliaryAccessUpdated events whenever its AuxiliaryACL attribute data changes due to system management operations. This event should be generated only once per batch of changes, if many changes are done together. Administrators may use this event to trigger re-evaluation of overall access control currently granted to the node.

SmartphoneKey Notes

• Cluster 31 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/31/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.