Skip to content

Commit

Permalink
Rebased accessControlClustersAnnotations to upstream/master.
Browse files Browse the repository at this point in the history 
operational-credentials-cluster.xml and onoff-cluster.xml based on received feedback:
    normalized the <access> elements. Note that the writeable <attribute> attribute indicates if a field is writeable, or not. The <access> elements qualifies provileges on a per operation basis.

operational-credentials-cluster.xml:
    updated all <struct> elements to include <item> fieldId;
    updated NodeOperationalCertStatus to include missing item elements;
    updated NOCStruct to include a missing item element;
    project-chip#11286: normalized fabric_idx usage across;
  • Loading branch information
Eugen Feraru committed Nov 2, 2021
1 parent ace0aea commit d65c45f
Show file tree
Hide file tree
Showing 2 changed files with 33 additions and 229 deletions.
95 changes: 6 additions & 89 deletions src/app/zap-templates/zcl/data-model/chip/onoff-cluster.xml
View file
Original file line number Diff line number Diff line change
Expand Up @@ -48,115 +48,32 @@ limitations under the License.
<description>Attributes and commands for switching devices between 'On' and 'Off' states.</description>
<globalAttribute side="either" code="0xFFFD" value="4"/>

<!--
Definition (OnOff.adoc):
| ID | Name | Type | Constraint | Quality | Default | Access | Conformance
| 0x0000 | OnOff | bool | all | SN | FALSE | R V | M
<access/> Design Rationale:
Per Definition:
Operation: R(ead) only. I.e. Write is inferred as not allowed.
Role/Privilege: V(iew)
Modifier: None
-->
<attribute side="server" code="0x0000" define="ON_OFF" type="boolean" default="0" reportable="true" optional="false">
<attribute side="server" code="0x0000" define="ON_OFF" type="boolean" default="0" writable="false" reportable="true" optional="false">
<description>OnOff</description>
<access op="read" privilege="view"/>
</attribute>

<!--
Definition (OnOff.adoc):
| ID | Name | Type | Constraint | Quality | Default | Access | Conformance
| 0x4000 | GlobalSceneControl | bool | all | | TRUE | R V | LT
<access/> Design Rationale:
Per Definition:
Operation: R(ead) only. I.e. Write is inferred as not allowed.
Role/Privilege: V(iew)
Modifier: None
-->
<attribute side="server" code="0x4000" define="GLOBAL_SCENE_CONTROL" type="boolean" default="1" optional="true">
<attribute side="server" code="0x4000" define="GLOBAL_SCENE_CONTROL" type="boolean" default="1" writable="false" optional="true">
<description>GlobalSceneControl</description>
<access op="read" privilege="view"/>
</attribute>

<!--
Definition (OnOff.adoc):
| ID | Name | Type | Constraint | Quality | Default | Access | Conformance
| 0x4001 | OnTime | uint16 | all | | 0 | RW VO | LT
<access/> Design Rationale:
Per Definition:
Operation: R(ead)
W(rite)
Role/Privilege: V(iew) for Read
O(perate) for Write
Modifier: None
-->
<attribute side="server" code="0x4001" define="ON_TIME" type="int16u" writable="true" optional="true">
<attribute side="server" code="0x4001" define="ON_TIME" type="int16u" default="0" writable="true" optional="true">
<description>OnTime</description>
<!-- The following required access privileges are the default, and could have been
omitted, but are included here as an example. -->
<access op="read" privilege="view"/>
<access op="write" privilege="operate"/>
</attribute>

<!--
Definition (OnOff.adoc):
| ID | Name | Type | Constraint | Quality | Default | Access | Conformance
| 0x4002 | OffWaitTime | uint16 | all | | 0 | RW VO | LT
<access/> Design Rationale:
Per Definition:
Operation: R(ead)
W(rite)
Role/Privilege: V(iew) for Read
O(perate) for Write
Modifier: None
-->
<attribute side="server" code="0x4002" define="OFF_WAIT_TIME" type="int16u" default="0" writable="true" optional="true">
<description>OffWaitTime</description><!-- Example considers the R V combination. XSL parser to verify if (R) then V else if (W) then O -->
<description>OffWaitTime</description>
<access op="read" privilege="view"/>
<access op="write" privilege="operate"/>
</attribute>

