[ESP32] Added an API to set the CD in DAC providers and some document…

…ation changes (#31104)

* [ESP32] Added an API to set the CD in DAC providers

* Usage of SetCertificationDeclaration() API in lighting-app/esp32

* [docs] Added some references for production workflows

* fix the readme files

* Add some docs for the lifetime of data

* adjustment to the API documentation

config/esp32/components/chip/Kconfig

@@ -867,6 +867,15 @@ menu "CHIP Device Layer"
                 then this option gets enabled.
                 Also, please disable ESP_SECURE_CERT_DS_PERIPHERAL from the menuconfig when this option is disabled
 
+        config ENABLE_SET_CERT_DECLARATION_API
+            depends on ENABLE_ESP32_FACTORY_DATA_PROVIDER || SEC_CERT_DAC_PROVIDER
+            bool "Enable Set CD API"
+            default n
+            help
+                By default, the implementation reads the Certification Declaration (CD) from the 'chip-factory'
+                NVS namespace. If this option is enabled, the application can use an API to set a CD,
+                the configured CD will be used for subsequent CD reads.
+
        config ENABLE_ESP_INSIGHTS_TRACE
            bool "Enable Matter ESP Insights"
            depends on ESP_INSIGHTS_ENABLED

docs/guides/esp32/factory_data.md

@@ -1,5 +1,19 @@
 ## Using ESP32 Factory Data Provider
 
+**WARNING:** The following steps outline the development workflow for building a
+matter device.
+
+Please take a look at
+[security considerations](https://docs.espressif.com/projects/esp-matter/en/latest/esp32/security.html)
+and review the security guidelines outlined in
+[security workflow](https://docs.espressif.com/projects/esp-idf/en/latest/esp32/security/host-based-security-workflows.html)
+for production workflows.
+
+Ensure to select the appropriate SoC from the menu on the left-hand side, as the
+provided references are specific to ESP32.
+
+---
+
 By default applications uses test-mode or default commissionable data provider,
 device attestation credentials provider, device instance info provider, and
 device info provider.
@@ -47,6 +61,15 @@ specific implementation of `CommissionableDataProvider` and
 [Component config → CHIP Device Layer → Commissioning options → Use ESP32
 Factory Data Provider]
 
+By default, the factory data provider implementation reads the Certification
+Declaration (CD) from the 'chip-factory' NVS namespace. Enable
+`CONFIG_ENABLE_SET_CERT_DECLARATION_API` option to enable an API which lets you
+set the CD from the application and the configured CD will be used for
+subsequent CD reads.
+
+[Component config -> CHIP Device Layer -> Commissioning options -> Enable Set CD
+API]
+
 Enable config option `CONFIG_ENABLE_ESP32_DEVICE_INSTANCE_INFO_PROVIDER` to use
 ESP32 specific implementation of `DeviceInstanceInfoProvider`.
 
@@ -107,4 +130,6 @@ appropriate address.
 
 ### Securing NVS binary image with NVS Encryption
 
-Please check [Flash and NVS encryption guide](flash_nvs_encryption.md)
+WARNING: NVS binary image may contain the sensitive information and it must be
+secured using NVS encryption. For more details please check
+[Flash and NVS encryption guide](flash_nvs_encryption.md)

docs/guides/esp32/secure_cert_partition.md

@@ -1,5 +1,19 @@
 # Using esp_secure_cert partition
 
+**WARNING:** The following steps outline the development workflow for building a
+matter device.
+
+Please take a look at
+[security considerations](https://docs.espressif.com/projects/esp-matter/en/latest/esp32/security.html)
+and review the security guidelines outlined in
+[security workflow](https://docs.espressif.com/projects/esp-idf/en/latest/esp32/security/host-based-security-workflows.html)
+for production workflows.
+
+Ensure to select the appropriate SoC from the menu on the left-hand side, as the
+provided references are specific to ESP32.
+
+---
+
 ## 1.1 ESP Secure Cert Partition
 
 -   When a device is pre-provisioned, PKI credentials are generated for the
@@ -177,6 +191,15 @@ CONFIG_ENABLE_ESP32_DEVICE_INSTANCE_INFO_PROVIDER=y
 CONFIG_CHIP_FACTORY_NAMESPACE_PARTITION_LABEL="fctry"
 ```
 
+By default, the secure cert DAC provider implementation reads the Certification
+Declaration (CD) from the 'chip-factory' NVS namespace. Enable
+`CONFIG_ENABLE_SET_CERT_DECLARATION_API` option to enable an API which lets you
+set the CD from the application and the configured CD will be used for
+subsequent CD reads.
+
+[Component config -> CHIP Device Layer -> Commissioning options -> Enable Set CD
+API]
+
 In order to use the esp_secure_cert_partition, in addition to enabling the above
 config options, you should also have the esp_secure_cert_partition and factory
 partition in your app. For reference, refer to partitions.csv file of

examples/lighting-app/esp32/README.md

@@ -16,8 +16,8 @@ guides to get started.
 -   Create a file named insights_auth_key.txt in the main directory of the
     example.
 
--   Follow the steps
-    present[here](https://github.com/espressif/esp-insights/blob/main/examples/README.md#set-up-esp-insights-account)
+-   Follow the steps present
+    [here](https://github.com/espressif/esp-insights/blob/main/examples/README.md#set-up-esp-insights-account)
     to set up an insights_account and the auth key created while setting it up
     will be used in the example.
 
@@ -27,13 +27,6 @@ guides to get started.
 cp /path/to/auth/key.txt path/to/connectedhomeip/examples/lighting-app/esp32/main/insights_auth_key.txt
 ```
 
----
-
--   [Cluster Control](#cluster-control)
--   [Matter OTA guide](../../../docs/guides/esp32/ota.md)
-
----
-
 ### Cluster Control
 
 -   After successful commissioning, use the OnOff cluster command to control the
@@ -50,3 +43,8 @@ cp /path/to/auth/key.txt path/to/connectedhomeip/examples/lighting-app/esp32/mai
     control the color attributes:
 
         $ ./out/debug/chip-tool colorcontrol move-to-hue-and-saturation 240 100 0 0 0 <NODE ID> 1
+
+### Matter OTA
+
+For Matter OTA please take a look at
+[Matter OTA guide](../../../docs/guides/esp32/ota.md).

examples/lighting-app/esp32/main/CMakeLists.txt

@@ -111,6 +111,10 @@ if (CONFIG_ENABLE_ESP_INSIGHTS_TRACE)
     target_add_binary_data(${COMPONENT_TARGET} "insights_auth_key.txt" TEXT)
 endif()
 
+if (CONFIG_ENABLE_SET_CERT_DECLARATION_API)
+    target_add_binary_data(${COMPONENT_TARGET} "certification_declaration.der" BINARY)
+endif()
+
 set_property(TARGET ${COMPONENT_LIB} PROPERTY CXX_STANDARD 17)
 target_compile_options(${COMPONENT_LIB} PRIVATE "-DCHIP_HAVE_CONFIG_H")
 target_compile_options(${COMPONENT_LIB} PUBLIC

examples/lighting-app/esp32/main/main.cpp

@@ -100,13 +100,25 @@ DeviceLayer::DeviceInfoProviderImpl gExampleDeviceInfoProvider;
 DeviceLayer::ESP32SecureCertDACProvider gSecureCertDACProvider;
 #endif // CONFIG_SEC_CERT_DAC_PROVIDER
 
+#ifdef CONFIG_ENABLE_SET_CERT_DECLARATION_API
+extern const uint8_t cd_start[] asm("_binary_certification_declaration_der_start");
+extern const uint8_t cd_end[] asm("_binary_certification_declaration_der_end");
+ByteSpan cdSpan(cd_start, static_cast<size_t>(cd_end - cd_start));
+#endif // CONFIG_ENABLE_SET_CERT_DECLARATION_API
+
 chip::Credentials::DeviceAttestationCredentialsProvider * get_dac_provider(void)
 {
 #if CONFIG_SEC_CERT_DAC_PROVIDER
+#ifdef CONFIG_ENABLE_SET_CERT_DECLARATION_API
+    gSecureCertDACProvider.SetCertificationDeclaration(cdSpan);
+#endif // CONFIG_ENABLE_SET_CERT_DECLARATION_API
     return &gSecureCertDACProvider;
 #elif CONFIG_ENABLE_ESP32_FACTORY_DATA_PROVIDER
+#ifdef CONFIG_ENABLE_SET_CERT_DECLARATION_API
+    sFactoryDataProvider.SetCertificationDeclaration(cdSpan);
+#endif // CONFIG_ENABLE_SET_CERT_DECLARATION_API
     return &sFactoryDataProvider;
-#else // EXAMPLE_DAC_PROVIDER
+#else  // EXAMPLE_DAC_PROVIDER
     return chip::Credentials::Examples::GetExampleDACProvider();
 #endif
 }

src/platform/ESP32/ESP32FactoryDataProvider.cpp

@@ -123,11 +123,15 @@ CHIP_ERROR ESP32FactoryDataProvider::GetDeviceAttestationCert(MutableByteSpan &
 
 CHIP_ERROR ESP32FactoryDataProvider::GetProductAttestationIntermediateCert(MutableByteSpan & outBuffer)
 {
+#ifdef CONFIG_ENABLE_SET_CERT_DECLARATION_API
+    return CopySpanToMutableSpan(mCD, outBuffer);
+#else
     size_t certSize;
     ReturnErrorOnFailure(
         ESP32Config::ReadConfigValueBin(ESP32Config::kConfigKey_PAICert, outBuffer.data(), outBuffer.size(), certSize));
     outBuffer.reduce_size(certSize);
     return CHIP_NO_ERROR;
+#endif // CONFIG_ENABLE_SET_CERT_DECLARATION_API
 }
 
 CHIP_ERROR ESP32FactoryDataProvider::SignWithDeviceAttestationKey(const ByteSpan & messageToSign, MutableByteSpan & outSignBuffer)

src/platform/ESP32/ESP32FactoryDataProvider.h

@@ -60,6 +60,28 @@ class ESP32FactoryDataProvider : public CommissionableDataProvider,
     CHIP_ERROR GetProductAttestationIntermediateCert(MutableByteSpan & outBuffer) override;
     CHIP_ERROR SignWithDeviceAttestationKey(const ByteSpan & messageToSign, MutableByteSpan & outSignBuffer) override;
 
+#ifdef CONFIG_ENABLE_SET_CERT_DECLARATION_API
+    /**
+     * @brief API to set the Certification Declaration (CD).
+     *
+     * The GetCertificationDeclaration() API implementation reads the CD from the NVS namespace `chip-factory`.
+     * Use this API to set the CD if it is stored at a different location, e.g., embedded in the firmware.
+     * Subsequent reads after calling this API will return the set CD.
+     *
+     * @param[in] cd ByteSpan containing the Certification Declaration.
+     *               The underlying data must remain allocated throughout the lifetime of the device,
+     *               as the API does not make a copy.
+     *
+     * @return CHIP_ERROR indicating the success or failure of the operation.
+     */
+    CHIP_ERROR SetCertificationDeclaration(const ByteSpan & cd)
+    {
+        VerifyOrReturnError(!cd.empty(), CHIP_ERROR_INVALID_ARGUMENT);
+        mCD = cd;
+        return CHIP_NO_ERROR;
+    }
+#endif // CONFIG_ENABLE_SET_CERT_DECLARATION_API
+
 #if CHIP_DEVICE_CONFIG_ENABLE_DEVICE_INSTANCE_INFO_PROVIDER
     // ===== Members functions that implement the GenericDeviceInstanceInfoProvider
     CHIP_ERROR GetVendorName(char * buf, size_t bufSize) override;
@@ -75,6 +97,11 @@ class ESP32FactoryDataProvider : public CommissionableDataProvider,
     CHIP_ERROR GetPartNumber(char * buf, size_t bufSize) override;
     CHIP_ERROR GetHardwareVersion(uint16_t & hardwareVersion) override;
 #endif // CHIP_DEVICE_CONFIG_ENABLE_DEVICE_INSTANCE_INFO_PROVIDER
+
+private:
+#ifdef CONFIG_ENABLE_SET_CERT_DECLARATION_API
+    ByteSpan mCD;
+#endif // CONFIG_ENABLE_SET_CERT_DECLARATION_API
 };
 
 } // namespace DeviceLayer

src/platform/ESP32/ESP32SecureCertDACProvider.cpp

@@ -55,11 +55,15 @@ CHIP_ERROR LoadKeypairFromRaw(ByteSpan privateKey, ByteSpan publicKey, Crypto::P
 
 CHIP_ERROR ESP32SecureCertDACProvider ::GetCertificationDeclaration(MutableByteSpan & outBuffer)
 {
+#ifdef CONFIG_ENABLE_SET_CERT_DECLARATION_API
+    return CopySpanToMutableSpan(mCD, outBuffer);
+#else
     size_t certSize;
     ReturnErrorOnFailure(
         ESP32Config::ReadConfigValueBin(ESP32Config::kConfigKey_CertDeclaration, outBuffer.data(), outBuffer.size(), certSize));
     outBuffer.reduce_size(certSize);
     return CHIP_NO_ERROR;
+#endif // CONFIG_ENABLE_SET_CERT_DECLARATION_API
 }
 
 CHIP_ERROR ESP32SecureCertDACProvider ::GetFirmwareInformation(MutableByteSpan & out_firmware_info_buffer)

src/platform/ESP32/ESP32SecureCertDACProvider.h

@@ -31,6 +31,33 @@ class ESP32SecureCertDACProvider : public Credentials::DeviceAttestationCredenti
     CHIP_ERROR GetDeviceAttestationCert(MutableByteSpan & outBuffer) override;
     CHIP_ERROR GetProductAttestationIntermediateCert(MutableByteSpan & outBuffer) override;
     CHIP_ERROR SignWithDeviceAttestationKey(const ByteSpan & messageToSign, MutableByteSpan & outSignBuffer) override;
+
+#ifdef CONFIG_ENABLE_SET_CERT_DECLARATION_API
+    /**
+     * @brief API to set the Certification Declaration (CD).
+     *
+     * The GetCertificationDeclaration() API implementation reads the CD from the NVS namespace `chip-factory`.
+     * Use this API to set the CD if it is stored at a different location, e.g., embedded in the firmware.
+     * Subsequent reads after calling this API will return the set CD.
+     *
+     * @param[in] cd ByteSpan containing the Certification Declaration.
+     *               The underlying data must remain allocated throughout the lifetime of the device,
+     *               as the API does not make a copy.
+     *
+     * @return CHIP_ERROR indicating the success or failure of the operation.
+     */
+    CHIP_ERROR SetCertificationDeclaration(const ByteSpan & cd)
+    {
+        VerifyOrReturnError(!cd.empty(), CHIP_ERROR_INVALID_ARGUMENT);
+        mCD = cd;
+        return CHIP_NO_ERROR;
+    }
+#endif // CONFIG_ENABLE_SET_CERT_DECLARATION_API
+
+private:
+#ifdef CONFIG_ENABLE_SET_CERT_DECLARATION_API
+    ByteSpan mCD;
+#endif // CONFIG_ENABLE_SET_CERT_DECLARATION_API
 };
 } // namespace DeviceLayer
 } // namespace chip