Matter Cluster 2049 — TLS Certificate Management Cluster

Cluster Identity

Revision history

Shadow Path Format

Cluster 2049 values in the device shadow use this format:

endpoint_id / 2049 / attribute_id

Example:

{
  "0/2049/0": 5
}

Data Types

TLSCertStruct (struct) — fabric-scoped

This encodes the mapping between a TLSCAID and the associated root certificate.

TLSClientCertificateDetailStruct (struct) — fabric-scoped

This encodes a TLS Client Certificate and corresponding ICAC chain.

Cluster 2049 Attributes

Cluster 2049 defines 4 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 — MaxRootCertificates

Path example:

0/2049/0

This attribute contains the maximum number of per fabric TLSRCACs that can be installed on this Node.

Example:

{
  "0/2049/0": 5
}

Attribute 1 / 0x0001 — ProvisionedRootCertificates

Path example:

0/2049/1

This attribute is a list of all provisioned TLSCertStruct that are currently installed on this Node. When this attribute is read over a non Large Message capable transport, the Certificate field must NOT be included. To get the full details of a certificate use the FindRootCertificate command.

Each entry is a TLSCertStruct (see Data Types).

Example:

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

Attribute 2 / 0x0002 — MaxClientCertificates

Path example:

0/2049/2

This attribute contains the maximum number of per fabric Client Certificates that can be installed on this Node.

Example:

{
  "0/2049/2": 2
}

Attribute 3 / 0x0003 — ProvisionedClientCertificates

Path example:

0/2049/3

This attribute is a list of all provisioned TLSCCDID that are currently installed on this Node. When this attribute is read over a non Large Message capable transport, the ClientCertificate and IntermediateCertificates fields must NOT be included. To get the full details of a client certificate use the FindClientCertificate command.

Each entry is a TLSClientCertificateDetailStruct (see Data Types).

Example:

{
  "0/2049/3": []
}

Cluster 2049 Commands

Cluster 2049 has 9 client-to-server commands and 6 responses.

AcceptedCommandList

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

endpoint_id / 2049 / 65529

{
  "0/2049/65529": [
    0,
    2,
    4,
    6,
    7,
    9,
    10,
    12,
    14
  ]
}

Bridge Command Payload Format

The bridge accepts Matter commands in this structure:

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

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

Purpose

This command must provision a newly provided certificate, or rotate an existing one, based on the contents of the CAID field.

Command Identity

Payload Fields

Bridge Command Example

{
  "message_id": "1",
  "command": "device_command",
  "args": {
    "endpoint_id": 0,
    "cluster_id": 2049,
    "command_name": "ProvisionRootCertificate",
    "payload": {
      "certificate": "AQID",
      "caid": 0
    }
  }
}

The device answers with ProvisionRootCertificateResponse (see below).

Command: ProvisionRootCertificateResponse

Purpose

This command is generated in response to a ProvisionRootCertificate command.

Command Identity

Response Fields

Command: FindRootCertificate

Purpose

This command returns the specified TLS root certificate, or all provisioned TLS root certificates for the accessing fabric, based on the contents of the CAID field.

Command Identity

Payload Fields

Bridge Command Example

{
  "message_id": "1",
  "command": "device_command",
  "args": {
    "endpoint_id": 0,
    "cluster_id": 2049,
    "command_name": "FindRootCertificate",
    "payload": {
      "caid": 0
    }
  }
}

The device answers with FindRootCertificateResponse (see below).

Command: FindRootCertificateResponse

Purpose

This command is generated in response to a FindRootCertificate command.

Command Identity

Response Fields

Command: LookupRootCertificate

Purpose

This command returns the CAID for the passed in fingerprint.

Command Identity

Payload Fields

Bridge Command Example

{
  "message_id": "1",
  "command": "device_command",
  "args": {
    "endpoint_id": 0,
    "cluster_id": 2049,
    "command_name": "LookupRootCertificate",
    "payload": {
      "fingerprint": "AQID"
    }
  }
}

