Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Annotation of access control metadata to two clusters #11542

Closed
wants to merge 2 commits into from
Closed

Annotation of access control metadata to two clusters #11542

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
7b25c6f
https://github.com/project-chip/connectedhomeip/issues/10246
Nov 8, 2021
09376a8
Removed multiple op invoke privileges, as there can only be one privi…
Nov 12, 2021
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
36 changes: 31 additions & 5 deletions src/app/zap-templates/zcl/data-model/chip/onoff-cluster.xml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -48,39 +48,65 @@ limitations under the License.
<description>Attributes and commands for switching devices between 'On' and 'Off' states.</description>
<globalAttribute side="either" code="0xFFFD" value="4"/>

<attribute side="server" code="0x0000" define="ON_OFF" type="boolean" default="0" reportable="true" >OnOff</attribute>
<attribute side="server" code="0x4000" define="GLOBAL_SCENE_CONTROL" type="boolean" default="1" optional="true">GlobalSceneControl</attribute>
<attribute side="server" code="0x4001" define="ON_TIME" type="int16u" default="0" writable="true" optional="true">OnTime</attribute>
<attribute side="server" code="0x4002" define="OFF_WAIT_TIME" type="int16u" default="0" writable="true" optional="true">OffWaitTime</attribute>
<attribute side="server" code="0x4003" define="START_UP_ON_OFF" type="enum8" writable="true" optional="true">StartUpOnOff</attribute>
<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>
<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>
<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>
<attribute side="server" code="0x4002" define="OFF_WAIT_TIME" type="int16u" default="0" writable="true" optional="true">
<description>OffWaitTime</description>
<access op="read" privilege="view"/>
<access op="write" privilege="operate"/>
</attribute>
<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>

<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="operate"/>
</command>

<command source="client" code="0x01" name="On" optional="false">
<description>On receipt of this command, a device SHALL enter its ‘On’ state. This state is device dependent, but it is recommended that it is used for power on or similar functions. On receipt of the On command, if the value of the OnTime attribute is equal to 0, the device SHALL set the OffWaitTime attribute to 0.</description>
<access op="invoke" privilege="operate"/>
</command>

<command source="client" code="0x02" name="Toggle" optional="false">
<description>On receipt of this command, if a device is in its ‘Off’ state it SHALL enter its ‘On’ state. Otherwise, if it is in its ‘On’ state it SHALL enter its ‘Off’ state. On receipt of the Toggle command, if the value of the OnOff attribute is equal to FALSE and if the value of the OnTime attribute is equal to 0, the device SHALL set the OffWaitTime attribute to 0. If the value of the OnOff attribute is equal to TRUE, the OnTime attribute SHALL be set to 0.</description>
<access op="invoke" privilege="operate"/>
</command>

<command source="client" code="0x40" name="OffWithEffect" optional="true">
<description>The OffWithEffect command allows devices to be turned off using enhanced ways of fading.</description>
<arg name="EffectId" type="OnOffEffectIdentifier"/>
<arg name="EffectVariant" type="OnOffDelayedAllOffEffectVariant"/>
<access op="invoke" privilege="operate"/>
</command>

<command source="client" code="0x41" name="OnWithRecallGlobalScene" optional="true">
<description>The OnWithRecallGlobalScene command allows the recall of the settings when the device was turned off.</description>
<access op="invoke" privilege="operate"/>
</command>

<command source="client" code="0x42" name="OnWithTimedOff" optional="true">
<description>The OnWithTimedOff command allows devices to be turned on for a specific duration with a guarded off duration so that SHOULD the device be subsequently switched off, further OnWithTimedOff commands, received during this time, are prevented from turning the devices back on.</description>
<arg name="OnOffControl" type="OnOffControl"/>
<arg name="OnTime" type="int16u"/><!-- min:0 max:0xfe -->
<arg name="OffWaitTime" type="int16u"/><!-- min:0 max:0xfe -->
<access op="invoke" privilege="operate"/>
</command>

</cluster>
Expand Down
83 changes: 58 additions & 25 deletions src/app/zap-templates/zcl/data-model/chip/operational-credentials-cluster.xml
View file
Open in desktop
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"/>
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Is isFabricSensitive an alias for the equivalent of an access tag?

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This was suggested on Nov 1st: https://csamembers.slack.com/archives/C02FTN42KEE/p1635797498010800?thread_ts=1635795804.009300&cid=C02FTN42KEE

<item fieldId="2" name="ICAC" type="OCTET_STRING" length="400" isFabricSensitive="true" isNullable="true"/>
</struct>

<cluster>
Expand All @@ -54,16 +57,38 @@ 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>

