Matter Specification - Administrator Commissioning Cluster

Matter :: Administrator Commissioning Cluster

---

This cluster is used to trigger a Node to allow a new Administrator to commission it. It defines Attributes, Commands and Responses needed for this purpose.

For the management of Operational Credentials and Trusted Root Certificates, the Node Operational Credentials cluster is used.

---

1. Classification

Hierarchy	Role	Context	PICS Code
Base	Utility	Node	CADMIN

2. Identifier

Identifier	Name
0x003C	AdministratorCommissioning

3. Features

3.1. Bit 0: Basic Commissioning

Bit	Code	Feature	Description
0	BC	Basic	Node supports Basic Commissioning Method

• value 0 = Basic Commissioning Method (BCM)
• value 1 = Enhanced Commissioning Method (ECM)

4. Data Types

4.1. CommissioningWindowStatus enum

Value	Name	Description	Conformance
0	WindowNotOpen	Commissioning window not open	M
1	EnhancedWindowOpen	An Enhanced Commissioning Method window is open	M
2	BasicWindowOpen	An Basic Commissioning Method window os open	BC

5. Attributes

5.1. Window Status

ID	Name	Type	Constraint	Quality	Default	Access	Conformance
0x0000	WindowStatus	CommisioningWindowStatus (4.1.)				R V	M

This attribute SHALL indicate whether a new Commissioning window has been opened by an Administrator, using either the OCW command or the OBCW command.

This attribute SHALL revert to WindowNotOpen upon expiry of a commissioning window.

Note that an initial commissioning window is not opened using either the OCW command or the OBCW command, and therefore this attribute SHALL be set to WindowNotOpen on initial commissioning.

 

5.2. Admin Fabric Index

ID	Name	Type	Constraint	Quality	Default	Access	Conformance
0x0001	AdminFabricIndex	fabric-idx		X		R V	M

When the WindowStatus attribute is not set to WindowNotOpen, this attribute SHALL indicate the FabricIndex associated with the Fabric scoping of the Administrator that opened the window. This MAY be used to cross-reference in the Fabrics attribute of the Node Operational Credentials cluster.

If, during an open commissioning window, the fabric for the Administrator that opened the window is removed, then this attribute SHALL be set to null.

When the WindowStatus attribute is set to WindowNotOpen, this attribute SHALL be set to null.

 

5.3. Admin Vendor ID

ID	Name	Type	Constraint	Quality	Default	Access	Conformance
0x0002	AdminVendorID	vendor-id		X		R V	M

When the WindowStatus attribute is not set to WindowNotOpen, this attribute SHALL indicate the Vendor ID associated with the Fabric scoping of the Administrator that opened the window. This field SHALL match the VendorID field of the Fabrics attribute list entry associated with the Administrator having opened the window, at the time of window opening. If the fabric for the Administrator that opened the window is removed from the node while the commissioning window is still open, this attribute SHALL NOT be updated.

When the WindowStatus attribute is set to WindowNotOpen, this attribute SHALL be set to null.

6. Commands

Only one commissioning window can be active at a time. If a Node receives another open commissioning command when one OCW is already active, it SHALL return a failure response (7. Status Codes)

6.1. Open Commissioning Window (OCW)

ID	Name	Direction	Response	Access	Conformance
0x00	OpenCommissioningWindow	client → server	Y	A T	M

This command is used by a current Administrator to instruct a Node to go into commissioning mode. The Enhanced Commissioning Method specifies a window of time during which an already commissioned Node accepts PASE sessions. The current Administrator MUST specify a timeout value for the duration of OCW.

When OCW expires or commissioning completes, the Node SHALL remove the Passcode by deleting the PAKE passcode verifier as well as stop publishing the DNS-SD record corresponding to this command as described in Section 4.3.1, “Commissionable Node Discovery”. The commissioning into a new Fabric completes when the Node successfully receives a CommissioningComplete command, see Section 5.5, “Commissioning Flows”.

The parameters for OpenCommissioningWindow command are as follows:

ID	Field	Type	Range	Default	Conformance
0	CommissioningTimeout	uint16	desc		M
1	PAKEPasscodeVerifier	octstr	all		M
2	Discriminator	uint16	0 to 2047		M
3	Iterations	uint32	1000 to 100000		M
4	Salt	octstr	16 to 32		M

A current Administrator MAY invoke this command to put a node in commissioning mode for the next Administrator. On completion, the command SHALL return a cluster specific status code from the enumeration below reflecting success or reasons for failure of the operation. The new Administrator SHALL discover the Node on the IP network using DNS-based Service Discovery (DNS-SD) for commissioning.
If any format or validity errors related to the PAKEPasscodeVerifier, Iterations or Salt arguments arise, this command SHALL fail with a cluster specific status code of PAKEParameterError.
If a commissioning window is already currently open, this command SHALL fail with a cluster specific status code of Busy. If the fail-safe timer is currently armed, this command SHALL fail with a cluster specific status code of Busy, since it is likely that concurrent commissioning operations from multiple separate Commissioners are about to take place.
In case of any other parameter error, this command SHALL fail with a status code of COMMAND_INVALID.

[CommissioningTimeout]

