Implement Terms and Conditions into Commissioning Workflow

Enabled Terms and Conditions for chip-all-clusters-app

Add support for terms and conditions check and enhanced setup flow

This commit adds support for terms and conditions (TC) check and
enhances the setup flow as part of the Connected Home over IP (CHIP)
Specification 1.4.

Changes include:

- Extended support for terms and conditions check and enhanced setup
  flow feature as part of the connectedhomeip spec 1.4.
- Added functionality to retrieve and store Terms and Conditions (TC)
  information, including accepted version, minimum required version,
  acknowledgements, and required acknowledgements.
- Implemented methods in `TermsAndConditionsManager` to handle TC
  versioning and acknowledgements.
- Updated `GeneralCommissioningAttrAccess` to include support for
  reading TC-related attributes.
- Added callback functions in `emberAfGeneralCommissioningCluster` to
  handle TC acknowledgements during commissioning.
- Integrated `TermsAndConditionsManager` into the server context for
  managing TC-related information.
- Enhanced error handling and logging for TC-related operations.
- Adjusted build configuration to include default values for TC
  versioning and acknowledgements.
- Expanded configuration management in `ConfigurationManagerImpl` to
  handle TC-related configuration keys.
- Updated `PosixConfig` to include configuration keys for TC-related
  information.
- Implemented default values for TC versioning and acknowledgements in
  `ConfigurationManagerImpl`.

Implement Terms and Conditions Acknowledgements in AutoCommissioner

This commit adds the necessary logic to AutoCommissioner.cpp and
CHIPDeviceController.cpp to facilitate the sending of Terms and
Conditions acknowledgements commands during the commissioning process.
This enhancement ensures that the commissioning workflow includes the
crucial step of acknowledging Terms and Conditions, contributing to a
more robust and comprehensive device setup.

examples/all-clusters-app/all-clusters-common/all-clusters-app.zap

@@ -2171,6 +2171,22 @@
               "source": "server",
               "isIncoming": 0,
               "isEnabled": 1
+            },
+            {
+              "name": "SetTCAcknowledgements",
+              "code": 6,
+              "mfgCode": null,
+              "source": "client",
+              "isIncoming": 1,
+              "isEnabled": 1
+            },
+            {
+              "name": "SetTCAcknowledgementsResponse",
+              "code": 7,
+              "mfgCode": null,
+              "source": "server",
+              "isIncoming": 0,
+              "isEnabled": 1
             }
           ],
           "attributes": [
@@ -2254,6 +2270,70 @@
               "maxInterval": 65534,
               "reportableChange": 0
             },