<!--
Definition (OnOff.adoc):
| ID | Name | Type | Constraint | Quality | Default | Access | Conformance
| 0x4003 | StartUpOnOff | enum8 | desc | N | MS | RW VM | LT
<access/> Design Rationale:
Per Definition:
Operation: R(ead)
W(rite)
Role/Privilege: V(iew) for Read
M(anage) for Write
Modifier: None
-->
<attribute side="server" code="0x4003" define="START_UP_ON_OFF" type="enum8" writable="true" optional="true">
<description>StartUpOnOff</description>
<access op="read" privilege="view"/>
<access op="write" privilege="operate"/>
</attribute>

<!--
Since all Commands for the OnOff Cluster have the same access,
the definition is listed only once.
Definition (OperationalCredentialCluster.adoc):
| ID | Name | Direction | Response | Access | Conformance
| 0x00 | Off | client => server | Y | VO | M
| 0x01 | On | client => server | Y | VO | M
| 0x02 | Toggle | client => server | Y | VO | M
| 0x40 | OffWithEffect | client => server | Y | VO | O
| 0x41 | OnWithRecallGlobalScene | client => server | Y | VO | O
| 0x42 | OnWithTimedOff | client => server | Y | VO | O
<access/> Design Rationale:
Per Definition:
Operation: Invoke (by default)
Role/Privilege: There are two privileges listed: View and Operate. Thus, it is assumed, that EITHER of them would allow
the "Invoke" operation to go through. As such, both provileges are listed.
Modifier: None
-->
<command source="client" code="0x00" name="Off" optional="false">
<description>On receipt of this command, a device SHALL enter its ‘Off’ state. This state is device dependent, but it is recommended that it is used for power off or similar functions. On receipt of the Off command, the OnTime attribute SHALL be set to 0.</description>
<access op="invoke" privilege="view"/>
Expand Down
167 changes: 27 additions & 140 deletions src/app/zap-templates/zcl/data-model/chip/operational-credentials-cluster.xml
View file
Original file line number Diff line number Diff line change
Expand Up @@ -19,32 +19,35 @@ limitations under the License.

<struct name="FabricDescriptor">
<cluster code="0x003E"/>
<item name="FabricIndex" type="INT8U"/>
<item name="RootPublicKey" type="OCTET_STRING" length="65"/>
<item name="VendorId" type="INT16U"/> <!-- Change INT16U to new type VendorID #2395 -->
<item name="FabricId" type="FABRIC_ID"/>
<item name="NodeId" type="NODE_ID"/>
<item name="Label" type="CHAR_STRING" length="32"/>
<item fieldId="0" name="FabricIndex" type="fabric_idx"/>
<item fieldId="1" name="RootPublicKey" type="OCTET_STRING" length="65"/>
<item fieldId="2" name="VendorId" type="INT16U"/> <!-- Change INT16U to new type VendorID #2395 -->
<item fieldId="3" name="FabricId" type="FABRIC_ID"/>
<item fieldId="4" name="NodeId" type="NODE_ID"/>
<item fieldId="5" name="Label" type="CHAR_STRING" length="32"/>
</struct>

<enum name="NodeOperationalCertStatus" type="ENUM8">
<cluster code="0x003E"/>
<item name="SUCCESS" value="0x00"/>
<item name="InvalidPublicKey" value="0x01"/>
<item name="InvalidNodeOpId" value="0x02"/>
<item name="InvalidNOC" value="0x03"/>
<item name="MissingCsr" value="0x04"/>
<item name="TableFull" value="0x05"/>
<item name="InsufficientPrivilege" value="0x08"/>
<item name="FabricConflict" value="0x09"/>
<item name="LabelConflict" value="0x0a"/>
<item name="InvalidFabricIndex" value="0x0b"/>
<item fieldId="0" name="SUCCESS" value="0x00"/>
<item fieldId="1" name="InvalidPublicKey" value="0x01"/>
<item fieldId="2" name="InvalidNodeOpId" value="0x02"/>
<item fieldId="3" name="InvalidNOC" value="0x03"/>
<item fieldId="4" name="MissingCsr" value="0x04"/>
<item fieldId="5" name="TableFull" value="0x05"/>
<item fieldId="6" name="MissingACL" value="0x06"/>
<item fieldId="7" name="MissingIpk" value="0x07"/>
<item fieldId="8" name="InsufficientPrivilege" value="0x08"/>
<item fieldId="9" name="FabricConflict" value="0x09"/>
<item fieldId="10" name="LabelConflict" value="0x0a"/>
<item fieldId="11" name="InvalidFabricIndex" value="0x0b"/>
</enum>