This SHALL specify the time in seconds during which commissioning session establishment is allowed by the Node. This is known as Open Commissioning Window (OCW). This timeout value SHALL follow guidance as specified in Announcement Duration. The CommissioningTimeout applies only to cessation of any announcements and to accepting of new commissioning sessions; it does not apply to abortion of connections, i.e., a commissioning session SHOULD NOT abort prematurely upon expiration of this timeout.

 

[PAKEPasscodeVerifier]

This field SHALL specify an ephemeral PAKE passcode verifier (see Section 3.10, “Password-Authenticated Key Exchange (PAKE)”) computed by the existing Administrator to be used for this commissioning. The field is concatenation of two values (w0 || L) SHALL be

(CRYPTO_GROUP_SIZE_BYTES + CRYPTO_PUBLIC_KEY_SIZE_BYTES)-octets

long as detailed in Crypto_PAKEValues_Responder. It SHALL be derived from an ephemeral passcode (See PAKE). It SHALL be deleted by the Node at the end of commissioning or expiration of OCW, and SHALL be deleted by the existing Administrator after sending it to the Node(s).

 

[Discriminator]

This field SHALL be used by the Node as the long discriminator for DNS-SD advertisement (see Commissioning Discriminator) for discovery by the new Administrator. The new Administrator can find and filter DNS-SD records by long discriminator to locate and initiate commissioning with the appropriate Node.

 

[Iterations]

This field SHALL be used by the Node as the PAKE iteration count associated with the ephemeral PAKE passcode verifier to be used for this commissioning, which SHALL be sent by the Node to the new Administrator’s software as response to the PBKDFParamRequest during PASE negotiation. The permitted range of values SHALL match the range specified in Section 3.9, “Password-Based Key Derivation Function (PBKDF)”, within the definition of the Crypto_PBKDFParameterSet.

 

[Salt]

This field SHALL be used by the Node as the PAKE Salt associated with the ephemeral PAKE passcode verifier to be used for this commissioning, which SHALL be sent by the Node to the new Administrator’s software as response to the PBKDFParamRequest during PASE negotiation. The constraints on the value SHALL match those specified in Section 3.9, “Password-Based Key Derivation Function (PBKDF)”, within the definition of the Crypto_PBKDFParameterSet.

When a Node receives the Open Commissioning Window command, it SHALL begin advertising on DNS-SD as described in Section 4.3.1, “Commissionable Node Discovery” and for a time period as described in Section 11.18.8.1.1, “CommissioningTimeout”. When the command is received by a SED, it SHALL enter into active mode and set its fast-polling interval to SLEEPY_ACTIVE_INTERVAL for at least the entire duration of the CommissioningTimeout.

 

6.2. Open Basic Commissioning Window (OBCW)

ID	Name	Direction	Response	Access	Conformance
0x01	OpenBasicCommissioningWindow	client → server	Y	A T	BC

This command MAY be used by a current Administrator to instruct a Node to go into commissioning mode, if the node supports the Basic Commissioning Method. The Basic Commissioning Method specifies a window of time during which an already commissioned Node accepts PASE sessions. The current Administrator SHALL specify a timeout value for the duration of OBCW.

If a commissioning window is already currently open, this command SHALL fail with a cluster specific status code of Busy.

If the fail-safe timer is currently armed, this command SHALL fail with a cluster specific status code of Busy, since it is likely that concurrent commissioning operations from multiple separate Commissioners are about to take place.

In case of any other parameter error, this command SHALL fail with a status code of COMMAND_INVALID.

The commissioning into a new Fabric completes when the Node successfully receives a CommissioningComplete command, see Section 5.5, “Commissioning Flows”. The new Administrator SHALL discover the Node on the IP network using DNS-based Service Discovery (DNS-SD) for commissioning.

The data for this command is as follows:

ID	Field	Type	Range	Default	Conformance
0	CommissioningTimeout	uint16	desc		M

[CommissioningTimeout]
This SHALL specify the time in seconds during which commissioning session establishment is allowed by the Node. This is known as Open Basic Commissioning Window (OBCW). This timeout SHALL follow guidance as specified in Announcement Duration.

When a Node receives the Open Basic Commissioning Window command, it SHALL begin advertising on DNS-SD as described in Section 4.3.1, “Commissionable Node Discovery” and for a time period as described in Section 11.18.8.2.1, “CommissioningTimeout”. When the command is received by a SED, it SHALL enter into active mode and set its fast-polling interval to SLEEPY_ACTIVE_INTERVAL for at least the entire duration of the CommissioningTimeout.

 

6.3. Revoke Commissioning

ID	Name	Direction	Response	Access	Conformance
0x02	RevokeCommissioning	client → server	Y	A T	M

This command is used by a current Administrator to instruct a Node to revoke any active Open Commissioning Window or Open Basic Commissioning Window command. This is an idempotent command and the Node SHALL (for ECM) delete the temporary PAKEPasscodeVerifier and associated data, and stop publishing the DNS-SD record associated with the Open Commissioning Window or Open Basic Commissioning Window command, see Section 4.3.1, “Commissionable Node Discovery”.

If no commissioning window was open at time of receipt, this command SHALL fail with a cluster specific status code of WindowNotOpen.

7. Status Codes

Value	Name	Conformance	Description
2	Busy	M	Could not be completed because another commissioning is in progress
3	PAKEParameterError	M	Provided PAKE parameters were incorrectly formatted or otherwise invalid
4	WindowNotOpen	M	No commissioning window was currently open