<attribute side="server" code="0x0001" define="FABRICS" type="ARRAY" entryType="FabricDescriptor" length="320" writable="false" optional="false">fabrics list</attribute>
<attribute side="server" code="0x0002" define="SUPPORTED_FABRICS" type="INT8U" writable="false" optional="false">SupportedFabrics</attribute>
<attribute side="server" code="0x0003" define="COMMISSIONED_FABRICS" type="INT8U" writable="false" optional="false">CommissionedFabrics</attribute>
<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"/>
<access modifier="fabric-scoped"/>
</attribute>
<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"/>
<access modifier="fabric-scoped"/>
</attribute>
<attribute side="server" code="0x0002" define="SUPPORTED_FABRICS" type="INT8U" writable="false" optional="false">
<description>SupportedFabrics</description>
<access op="read" privilege="view"/>
</attribute>
<attribute side="server" code="0x0003" define="COMMISSIONED_FABRICS" type="INT8U" writable="false" optional="false">
<description>CommissionedFabrics</description>
<access op="read" privilege="view"/>
</attribute>
<!-- 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">TrustedRootCertificates</attribute>
<attribute side="server" code="0x0005" define="CURRENT_FABRIC_INDEX" type="fabric_idx" writable="false" optional="false">CurrentFabricIndex</attribute>
<attribute side="server" code="0x0004" define="TRUSTED_ROOTS" type="ARRAY" entryType="OCTET_STRING" length="400" writable="false" optional="false">
Comment on lines 78 to +79
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The 400 length for an array here doesn't make sense

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This is the topic that needs group resolution :)

<description>TrustedRootCertificates</description>
<access op="read" privilege="view"/>
</attribute>
<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>

<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"/>
<access op="invoke" privilege="administer"/>
</command>

<command source="server" code="0x01" name="AttestationResponse" optional="false">
Expand All @@ -75,6 +100,7 @@ limitations under the License.
<command source="client" code="0x02" name="CertificateChainRequest" optional="false">
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Add response="CertificateChainResponse"

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Did the comment refer to the already existing response?

    <command source="server" code="0x03" name="CertificateChainResponse" optional="false">
      <description>A device attestation certificate (DAC) or product attestation intermediate (PAI) certificate from the server.</description>
      <arg name="Certificate" type="OCTET_STRING"/>
    </command>

<description>Sender is requesting a device attestation certificate from the receiver.</description>
<arg name="CertificateType" type="INT8U"/>
<access op="invoke" privilege="administer"/>
</command>

<command source="server" code="0x03" name="CertificateChainResponse" optional="false">
Expand All @@ -85,6 +111,7 @@ limitations under the License.
<command source="client" code="0x04" name="OpCSRRequest" optional="false">
<description>Sender is requesting a certificate signing request (CSR) from the receiver.</description>
<arg name="CSRNonce" type="OCTET_STRING"/>
<access op="invoke" privilege="administer"/>
</command>

<!-- TODO: Fix to match chip-spec:#3346 -->
Expand All @@ -101,39 +128,45 @@ limitations under the License.
<arg name="IPKValue" type="OCTET_STRING"/>
<arg name="CaseAdminNode" type="NODE_ID"/>
<arg name="AdminVendorId" type="INT16U"/>
<access op="invoke" privilege="administer"/>
</command>

<command source="client" code="0x07" name="UpdateNOC" response="NOCResponse" optional="false">
<description>Sender is requesting to update the node operational certificates.</description>
<arg name="NOCValue" type="OCTET_STRING"/>
<arg name="ICACValue" type="OCTET_STRING" optional="true"/>
<access op="invoke" privilege="administer"/>
</command>

<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"/>
Comment on lines 143 to 145
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Need the field IDs for these args

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

None of the cluster xml files include a fieldId in the attributes. To make sure I understand the requirement, is this format correct?

    <command source="server" code="0x08" name="NOCResponse" optional="false">
      <description>Response to AddNOC or UpdateNOC commands.</description>
      <arg fieldId="0" name="StatusCode" type="INT8U"/>
      <arg fieldId="1" name="FabricIndex" type="fabric_idx"/>
      <arg fieldId="2" name="DebugText" type="CHAR_STRING"/>
    </command>

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The last commit made the above assumption. If incorrect, we can rollback the changes and work on determining the right format.

</command>

<command source="client" code="0x09" name="UpdateFabricLabel" response="NOCResponse" optional="false">
<description>This command SHALL be used by an Administrative Node to set the user-visible Label field for a given Fabric, as reflected by entries in the Fabrics attribute.</description>
<arg name="Label" type="CHAR_STRING" length="32"/>
<access op="invoke" privilege="administer"/>
</command>

<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>

<command source="client" code="0x0b" name="AddTrustedRootCertificate" optional="false">
<description>This command SHALL add a Trusted Root CA Certificate, provided as its CHIP Certificate representation.</description>
<arg name="RootCertificate" type="OCTET_STRING"/>
<access op="invoke" privilege="administer"/>
</command>

<command source="client" code="0x0c" name="RemoveTrustedRootCertificate" optional="false">
<description>This command SHALL remove a Trusted Root CA Certificate, provided as its CHIP Certificate representation.</description>
<arg name="TrustedRootIdentifier" type="OCTET_STRING"/>
<access op="invoke" privilege="administer"/>
</command>

</cluster>
Expand Down