<struct name="NOCStruct">
<cluster code="0x003E"/>
<item name="FabricIndex" type="INT8U"/>
<item name="NOC" type="OCTET_STRING"/>
<item fieldId="0" name="FabricIndex" type="fabric_idx"/>
<item fieldId="1" name="NOC" type="OCTET_STRING" length="400" isFabricSensitive="true"/>
<item fieldId="2" name="ICAC" type="OCTET_STRING" length="400" isFabricSensitive="true" isNullable="true"/>
</struct>

<cluster>
Expand All @@ -54,150 +57,34 @@ limitations under the License.
<define>OPERATIONAL_CREDENTIALS_CLUSTER</define>
<description>This cluster is used to add or remove Operational Credentials on a Commissionee or Node, as well as manage the associated Fabrics.</description>

<!--
General Notes regarding this proposed design:
(1) OperationalCredentialCluster.adoc has been used to provide the definitions for attributes and commands, includig the access control definitions.
(2) Some of the attributes were either completely added, or updated in this cluster, and some were missing or having incorrect elements.
Did so to help focus on the <access> elements for each of them, as for accuracy while presenting this proposed design.
-->

<!--
Definition (OperationalCredentialCluster.adoc):
| Id | Name | Type | Constraint | Quality | Default | Access | Conformance
| 0 | NOCs | <<list-def>>[<<ref_NOCStruct,NOCStruct>>] | max SupportedFabrics | N | | R A F | M
<access/> Design Rationale:
Per Definition:
Operation: R(ead) only. I.e. Write is inferred as not allowed.
Role/Privilege: A(dminister)
Modifier: F(abric-scoped)
Other notes:
Newly added attribute, as per the spec, as it was not included.
-->
<attribute side="server" code="0x0000" define="NOCs" type="ARRAY" entryType="NOCStruct" length="320" writable="false" optional="false">
<description>NOCs</description>
<access op="read" privilege="administer" modifier="fabric-scoped"/>
<access op="read" privilege="administer"/>
<access modifier="fabric-scoped"/>
</attribute>

<!--
Definition (OperationalCredentialCluster.adoc):
| Id | Name | Type | Constraint | Quality | Default | Access | Conformance
| 1 | Fabrics | <<list-def>>[FabricDescriptorStruct] | max SupportedFabrics | N | | R V F | M
<access/> Design Rationale:
Per Definition:
Operation: R(ead) only. I.e. Write is inferred as not allowed.
Role/Privilege: V(iew)
Modifier: F(abric-scoped)
Other notes:
Updated attribute description, as per the spec.
-->
<attribute side="server" code="0x0001" define="FABRICS" type="ARRAY" entryType="FabricDescriptor" length="320" writable="false" optional="false">
<description>Fabrics</description>
<access op="read" privilege="view" modifier="fabric-scoped"/>
<access op="read" privilege="view"/>
<access modifier="fabric-scoped"/>
</attribute>

<!--
Definition:
| Id | Name | Type | Constraint | Quality | Default | Access | Conformance
| 2 | SupportedFabrics | uint8 | 5 to 255 | F | | R V | M
<access/> Design Rationale:
Per Definition:
Operation: R(ead) only. I.e. Write is inferred as not allowed.
Role/Privilege: V(iew)
Modifier: None
-->
<attribute side="server" code="0x0002" define="SUPPORTED_FABRICS" type="INT8U" writable="false" optional="false">
<description>SupportedFabrics</description>
<access op="read" privilege="view"/>
</attribute>

