Line data    Source code

       1              : /*
       2              :  *
       3              :  *    Copyright (c) 2025 Project CHIP Authors
       4              :  *    All rights reserved.
       5              :  *
       6              :  *    Licensed under the Apache License, Version 2.0 (the "License");
       7              :  *    you may not use this file except in compliance with the License.
       8              :  *    You may obtain a copy of the License at
       9              :  *
      10              :  *        http://www.apache.org/licenses/LICENSE-2.0
      11              :  *
      12              :  *    Unless required by applicable law or agreed to in writing, software
      13              :  *    distributed under the License is distributed on an "AS IS" BASIS,
      14              :  *    WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
      15              :  *    See the License for the specific language governing permissions and
      16              :  *    limitations under the License.
      17              :  */
      18              : 
      19              : #pragma once
      20              : 
      21              : #include <credentials/jcm/TrustVerification.h>
      22              : #include <credentials/jcm/VendorIdVerificationClient.h>
      23              : 
      24              : #include <app-common/zap-generated/ids/Attributes.h>
      25              : #include <app-common/zap-generated/ids/Clusters.h>
      26              : #include <app/DeviceProxy.h>
      27              : #include <app/ReadClient.h>
      28              : #include <controller/AutoCommissioner.h>
      29              : #include <controller/CHIPDeviceController.h>
      30              : #include <lib/core/CHIPCallback.h>
      31              : #include <lib/core/CHIPCore.h>
      32              : #include <lib/core/CHIPError.h>
      33              : #if CONFIG_DEVICE_LAYER
      34              : #include <platform/CHIPDeviceLayer.h>
      35              : #endif
      36              : 
      37              : namespace chip {
      38              : 
      39              : namespace Controller {
      40              : 
      41              : namespace JCM {
      42              : 
      43              : /*
      44              :  * DeviceCommissioner is a class that handles the Joint Commissioning Management (JCM) process
      45              :  * for commissioning Joint Fabric Administrator devices in a CHIP network. It extends the DeviceCommissioner class and
      46              :  * implements the JCM trust verification process.
      47              :  */
      48              : class DeviceCommissioner : public chip::Controller::DeviceCommissioner,
      49              :                            public Credentials::JCM::VendorIdVerificationClient,
      50              :                            public Credentials::JCM::TrustVerificationStateMachine
      51              : {
      52              : public:
      53              :     // The constructor initializes the DeviceCommissioner with a reference to this device commissioner
      54            7 :     DeviceCommissioner() {}
      55            7 :     ~DeviceCommissioner() {}
      56              : 
      57              :     /*
      58              :      * StartJCMTrustVerification is a method that initiates the JCM trust verification process for the device.
      59              :      * It is called by the commissioning client to start the trust verification process.
      60              :      * The method will return an error if the device proxy is null or if the trust verification process fails.
      61              :      *
      62              :      * @return CHIP_ERROR indicating success or failure of the operation.
      63              :      */
      64              :     CHIP_ERROR StartJCMTrustVerification(DeviceProxy * proxy) override;
      65              : 
      66              :     /*
      67              :      * ContinueAfterUserConsent is a method that continues the JCM trust verification process after the user has
      68              :      * provided consent or denied it. If the user grants consent, the trust verification process will continue;
      69              :      * otherwise, it will terminate with an error.
      70              :      *
      71              :      * @param consent A boolean indicating whether the user granted consent (true) or denied it (false).
      72              :      */
      73              :     void ContinueAfterUserConsent(const bool & consent) override;
      74              : 
      75              :     /**
      76              :      * ContinueAfterLookupOperationalTrustAnchor is a method that continues the JCM trust verification process after the
      77              :      * lookup of the operational trust anchor. It will call the trust verification delegate to continue the process.
      78              :      *
      79              :      * @param globallyTrustedRootSpan A ByteSpan representing the globally trusted root public key.
      80              :      */
      81              :     void ContinueAfterLookupOperationalTrustAnchor(const CHIP_ERROR err, const ByteSpan globallyTrustedRootSpan);
      82              : 
      83              :     /*
      84              :      * GetTrustVerificationInfo is a method that returns the JCM trust verification information.
      85              :      */
      86              :     Credentials::JCM::TrustVerificationInfo & GetTrustVerificationInfo() { return mInfo; }
      87              : 
      88              :     bool HasValidCommissioningMode(const Dnssd::CommissionNodeData & nodeData) override;
      89              : 
      90              : protected:
      91              :     // Override ParseExtraCommissioningInfo to parse JCM administrator info
      92              :     CHIP_ERROR ParseExtraCommissioningInfo(ReadCommissioningInfo & info, const CommissioningParameters & params) override;
      93              :     // Override CleanupCommissioning to clean up JCM trust verification state
      94              :     void CleanupCommissioning(DeviceProxy * proxy, NodeId nodeId, const CompletionStatus & completionStatus) override;
      95              :     CHIP_ERROR OnLookupOperationalTrustAnchor(VendorId vendorID, Credentials::CertificateKeyId & subjectKeyId,
      96              :                                               ByteSpan & globallyTrustedRootSpan) override;
      97              :     void OnVendorIdVerificationComplete(const CHIP_ERROR & err) override;
      98              : 
      99              : private:
     100              :     // Parses the JCM extra commissioning information from the device
     101              :     CHIP_ERROR ParseAdminFabricIndexAndEndpointId(const ReadCommissioningInfo & info);
     102              :     CHIP_ERROR ParseOperationalCredentials(const ReadCommissioningInfo & info);
     103              :     CHIP_ERROR ParseTrustedRoot(const ReadCommissioningInfo & info);
     104              : 
     105              :     // JCM commissioning trust verification steps
     106              :     Credentials::JCM::TrustVerificationError VerifyAdministratorInformation();
     107              :     CHIP_ERROR OnSignVIDVerificationSuccessCb(const ByteSpan & signatureSpan, const ByteSpan & clientChallengeSpan);
     108              :     Credentials::JCM::TrustVerificationError PerformVendorIDVerificationProcedure();
     109              :     Credentials::JCM::TrustVerificationError AskUserForConsent();
     110              : 
     111              :     /*
     112              :      * ContinueAfterVendorIDVerification is a method that continues the JCM trust verification process after the
     113              :      * vendor ID verification step.
     114              :      *
     115              :      * @param err The error code indicating the result of the vendor ID verification. CHIP_NO_ERROR if successful.
     116              :      */
     117              :     void ContinueAfterVendorIDVerification(const CHIP_ERROR & err);
     118              : 
     119              :     Credentials::JCM::TrustVerificationStage
     120              :     GetNextTrustVerificationStage(const Credentials::JCM::TrustVerificationStage & currentStage) override;
     121              :     void PerformTrustVerificationStage(const Credentials::JCM::TrustVerificationStage & nextStage) override;
     122              : 
     123              :     /*
     124              :      * OnTrustVerificationComplete is a callback method that is called when the JCM trust verification process is complete.
     125              :      * It will handle the result of the trust verification and report it to the commissioning delegate.
     126              :      *
     127              :      * @param result The result of the JCM trust verification process.
     128              :      */
     129              :     void OnTrustVerificationComplete(Credentials::JCM::TrustVerificationError error) override;
     130              : 
     131              :     // Device proxy for the device being commissioned
     132              :     DeviceProxy * mDeviceProxy;
     133              : 
     134              :     friend class TestCommissioner;
     135              : };
     136              : 
     137              : } // namespace JCM
     138              : } // namespace Controller
     139              : } // namespace chip