TLSCertificateManagement Cluster (#36379)

* Generated using: ./alchemy zap --attribute="in-progress" --sdkRoot=[] --specRoot=[] 'TLSCertificateManagement.adoc' With manual edits adding description & apiMaturity * Generated using ./scripts/tools/zap_regen_all.py
project-chip · Jan 15, 2025 · 7999db8 · 7999db8
1 parent 11a6571
commit 7999db8
Show file tree

Hide file tree

Showing 56 changed files with 11,872 additions and 0 deletions.
diff --git a/.github/workflows/tests.yaml b/.github/workflows/tests.yaml
@@ -198,6 +198,7 @@ jobs:
                       src/app/zap-templates/zcl/data-model/chip/time-format-localization-cluster.xml \
                       src/app/zap-templates/zcl/data-model/chip/time-synchronization-cluster.xml \
                       src/app/zap-templates/zcl/data-model/chip/timer-cluster.xml \
+                      src/app/zap-templates/zcl/data-model/chip/tls-certificate-management-cluster.xml \
                       src/app/zap-templates/zcl/data-model/chip/user-label-cluster.xml \
                       src/app/zap-templates/zcl/data-model/chip/unit-localization-cluster.xml \
                       src/app/zap-templates/zcl/data-model/chip/wake-on-lan-cluster.xml \

diff --git a/docs/ids_and_codes/zap_clusters.md b/docs/ids_and_codes/zap_clusters.md
@@ -138,6 +138,7 @@ Generally regenerate using one of:
 |       1366 |      0x556 | Chime                                                   |
 |       1872 |      0x750 | EcosystemInformation                                    |
 |       1873 |      0x751 | CommissionerControl                                     |
+|       2049 |      0x801 | TlsCertificateManagement                                |
 | 4294048773 | 0xFFF1FC05 | UnitTesting                                             |
 | 4294048774 | 0xFFF1FC06 | FaultInjection                                          |
 | 4294048800 | 0xFFF1FC20 | SampleMei                                               |
diff --git a/scripts/rules.matterlint b/scripts/rules.matterlint
@@ -105,6 +105,7 @@ load "../src/app/zap-templates/zcl/data-model/chip/thread-network-directory-clus
 load "../src/app/zap-templates/zcl/data-model/chip/time-format-localization-cluster.xml";
 load "../src/app/zap-templates/zcl/data-model/chip/time-synchronization-cluster.xml";
 load "../src/app/zap-templates/zcl/data-model/chip/timer-cluster.xml";
+load "../src/app/zap-templates/zcl/data-model/chip/tls-certificate-management-cluster.xml";
 load "../src/app/zap-templates/zcl/data-model/chip/unit-localization-cluster.xml";
 load "../src/app/zap-templates/zcl/data-model/chip/user-label-cluster.xml";
 load "../src/app/zap-templates/zcl/data-model/chip/wake-on-lan-cluster.xml";

diff --git a/src/app/zap-templates/zcl/data-model/chip/tls-certificate-management-cluster.xml b/src/app/zap-templates/zcl/data-model/chip/tls-certificate-management-cluster.xml
@@ -0,0 +1,142 @@
+<?xml version="1.0"?>
+<!--
+Copyright (c) 2024-2025 Project CHIP Authors
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+    http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.
+-->
+<!--
+XML generated by Alchemy; DO NOT EDIT.
+Source: src/tls/TLSCertificateManagement.adoc
+Parameters: in-progress 
+Git: 1.4-534-g3214b3502
+-->
+<configurator xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="../../zcl.xsd">
+  <domain name="General"/>
+  <struct name="TLSCertStruct" apiMaturity="provisional">
+    <cluster code="0x0801"/>
+    <item fieldId="0" name="CAID" type="int16u"/>
+    <item fieldId="1" name="Certificate" type="long_octet_string" length="3000"/>
+  </struct>
+
+  <struct name="TLSClientCertificateDetailStruct" apiMaturity="provisional">
+    <cluster code="0x0801"/>
+    <item fieldId="0" name="CCDID" type="int16u"/>
+    <item fieldId="1" name="ClientCertificate" type="long_octet_string" length="3000"/>
+    <item fieldId="2" name="IntermediateCertificates" array="true" type="octet_string"/>
+  </struct>
+
+  <cluster apiMaturity="provisional">
+    <domain name="General"/>
+    <name>TLS Certificate Management</name>
+    <code>0x0801</code>
+    <define>TLS_CERTIFICATE_MANAGEMENT_CLUSTER</define>
+    <description>This Cluster is used to manage TLS Client Certificates and to provision
+      TLS endpoints with enough information to facilitate subsequent connection.</description>
+    <client init="false" tick="false">true</client>
+    <server init="false" tick="false">true</server>
+    <globalAttribute code="0xFFFD" side="either" value="1"/>
+    <attribute code="0x0000" side="server" define="MAX_ROOT_CERTIFICATES" type="int8u">MaxRootCertificates</attribute>
+    <attribute code="0x0001" side="server" define="CURRENT_ROOT_CERTIFICATES" type="int8u">CurrentRootCertificates</attribute>
+    <attribute code="0x0002" side="server" define="MAX_CLIENT_CERTIFICATES" type="int8u">MaxClientCertificates</attribute>
+    <attribute code="0x0003" side="server" define="CURRENT_CLIENT_CERTIFICATES" type="int8u">CurrentClientCertificates</attribute>
+    <command code="0x00" source="client" name="ProvisionRootCertificate" optional="false" response="ProvisionRootCertificateResponse">
+      <description>This command SHALL provision the provided certificate for the passed in CAID.</description>
+      <access op="invoke" privilege="administer"/>
+      <arg id="0" name="Certificate" type="long_octet_string" length="3000"/>
+      <arg id="1" name="CAID" type="int16u" isNullable="true"/>
+    </command>
+
+    <command code="0x01" source="server" name="ProvisionRootCertificateResponse" optional="false" disableDefaultResponse="true">
+      <description>This command SHALL be generated in response to a ProvisionRootCertificate command.</description>
+      <arg id="0" name="CAID" type="int16u"/>
+    </command>
+
+    <command code="0x02" source="client" name="FindRootCertificate" optional="false" response="FindRootCertificateResponse">
+      <description>This command SHALL return the TLSCertStruct for the passed in CAID.</description>
+      <arg id="0" name="CAID" type="int16u" isNullable="true"/>
+    </command>
+
+    <command code="0x03" source="server" name="FindRootCertificateResponse" optional="false" disableDefaultResponse="true">
+      <description>This command SHALL be generated in response to a FindRootCertificate command.</description>
+      <arg id="0" name="CertificateDetails" array="true" type="TLSCertStruct"/>
+    </command>
+
+    <command code="0x04" source="client" name="LookupRootCertificate" optional="false" response="LookupRootCertificateResponse">
+      <description>This command SHALL return the CAID for the passed in fingerprint.</description>
+      <arg id="0" name="Fingerprint" type="octet_string" length="64"/>
+    </command>
+
+    <command code="0x05" source="server" name="LookupRootCertificateResponse" optional="false" disableDefaultResponse="true">
+      <description>This command SHALL be generated in response to a LookupRootCertificate command.</description>
+      <arg id="0" name="CAID" type="int16u"/>
+    </command>
+
+    <command code="0x06" source="client" name="RemoveRootCertificate" optional="false">
+      <description>This command SHALL be generated to request the server removes the certificate provisioned to the provided Certificate Authority ID.</description>
+      <access op="invoke" privilege="administer"/>
+      <arg id="0" name="CAID" type="int16u"/>
+    </command>
+
+    <command code="0x07" source="client" name="TLSClientCSR" optional="false" response="TLSClientCSRResponse">
+      <description>This command SHALL be generated to request the Node generates a Certificate Signing Request.</description>
+      <access op="invoke" privilege="administer"/>
+      <arg id="1" name="Nonce" type="octet_string"/>
+    </command>
+
+    <command code="0x08" source="server" name="TLSClientCSRResponse" optional="false" disableDefaultResponse="true">
+      <description>This command SHALL be generated in response to a TLSClientCSR command.</description>
+      <arg id="0" name="CCDID" type="int16u"/>
+      <arg id="1" name="CSR" type="octet_string"/>
+      <arg id="2" name="Nonce" type="octet_string"/>
+    </command>
+
+    <command code="0x09" source="client" name="ProvisionClientCertificate" optional="false" response="ProvisionClientCertificateResponse">
+      <description>This command SHALL be generated to request the Node provisions the provided Client Certificate Details.</description>
+      <access op="invoke" privilege="administer"/>
+      <arg id="0" name="CCDID" type="int16u"/>
+      <arg id="1" name="ClientCertificateDetails" type="TLSClientCertificateDetailStruct"/>
+    </command>
+
+    <command code="0x0A" source="server" name="ProvisionClientCertificateResponse" optional="false" disableDefaultResponse="true">
+      <description>This command SHALL be generated in response to a ProvisionClientCertificate command.</description>
+      <arg id="0" name="CCDID" type="int16u"/>
+    </command>
+
+    <command code="0x0B" source="client" name="FindClientCertificate" optional="false" response="FindClientCertificateResponse">
+      <description>This command SHALL return the TLSClientCertificateDetailStruct for the passed in CCDID.</description>
+      <arg id="0" name="CCDID" type="int16u"/>
+    </command>
+
+    <command code="0x0C" source="server" name="FindClientCertificateResponse" optional="false" disableDefaultResponse="true">
+      <description>This command SHALL be generated in response to a FindClientCertificate command.</description>
+      <arg id="0" name="CertificateDetails" array="true" type="TLSClientCertificateDetailStruct"/>
+    </command>
+
+    <command code="0x0D" source="client" name="LookupClientCertificate" optional="false" response="LookupClientCertificateResponse">
+      <description>This command SHALL return the CCDID for the passed in Fingerprint.</description>
+      <arg id="0" name="Fingerprint" type="octet_string" length="64"/>
+    </command>
+
+    <command code="0x0E" source="server" name="LookupClientCertificateResponse" optional="false" disableDefaultResponse="true">
+      <description>This command SHALL be generated in response to a LookupClientCertificate command.</description>
+      <arg id="0" name="CCDID" type="int16u"/>
+    </command>
+
+    <command code="0x0F" source="client" name="RemoveClientCertificate" optional="false">
+      <description>This command SHALL be generated to request the Node removes the certificate provisioned to the provided Client Certificate Details ID.</description>
+      <access op="invoke" privilege="administer"/>
+      <arg id="0" name="CCDID" type="int16u"/>
+    </command>
+
+  </cluster>
+</configurator>
diff --git a/src/app/zap-templates/zcl/zcl-with-test-extensions.json b/src/app/zap-templates/zcl/zcl-with-test-extensions.json
@@ -127,6 +127,7 @@
         "time-format-localization-cluster.xml",
         "time-synchronization-cluster.xml",
         "timer-cluster.xml",
+        "tls-certificate-management-cluster.xml",
         "user-label-cluster.xml",
         "unit-localization-cluster.xml",
         "valve-configuration-and-control-cluster.xml",

diff --git a/src/app/zap-templates/zcl/zcl.json b/src/app/zap-templates/zcl/zcl.json
@@ -121,6 +121,7 @@
         "time-format-localization-cluster.xml",
         "time-synchronization-cluster.xml",
         "timer-cluster.xml",
+        "tls-certificate-management-cluster.xml",
         "user-label-cluster.xml",
         "unit-localization-cluster.xml",
         "valve-configuration-and-control-cluster.xml",

diff --git a/src/app/zap_cluster_list.json b/src/app/zap_cluster_list.json
@@ -123,6 +123,7 @@
         "TIME_FORMAT_LOCALIZATION_CLUSTER": [],
         "TIME_SYNCHRONIZATION_CLUSTER": [],
         "TIMER_CLUSTER": [],
+        "TLS_CERTIFICATE_MANAGEMENT_CLUSTER": [],
         "TRUSTED_ROOT_CERTIFICATES_CLUSTER": [],
         "UNIT_LOCALIZATION_CLUSTER": [],
         "UNIT_TESTING_CLUSTER": [],
@@ -307,6 +308,7 @@
         "TIME_FORMAT_LOCALIZATION_CLUSTER": ["time-format-localization-server"],
         "TIME_SYNCHRONIZATION_CLUSTER": ["time-synchronization-server"],
         "TIMER_CLUSTER": ["timer-server"],
+        "TLS_CERTIFICATE_MANAGEMENT_CLUSTER": [],
         "TVOC_CONCENTRATION_MEASUREMENT_CLUSTER": [
             "concentration-measurement-server"
         ],

diff --git a/src/controller/data_model/controller-clusters.matter b/src/controller/data_model/controller-clusters.matter
@@ -10441,6 +10441,121 @@ cluster CommissionerControl = 1873 {
   command access(invoke: manage) CommissionNode(CommissionNodeRequest): ReverseOpenCommissioningWindow = 1;
 }
 
+/** This Cluster is used to manage TLS Client Certificates and to provision
+      TLS endpoints with enough information to facilitate subsequent connection. */
+provisional cluster TlsCertificateManagement = 2049 {
+  revision 1;
+
+  struct TLSCertStruct {
+    int16u caid = 0;
+    long_octet_string<3000> certificate = 1;
+  }
+
+  struct TLSClientCertificateDetailStruct {
+    int16u ccdid = 0;
+    long_octet_string<3000> clientCertificate = 1;
+    octet_string intermediateCertificates[] = 2;
+  }
+
+  readonly attribute int8u maxRootCertificates = 0;
+  readonly attribute int8u currentRootCertificates = 1;
+  readonly attribute int8u maxClientCertificates = 2;
+  readonly attribute int8u currentClientCertificates = 3;
+  readonly attribute command_id generatedCommandList[] = 65528;
+  readonly attribute command_id acceptedCommandList[] = 65529;
+  readonly attribute event_id eventList[] = 65530;
+  readonly attribute attrib_id attributeList[] = 65531;
+  readonly attribute bitmap32 featureMap = 65532;
+  readonly attribute int16u clusterRevision = 65533;
+
+  request struct ProvisionRootCertificateRequest {
+    long_octet_string<3000> certificate = 0;
+    nullable int16u caid = 1;
+  }
+
+  response struct ProvisionRootCertificateResponse = 1 {
+    int16u caid = 0;
+  }
+
+  request struct FindRootCertificateRequest {
+    nullable int16u caid = 0;
+  }
+
+  response struct FindRootCertificateResponse = 3 {
+    TLSCertStruct certificateDetails[] = 0;
+  }
+
+  request struct LookupRootCertificateRequest {
+    octet_string<64> fingerprint = 0;
+  }
+
+  response struct LookupRootCertificateResponse = 5 {
+    int16u caid = 0;
+  }
+
+  request struct RemoveRootCertificateRequest {
+    int16u caid = 0;
+  }
+
+  request struct TLSClientCSRRequest {
+    octet_string nonce = 0;
+  }
+
+  response struct TLSClientCSRResponse = 8 {
+    int16u ccdid = 0;
+    octet_string csr = 1;
+    octet_string nonce = 2;
+  }
+
+  request struct ProvisionClientCertificateRequest {
+    int16u ccdid = 0;
+    TLSClientCertificateDetailStruct clientCertificateDetails = 1;
+  }
+
+  response struct ProvisionClientCertificateResponse = 10 {
+    int16u ccdid = 0;
+  }
+
+  request struct FindClientCertificateRequest {
+    int16u ccdid = 0;
+  }
+
+  response struct FindClientCertificateResponse = 12 {
+    TLSClientCertificateDetailStruct certificateDetails[] = 0;
+  }
+
+  request struct LookupClientCertificateRequest {
+    octet_string<64> fingerprint = 0;
+  }
+
+  response struct LookupClientCertificateResponse = 14 {
+    int16u ccdid = 0;
+  }
+
+  request struct RemoveClientCertificateRequest {
+    int16u ccdid = 0;
+  }
+
+  /** This command SHALL provision the provided certificate for the passed in CAID. */
+  command access(invoke: administer) ProvisionRootCertificate(ProvisionRootCertificateRequest): ProvisionRootCertificateResponse = 0;
+  /** This command SHALL return the TLSCertStruct for the passed in CAID. */
+  command FindRootCertificate(FindRootCertificateRequest): FindRootCertificateResponse = 2;
+  /** This command SHALL return the CAID for the passed in fingerprint. */
+  command LookupRootCertificate(LookupRootCertificateRequest): LookupRootCertificateResponse = 4;
+  /** This command SHALL be generated to request the server removes the certificate provisioned to the provided Certificate Authority ID. */
+  command access(invoke: administer) RemoveRootCertificate(RemoveRootCertificateRequest): DefaultSuccess = 6;
+  /** This command SHALL be generated to request the Node generates a Certificate Signing Request. */
+  command access(invoke: administer) TLSClientCSR(TLSClientCSRRequest): TLSClientCSRResponse = 7;
+  /** This command SHALL be generated to request the Node provisions the provided Client Certificate Details. */
+  command access(invoke: administer) ProvisionClientCertificate(ProvisionClientCertificateRequest): ProvisionClientCertificateResponse = 9;
+  /** This command SHALL return the TLSClientCertificateDetailStruct for the passed in CCDID. */
+  command FindClientCertificate(FindClientCertificateRequest): FindClientCertificateResponse = 11;
+  /** This command SHALL return the CCDID for the passed in Fingerprint. */
+  command LookupClientCertificate(LookupClientCertificateRequest): LookupClientCertificateResponse = 13;
+  /** This command SHALL be generated to request the Node removes the certificate provisioned to the provided Client Certificate Details ID. */
+  command access(invoke: administer) RemoveClientCertificate(RemoveClientCertificateRequest): DefaultSuccess = 15;
+}
+
 /** The Test Cluster is meant to validate the generated code */
 internal cluster UnitTesting = 4294048773 {
   revision 1; // NOTE: Default/not specifically set