The device answers with LookupRootCertificateResponse (see below).

Command: LookupRootCertificateResponse

Purpose

This command is generated in response to a LookupRootCertificate command.

Command Identity

Response Fields

Command: RemoveRootCertificate

Purpose

This command is generated to request the server removes the certificate provisioned to the provided Certificate Authority ID.

Command Identity

Payload Fields

Bridge Command Example

{
  "message_id": "1",
  "command": "device_command",
  "args": {
    "endpoint_id": 0,
    "cluster_id": 2049,
    "command_name": "RemoveRootCertificate",
    "payload": {
      "caid": 0
    }
  }
}

Command: ClientCSR

Purpose

ClientCSR is a client-to-server command of the TLS Certificate Management cluster.

Command Identity

Payload Fields

Bridge Command Example

{
  "message_id": "1",
  "command": "device_command",
  "args": {
    "endpoint_id": 0,
    "cluster_id": 2049,
    "command_name": "ClientCSR",
    "payload": {
      "nonce": "AQID",
      "ccdid": 0
    }
  }
}

The device answers with ClientCSRResponse (see below).

Command: ClientCSRResponse

Purpose

ClientCSRResponse is a server response of the TLS Certificate Management cluster.

Command Identity

Response Fields

Command: ProvisionClientCertificate

Purpose

This command is generated to request the Node provisions newly provided Client Certificate Details, or rotate an existing client certificate. This command is typically invoked after having created a new client certificate using the CSR requested in ClientCSR, with the TLSCCDID returned by ClientCSRResponse.

Command Identity

Payload Fields

Bridge Command Example

{
  "message_id": "1",
  "command": "device_command",
  "args": {
    "endpoint_id": 0,
    "cluster_id": 2049,
    "command_name": "ProvisionClientCertificate",
    "payload": {
      "ccdid": 0,
      "clientCertificate": "AQID",
      "intermediateCertificates": []
    }
  }
}

Command: FindClientCertificate

Purpose

This command returns the TLSClientCertificateDetailStruct for the passed in CCDID, or all TLS client certificates for the accessing fabric, based on the contents of the CCDID field.

Command Identity

Payload Fields

Bridge Command Example

{
  "message_id": "1",
  "command": "device_command",
  "args": {
    "endpoint_id": 0,
    "cluster_id": 2049,
    "command_name": "FindClientCertificate",
    "payload": {
      "ccdid": 0
    }
  }
}

The device answers with FindClientCertificateResponse (see below).

Command: FindClientCertificateResponse

Purpose

This command is generated in response to a FindClientCertificate command.

Command Identity

Response Fields

Command: LookupClientCertificate

Purpose

This command returns the CCDID for the passed in Fingerprint.

Command Identity

Payload Fields

Bridge Command Example

{
  "message_id": "1",
  "command": "device_command",
  "args": {
    "endpoint_id": 0,
    "cluster_id": 2049,
    "command_name": "LookupClientCertificate",
    "payload": {
      "fingerprint": "AQID"
    }
  }
}

The device answers with LookupClientCertificateResponse (see below).

Command: LookupClientCertificateResponse

Purpose

This command is generated in response to a LookupClientCertificate command.

Command Identity

Response Fields

Command: RemoveClientCertificate

Purpose

This command is used to request the Node removes all stored information for the provided CCDID.

Command Identity

Payload Fields

Bridge Command Example

{
  "message_id": "1",
  "command": "device_command",
  "args": {
    "endpoint_id": 0,
    "cluster_id": 2049,
    "command_name": "RemoveClientCertificate",
    "payload": {
      "ccdid": 0
    }
  }
}

Cluster 2049 Events

Cluster 2049 defines no events.

SmartphoneKey Notes

• Cluster 2049 is not currently exposed by SmartphoneKey devices. This page documents the Matter 1.6.1 specification so that future devices can be interpreted without changes to the backend.
• Shadow paths follow endpoint/2049/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.