+            {
+              "name": "TCAcceptedVersion",
+              "code": 5,
+              "mfgCode": null,
+              "side": "server",
+              "type": "int16u",
+              "included": 1,
+              "storageOption": "RAM",
+              "singleton": 0,
+              "bounded": 0,
+              "defaultValue": "",
+              "reportable": 1,
+              "minInterval": 1,
+              "maxInterval": 65534,
+              "reportableChange": 0
+            },
+            {
+              "name": "TCMinRequiredVersion",
+              "code": 6,
+              "mfgCode": null,
+              "side": "server",
+              "type": "int16u",
+              "included": 1,
+              "storageOption": "RAM",
+              "singleton": 0,
+              "bounded": 0,
+              "defaultValue": "1",
+              "reportable": 1,
+              "minInterval": 1,
+              "maxInterval": 65534,
+              "reportableChange": 0
+            },
+            {
+              "name": "TCAcknowledgements",
+              "code": 7,
+              "mfgCode": null,
+              "side": "server",
+              "type": "bitmap16",
+              "included": 1,
+              "storageOption": "RAM",
+              "singleton": 0,
+              "bounded": 0,
+              "defaultValue": "0x0000",
+              "reportable": 1,
+              "minInterval": 1,
+              "maxInterval": 65534,
+              "reportableChange": 0
+            },
+            {
+              "name": "TCAcknowledgementsRequired",
+              "code": 8,
+              "mfgCode": null,
+              "side": "server",
+              "type": "boolean",
+              "included": 1,
+              "storageOption": "RAM",
+              "singleton": 0,
+              "bounded": 0,
+              "defaultValue": "true",
+              "reportable": 1,
+              "minInterval": 1,
+              "maxInterval": 65534,
+              "reportableChange": 0
+            },
             {
               "name": "GeneratedCommandList",
               "code": 65528,
@@ -2328,7 +2408,7 @@
               "storageOption": "RAM",
               "singleton": 0,
               "bounded": 0,
-              "defaultValue": "0",
+              "defaultValue": "1",
               "reportable": 1,
               "minInterval": 1,
               "maxInterval": 65534,

examples/chip-tool/commands/pairing/PairingCommand.cpp

@@ -1,5 +1,5 @@
 /*
- *   Copyright (c) 2020 Project CHIP Authors
+ *   Copyright (c) 2020-2024 Project CHIP Authors
  *   All rights reserved.
  *
  *   Licensed under the Apache License, Version 2.0 (the "License");
@@ -118,6 +118,12 @@ CommissioningParameters PairingCommand::GetCommissioningParameters()
         params.SetCountryCode(CharSpan::fromCharString(mCountryCode.Value()));
     }
 
+    if (mTCAcknowledgements.HasValue() && mTCAcknowledgementVersion.HasValue())
+    {
+        params.SetTCAcknowledgements(mTCAcknowledgements.Value());
+        params.SetTCAcknowledgementVersion(mTCAcknowledgementVersion.Value());
+    }
+
     // mTimeZoneList is an optional argument managed by TypedComplexArgument mComplex_TimeZones.
     // Since optional Complex arguments are not currently supported via the <chip::Optional> class,
     // we will use mTimeZoneList.data() value to determine if the argument was provided.

examples/chip-tool/commands/pairing/PairingCommand.h

@@ -1,5 +1,5 @@
 /*
- *   Copyright (c) 2020 Project CHIP Authors
+ *   Copyright (c) 2020-2024 Project CHIP Authors
  *   All rights reserved.
  *
  *   Licensed under the Apache License, Version 2.0 (the "License");
@@ -55,8 +55,7 @@ class PairingCommand : public CHIPCommand,
     PairingCommand(const char * commandName, PairingMode mode, PairingNetworkType networkType,
                    CredentialIssuerCommands * credIssuerCmds,
                    chip::Dnssd::DiscoveryFilterType filterType = chip::Dnssd::DiscoveryFilterType::kNone) :
-        CHIPCommand(commandName, credIssuerCmds),
-        mPairingMode(mode), mNetworkType(networkType), mFilterType(filterType),
+        CHIPCommand(commandName, credIssuerCmds), mPairingMode(mode), mNetworkType(networkType), mFilterType(filterType),
         mRemoteAddr{ IPAddress::Any, chip::Inet::InterfaceId::Null() }, mComplex_TimeZones(&mTimeZoneList),
         mComplex_DSTOffsets(&mDSTOffsetList), mCurrentFabricRemoveCallback(OnCurrentFabricRemove, this)
     {
@@ -182,6 +181,14 @@ class PairingCommand : public CHIPCommand,
             AddArgument("dst-offset", &mComplex_DSTOffsets,
                         "DSTOffset list to use when setting Time Synchronization cluster's DSTOffset attribute",
                         Argument::kOptional);
+
+            AddArgument("tc-acknowledgements", 0, UINT16_MAX, &mTCAcknowledgements,
+                        "Terms and Conditions acknowledgements to use to set the General Commissioning cluster's TC "
+                        "Acknowledgements bit-field");
+
+            AddArgument("tc-acknowledgement-version", 0, UINT16_MAX, &mTCAcknowledgementVersion,
+                        "Terms and Conditions acknowledgement version to use to set the General Commissioning cluster's TC "
+                        "Acknowledgement version");
         }
 
         AddArgument("timeout", 0, UINT16_MAX, &mTimeout);
@@ -233,6 +240,8 @@ class PairingCommand : public CHIPCommand,
     chip::Optional<bool> mBypassAttestationVerifier;
     chip::Optional<std::vector<uint32_t>> mCASEAuthTags;
     chip::Optional<char *> mCountryCode;
+    chip::Optional<uint16_t> mTCAcknowledgements;
+    chip::Optional<uint16_t> mTCAcknowledgementVersion;
     chip::Optional<bool> mSkipICDRegistration;
     chip::Optional<NodeId> mICDCheckInNodeId;
     chip::Optional<chip::ByteSpan> mICDSymmetricKey;

src/app/clusters/general-commissioning-server/general-commissioning-server.cpp

@@ -1,6 +1,6 @@
 /**
  *
- *    Copyright (c) 2021 Project CHIP Authors
+ *    Copyright (c) 2021-2024 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.
@@ -66,7 +66,8 @@ class GeneralCommissioningAttrAccess : public AttributeAccessInterface
     CHIP_ERROR Read(const ConcreteReadAttributePath & aPath, AttributeValueEncoder & aEncoder) override;
 
 private:
-    CHIP_ERROR ReadIfSupported(CHIP_ERROR (ConfigurationManager::*getter)(uint8_t &), AttributeValueEncoder & aEncoder);
+    template <typename T>
+    CHIP_ERROR ReadIfSupported(CHIP_ERROR (ConfigurationManager::*getter)(T &), AttributeValueEncoder & aEncoder);
     CHIP_ERROR ReadBasicCommissioningInfo(AttributeValueEncoder & aEncoder);
     CHIP_ERROR ReadSupportsConcurrentConnection(AttributeValueEncoder & aEncoder);
 };
@@ -95,17 +96,29 @@ CHIP_ERROR GeneralCommissioningAttrAccess::Read(const ConcreteReadAttributePath
     case SupportsConcurrentConnection::Id: {
         return ReadSupportsConcurrentConnection(aEncoder);
     }
-    default: {
-        break;
+    case TCAcceptedVersion::Id: {
+        return ReadIfSupported(&ConfigurationManager::GetTCAcceptedVersion, aEncoder);
+    }
+    case TCMinRequiredVersion::Id: {
+        return ReadIfSupported(&ConfigurationManager::GetTCMinRequiredVersion, aEncoder);
+    }
+    case TCAcknowledgements::Id: {
+        return ReadIfSupported(&ConfigurationManager::GetTCAcknowledgements, aEncoder);
     }
+    case TCAcknowledgementsRequired::Id: {
+        return ReadIfSupported(&ConfigurationManager::GetTCAcknowledgementsRequired, aEncoder);
+    }
+    default:
+        break;
     }
     return CHIP_NO_ERROR;
 }
 
-CHIP_ERROR GeneralCommissioningAttrAccess::ReadIfSupported(CHIP_ERROR (ConfigurationManager::*getter)(uint8_t &),
+template <typename T>
+CHIP_ERROR GeneralCommissioningAttrAccess::ReadIfSupported(CHIP_ERROR (ConfigurationManager::*getter)(T &),
                                                            AttributeValueEncoder & aEncoder)
 {
-    uint8_t data;
+    T data;
     CHIP_ERROR err = (DeviceLayer::ConfigurationMgr().*getter)(data);
     if (err == CHIP_ERROR_UNSUPPORTED_CHIP_FEATURE)
     {
@@ -214,9 +227,10 @@ bool emberAfGeneralCommissioningClusterCommissioningCompleteCallback(
 {
     MATTER_TRACE_SCOPE("CommissioningComplete", "GeneralCommissioning");
 
-    DeviceControlServer * devCtrl = &DeviceLayer::DeviceControlServer::DeviceControlSvr();
-    auto & failSafe               = Server::GetInstance().GetFailSafeContext();
-    auto & fabricTable            = Server::GetInstance().GetFabricTable();
+    DeviceControlServer * devCtrl    = &DeviceLayer::DeviceControlServer::DeviceControlSvr();
+    auto & failSafe                  = Server::GetInstance().GetFailSafeContext();
+    auto & fabricTable               = Server::GetInstance().GetFabricTable();
+    auto & termsAndConditionsManager = Server::GetInstance().GetTermsAndConditionsManager();
 
     ChipLogProgress(FailSafe, "GeneralCommissioning: Received CommissioningComplete");
 
@@ -239,34 +253,58 @@ bool emberAfGeneralCommissioningClusterCommissioningCompleteCallback(
         }
         else
         {
-            if (failSafe.NocCommandHasBeenInvoked())
+            CHIP_ERROR err;
+
+            // Fetch the terms and conditions acknowledgements for verification
+            uint16_t tcAcceptedVersion = 0U, tcMinRequiredVersion = 0U, tcAcknowledgements = 0U, tcAcknowledgementsRequired = 0U;
+
+            err = termsAndConditionsManager.GetTCAcceptedVersion(tcAcceptedVersion);
+            CheckSuccess(err, Failure);
+
+            err = termsAndConditionsManager.GetTCMinRequiredVersion(tcMinRequiredVersion);
+            CheckSuccess(err, Failure);
+
+            err = termsAndConditionsManager.GetTCAcknowledgements(tcAcknowledgements);
+            CheckSuccess(err, Failure);
+
+            err = termsAndConditionsManager.GetTCAcknowledgementsRequired(tcAcknowledgementsRequired);
+            CheckSuccess(err, Failure);
+
+            if (tcAcknowledgementsRequired != (tcAcknowledgementsRequired & tcAcknowledgements))
             {
-                CHIP_ERROR err = fabricTable.CommitPendingFabricData();
-                if (err != CHIP_NO_ERROR)
-                {
-                    // No need to revert on error: CommitPendingFabricData always reverts if not fully successful.
-                    ChipLogError(FailSafe, "GeneralCommissioning: Failed to commit pending fabric data: %" CHIP_ERROR_FORMAT,
-                                 err.Format());
-                }
-                else
+                ChipLogError(AppServer, "Required terms and conditions have not been accepted");
+                Breadcrumb::Set(commandPath.mEndpointId, 0);
+                response.errorCode = CommissioningErrorEnum::kRequiredTCNotAccepted;
+            }
+
+            else if (tcAcceptedVersion < tcMinRequiredVersion)
+            {
+                ChipLogError(AppServer, "Minimium terms and conditions version has not been accepted");
+                Breadcrumb::Set(commandPath.mEndpointId, 0);
+                response.errorCode = CommissioningErrorEnum::kTCMinVersionNotMet;
+            }
+
+            else
+            {
+                if (failSafe.NocCommandHasBeenInvoked())
                 {
+                    err = fabricTable.CommitPendingFabricData();
+                    CheckSuccess(err, Failure);
                     ChipLogProgress(FailSafe, "GeneralCommissioning: Successfully commited pending fabric data");
                 }
-                CheckSuccess(err, Failure);
-            }
 
-            /*
-             * Pass fabric of commissioner to DeviceControlSvr.
-             * This allows device to send messages back to commissioner.
-             * Once bindings are implemented, this may no longer be needed.
-             */
-            failSafe.DisarmFailSafe();
-            CheckSuccess(
-                devCtrl->PostCommissioningCompleteEvent(handle->AsSecureSession()->GetPeerNodeId(), handle->GetFabricIndex()),
-                Failure);
+                /*
+                 * Pass fabric of commissioner to DeviceControlSvr.
+                 * This allows device to send messages back to commissioner.
+                 * Once bindings are implemented, this may no longer be needed.
+                 */
+                failSafe.DisarmFailSafe();
+                err = devCtrl->PostCommissioningCompleteEvent(handle->AsSecureSession()->GetPeerNodeId(), handle->GetFabricIndex());
+                CheckSuccess(err, Failure);
 
-            Breadcrumb::Set(commandPath.mEndpointId, 0);
-            response.errorCode = CommissioningErrorEnum::kOk;
+                Breadcrumb::Set(commandPath.mEndpointId, 0);
+                response.errorCode = CommissioningErrorEnum::kOk;
+            }
         }
     }
 