<!--
Definition:
| Id | Name | Type | Constraint | Quality | Default | Access | Conformance
| 3 | CommissionedFabrics | uint8 | max SupportedFabrics | N | | R V | M
<access/> Design Rationale:
Per Definition:
Operation: R(ead) only. I.e. Write is inferred as not allowed.
Role/Privilege: V(iew)
Modifier: None
-->
<attribute side="server" code="0x0003" define="COMMISSIONED_FABRICS" type="INT8U" writable="false" optional="false">
<description>CommissionedFabrics</description>
<access op="read" privilege="view"/>
</attribute>

<!--
Definition:
| Id | Name | Type | Constraint | Quality | Default | Access | Conformance
| 4 | TrustedRootCertificates | <<list-def>>[<<octstr-def>>] | max SupportedFabrics | N | | R V | M
<access/> Design Rationale:
Per Definition:
Operation: R(ead) only. I.e. Write is inferred as not allowed.
Role/Privilege: V(iew)
Modifier: None
-->
<!-- 400 = 400 bytes for root cert -->
<attribute side="server" code="0x0004" define="TRUSTED_ROOTS" type="ARRAY" entryType="OCTET_STRING" length="400" writable="false" optional="false">
<description>TrustedRootCertificates</description>
<access op="read" privilege="view"/>
</attribute>

<!--
Definition:
| Id | Name | Type | Constraint | Quality | Default | Access | Conformance
| 5 | CurrentFabricIndex | uint8 | | | 0 | R V | M
<access/> Design Rationale:
Per Definition:
Operation: R(ead) only. I.e. Write is inferred as not allowed.
Role/Privilege: V(iew)
Modifier: None
-->
<attribute side="server" code="0x0005" define="CURRENT_FABRIC_INDEX" type="fabric_idx" writable="false" optional="false">
<description>CurrentFabricIndex</description>
<access op="read" privilege="view"/>
</attribute>





<!--
Since all Commands for the Operational Credential Cluster have the same access,
the definition is listed only once.
Definition (OperationalCredentialCluster.adoc):
| 0 | AttestationRequest | Client => Server | AttestationResponse | A | M
| 1 | AttestationResponse | Server => Client | N | A | M
| 2 | CertificateChainRequest | Client => Server | CertificateChainResponse | A | M
| 3 | CertificateChainResponse | Server => Client | N | A | M
| 4 | CSRRequest | Client => Server | CSRResponse | A | M
| 5 | CSRResponse | Server => Client | N | A | M
| 6 | AddNOC | Client => Server | NOCResponse | A | M
| 7 | UpdateNOC | Client => Server | NOCResponse | A | M
| 8 | NOCResponse | Server => Client | N | A | M
| 9 | UpdateFabricLabel | Client => Server | NOCResponse | A | M
| 10 | RemoveFabric | Client => Server | NOCResponse | A | M
| 11 | AddTrustedRootCertificate | Client => Server | Y | A | M
| 12 | RemoveTrustedRootCertificate | Client => Server | Y | A | M
<access/> Design Rationale:
Per Definition:
Operation: Invoke (by default)
Role/Privilege: A(dminister)
Modifier: None
-->
<command source="client" code="0x00" name="AttestationRequest" optional="false">
<description>Sender is requesting attestation information from the receiver.</description>
<arg name="AttestationNonce" type="OCTET_STRING"/>
Expand Down Expand Up @@ -257,7 +144,7 @@ limitations under the License.
<command source="server" code="0x08" name="NOCResponse" optional="false">
<description>Response to AddNOC or UpdateNOC commands.</description>
<arg name="StatusCode" type="INT8U"/>
<arg name="FabricIndex" type="INT8U"/>
<arg name="FabricIndex" type="fabric_idx"/>
<arg name="DebugText" type="CHAR_STRING"/>
<access op="invoke" privilege="administer"/>
</command>
Expand All @@ -270,7 +157,7 @@ limitations under the License.

<command source="client" code="0x0a" name="RemoveFabric" response="NOCResponse" optional="false">
<description>This command is used by Administrative Nodes to remove a given fabric index and delete all associated fabric-scoped data.</description>
<arg name="FabricIndex" type="INT8U"/>
<arg name="FabricIndex" type="fabric_idx"/>
<access op="invoke" privilege="administer"/>
</command>

Expand Down

0 comments on commit d65c45f

Please sign in to comment.