@@ -328,6 +366,22 @@ bool emberAfGeneralCommissioningClusterSetRegulatoryConfigCallback(app::CommandH
     return true;
 }
 
+bool emberAfGeneralCommissioningClusterSetTCAcknowledgementsCallback(
+    chip::app::CommandHandler * commandObj, const chip::app::ConcreteCommandPath & commandPath,
+    const chip::app::Clusters::GeneralCommissioning::Commands::SetTCAcknowledgements::DecodableType & commandData)
+{
+    MATTER_TRACE_SCOPE("SetTCAcknowledgements", "GeneralCommissioning");
+    auto & termsAndConditionsManager = Server::GetInstance().GetTermsAndConditionsManager();
+
+    Commands::SetTCAcknowledgementsResponse::Type response;
+
+    CheckSuccess(termsAndConditionsManager.SetTCAcknowledgements(commandData.TCVersion, commandData.TCUserResponse), Failure);
+    response.errorCode = CommissioningErrorEnum::kOk;
+
+    commandObj->AddResponse(commandPath, response);
+    return true;
+}
+
 namespace {
 void OnPlatformEventHandler(const DeviceLayer::ChipDeviceEvent * event, intptr_t arg)
 {

src/app/server/BUILD.gn

@@ -1,4 +1,4 @@
-# Copyright (c) 2020 Project CHIP Authors
+# Copyright (c) 2020-2024 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.
@@ -44,6 +44,8 @@ static_library("server") {
     "OnboardingCodesUtil.h",
     "Server.cpp",
     "Server.h",
+    "TermsAndConditionsManager.cpp",
+    "TermsAndConditionsManager.h",
   ]
 
   public_configs = [ ":server_config" ]

src/app/server/Server.h

@@ -1,6 +1,6 @@
 /*
  *
- *    Copyright (c) 2020 Project CHIP Authors
+ *    Copyright (c) 2020-2024 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.
@@ -33,6 +33,7 @@
 #include <app/server/AppDelegate.h>
 #include <app/server/CommissioningWindowManager.h>
 #include <app/server/DefaultAclStorage.h>
+#include <app/server/TermsAndConditionsManager.h>
 #include <credentials/CertificateValidityPolicy.h>
 #include <credentials/FabricTable.h>
 #include <credentials/GroupDataProvider.h>
@@ -357,6 +358,8 @@ class Server
 
     app::FailSafeContext & GetFailSafeContext() { return mFailSafeContext; }
 
+    app::TermsAndConditionsManager & GetTermsAndConditionsManager() { return mTermsAndConditionsManager; }
+
     TestEventTriggerDelegate * GetTestEventTriggerDelegate() { return mTestEventTriggerDelegate; }
 
     Crypto::OperationalKeystore * GetOperationalKeystore() { return mOperationalKeystore; }
@@ -636,6 +639,7 @@ class Server
     Crypto::OperationalKeystore * mOperationalKeystore;
     Credentials::OperationalCertificateStore * mOpCertStore;
     app::FailSafeContext mFailSafeContext;
+    app::TermsAndConditionsManager mTermsAndConditionsManager;
 
     bool mIsDnssdReady = false;
     uint16_t mOperationalServicePort;