Matter device factory data provisioning

This message will disappear after all relevant tasks have been resolved.

Semantic MediaWiki

There are 1 incomplete or pending task to finish installation of Semantic MediaWiki. An administrator or user with sufficient rights can complete it. This should be done before adding new data to avoid inconsistencies.

1. Introduction

Factory data are parameters stored in the device during the manufacturing process in a factory. These data do not change during the lifetime of the device. For this purpose, ST provides a tool with X-CUBE-MATTER that can be used to store data in the flash memory and manages them in general. ST has also partners providing infrastructure for Device Attestation Certificate (DAC) and Product Attestation Intermediate (PAI) certificates provisioning.
Factory data provisioning is enabled by defining and setting to 1 CONFIG_STM32_FACTORY_DATA_ENABLE flag in the header file app_conf.h located in X-CUBE-MATTER\Projects\<STM32 platform>\Applications\Matter\<XXX-App>\Core\Inc folder. If CONFIG_STM32_FACTORY_DATA_ENABLE flag is not set, Matter test VID/PID and certificates are used at commissioning time. Development DAC/PAI certificates are available in X-CUBE-MATTER\Middlewares\Third_Party\connectedhomeip\src\credentials\examples\ExampleDACs.cpp/ExamplePAI.cpp. User can select the VID and PID in CHIPProjectConfig.h using CHIP_DEVICE_CONFIG_DEVICE_VENDOR_ID and CHIP_DEVICE_CONFIG_DEVICE_PRODUCT_ID.

1.1. Provisioning overview

In a Matter ecosystem, each device is identified through a set of credentials. This allows to securely identify each device joining a Matter fabric (illustrated by the figure below) and the software running on the device. Trusted software are referenced on CSA Distributed Compliance Ledger (DCL) server.

1.2. Matter factory data

Each device must have a consistent set of credentials to complete Matter commissioning. These credentials are stored on the Matter device during provisioning. The following information are stored in factory data:

Product information:

- VID/PID, hardware version, serial number, firmware information

Matter certificates:

- PAI, DAC, DAC public key, DAC private key, Certification Declaration (CD)

Other security credentials:

- Setup discriminator, Spake2+ parameters

1.3. Matter commissioning

During Matter commissioning:

The commissioner extracts the DAC certificate and the PAI certificate from the commissionee at validate attestation step.
The authenticity and integrity of the DAC certificate are checked by the commissioner sending a challenge request to the commissionee. The challenge request is signed by commissionee using DAC private key.
The answer to the CSR request is also signed using DAC private key.

Warning

The DAC private key is a key security element on a Matter device. It must be securely stored to prevent device cloning.

1.4. Device attestation PKI hierarchy

Each Matter device is identified by its own DAC. The DAC certificates are derived from a single root of trust involving PAA and PAI. Each DAC is provided with a public/private key pair. The DAC private key length is 256 bits.

2. ST provisioning architecture

2.1. Device provisioning overall system architecture

The Matter provisioning data model promoted by ST is open. ST end customer may contact whatever PKI provider to get PAI and DAC for his Matter end device.
Factory used by the end customer shall meet minimum security requirements to ensure that key assets cannot be stolen.

Architecture requirements:

DAC and PAI certificates are retrieved from PKI provider server using a secure connection (PKCS#10, …)

DAC private key is generated in the device and shall be securely stored to prevent device cloning. Application software should not be able to read or modify it.

Embedded software with third party middleware is used to customize the interaction with provisioning infrastructure.

Data structure and format:

Matter factory data are stored in TLV format as represented in figures below:

2.2. Device provisioning hardware environment

2.3. Secure provisioning services deliveries

ST delivers tools as part of X-CUBE-MATTER package to support device “data factory setting” during manufacturing. The tools are integrated/customized by the “PKI provider company” as required by the current customer manufacturing process. ST provides supports to integrate the tools. The tools comprise:

Python script (genFactoryData.py) running on a programming PC connected to the device to be programmed via STLINK.

- It uses STM32CubeProgrammer CLI to communicate with the STM32 devices.

- It writes firmware and data factory (non-sensitive) into the device flash memory and can also set sensitive data (DAC/PAI certificates DAC public/private keys in reconfigure mode.

- It is provided in X-CUBE-MATTER within the Utilities\DataFactory folder.

- It launches a provisioning function on the programming PC to manage the provisioning process. ST delivers a provisioning process manager script (STM32_provisioning.py) for provisioning demonstration. The third-party must provide its own application to be used in provisioning mode on the programming PC.

Embedded firmware is delivered in source code, runs on the STM32 device to perform secure provisioning of sensitive data (DAC private key).

- It uses a customizable interface to interact with the programming PC. This interface allows to receive DAC and PAI certificates from the programming PC.

- It stores the DAC private key, DAC certificate, and PAI certificate in the target storage area. The DAC private key is stored in flash memory during test mode or in secure storage during production mode for STM32WB55, and in secure storage for STM32WBA6 with OEMiRoT and TFM. The secure storage is Internal Trusted Storage (ITS) for STM32WBA6 with OEMiRoT and TFM, and Customer Key Storage (CKS) for STM32WB55.

- The provisioning embedded firmware is delivered in X-CUBE-MATTER within the following folders:

X-CUBE-MATTER\Project\<STM32WBA65I-DK1\Applications\Matter folder for Lighting-App, Window-App or Generic-Switch-App on STM32WBA6 without OEMiRoT. It is used to store the development certificates (development DAC and PAI certificates) and keys (development DAC private and public keys) in the flash memory.
X-CUBE-MATTER\Projects\STM32WBA65I-DK1\ROT_STM_Prov_OEMiRoT\OEMiROT_Appli_TrustZone\NonSecure folder for STM32WBA6 with OEMiRoT enabled and without TFM. It is used to store the development certificates (development DAC and PAI certificates) and keys (development DAC private and public keys) in the flash memory.
X-CUBE-MATTER\Projects\STM32WBA65IDK1\Applications\ROT_STM_Prov_TFM\OEMiROT_Appli_TrustZone\NonSecure folder for STM32WBA6 with OEMiRoT and TFM. It is used to securely store the Device Attestation private key using TFM PSA API in TFM ITS secure storage, and to store device certificates and the DAC public key in the flash memory.
X-CUBE-MATTER\Project\STM32WB5MM-DK\Applications\Matter folder for S STM32WB55 based platform. It is used to store the Device Attestation private key, securely in CKS using the OpenThread CKS API in production mode, or directly in the flash memory in test mode.

2.3.1. genFactoryData python script description

Features

- Multiple security levels: supports classic (no security), OEMiROT only, and OEMiROT + TFM provisioning flows.

- Flexible input data format: reads a JSON or binary input file containing device configuration data, computes a binary DataFactory output file, and flashes it to a specified address.

- Firmware programming: programs firmware to a specified address (or specified addresses for dual-core STM32, such as STM32WB55 with M0 and M4 cores).

- Scripted Provisioning: uses a script (STM32_provisioning.py) that monitors the provisioning process, and which can be replaced by a third-party script in provisioning mode.

- Serial Port Management: lists and checks the available serial ports for device communication.

- Multi-device Support: handles multiple devices concurrently using threading (instances of STM32_provisioning.py in reconfigure mode, or third-party script in provisioning mode).

Requirements

Installation of the following components is required:

Python 3.x.
STM32CubeProgrammer (default path: c:\Program Files\STMicroelectronics\STM32Cube\STM32CubeProgrammer\bin).
Required Python packages:
- pyserial
- concurrent.futures
- argparse
- json
- struct
- subprocess
- tempfile
- os
- re
- ssl
- enum
- threading
- datetime
TrustZone scripts:
- regression.bat in Windows or regression.sh in Linux: This script is used to put the board in a clean state, erase the memory, and configure the security registers.
- provisioning.bat in Windows or provisioning.sh in Linux: This script is used to flash the provisioning firmware with OEMiRoT for secure boot and secure services.

These scripts are delivered in the following directories:

For Lighting-App Matter application on STM32WBA65I-DK1 with OEMiRoT enabled and without TFM: X-CUBE-MATTER\Projects\STM32WBA65I-DK1\ROT_Provisioning_Lighting_OEMiRoT\OEMiROT.
For Lighting-App Matter application on STM32WBA65I-DK1 with OEMiRoT enabled and with TFM: X-CUBE-MATTER\Projects\STM32WBA65I-DK1\ROT_Provisioning_Lighting_TFM\OEMiROT.
For Provisioning application on STM32WBA65I-DK1 with OEMiRoT enabled and without TFM: X-CUBE-MATTER\Projects\STM32WBA65I-DK1\ROT_Provisioning_STM_Prov_OEMiRoT\OEMiROT.
For Provisioning application on STM32WBA65I-DK1 with OEMiRoT enabled and with TFM: X-CUBE-MATTER\Projects\STM32WBA65I-DK1\ROT_Provisioning_Prov_TFM\OEMiROT.

For actual factory provisioning, only scripts for the provisioning application are used. Then, Matter application is programmed using the OTA procedure.

Command line options and parameters

The script accepts the following command line arguments to control its behavior:

--provisioning: A mandatory argument set to 0 for reconfigure mode or 1 for provisioning mode. The reconfigure mode applies during the development phase to a device already configured with application firmware and on which the ST tool is used to reconfigure the factory data.
--json: Indicates the path to an input JSON file containing device configuration data (mutually exclusive with --binary). The JSON file includes or excludes DAC/PAI certificates and DAC public/private keys if --provisioning is set to 0 or 1, respectively. Two variants of input JSON files (Full_FactoryData.json and Provisioning_FactoryData.json) are provided in X-CUBE-MATTER within the folder X-CUBE-MATTER\Utilities\DataFactory.
--binary: Indicates the path to a binary file containing device configuration data (mutually exclusive with --json. The binary file includes or excludes DAC/PAI certificates and DAC public/private keys if --provisioning is set to 0 or 1, respectively.
--provisioning_script: Indicates the path to the provisioning script STM32_provisioning.py in reconfigure mode or third-party provisioning mode (required if --provisioning is set to 1).
--flashAddr or -fa: Indicates the address where the DataFactory binary output file is programmed (mandatory argument).
-programmerPath or -pp: Indicates the path to STM32CubeProgrammer and the executable file name (if not set, the default path defined in the programmer is used)).
--externalLoader or -el: Indicates the external loader driver to use for external flash and the driver name (if not set, the external loader defined in external_loader is used by default)).
--flashCoFW: Indicates the path to the coprocessor firmware file for a dual-core STM32 (required if --provisioning is set to 1). The file is programmed at the address indicated by the option --CoFwAddr.
--flashProvisioningFW: Indicates the path to the provisioning application firmware file (required if --provisioning is set to 1). The file is programmed at the address indicated by the option --AppFwAddr. The user can obtain the provisioning file binary by compiling the provisioning firmware project (STM_Provisioning) provided in X-CUBE-MATTER within the folder X-CUBE-MATTER\Projects\STM32WB5MM-DK\Applications\Matter.
--flashAppFW: Indicates the path to the operational application firmware file (required if --provisioning is set to 1). The file is programmed at the address indicated by the option --AppFwAddr.
--CoFwAddr or -cofwa: Indicates the address where the coprocessor firmware is programmed (required if --provisioning is set to 1).
--AppFwAddr or -afwa: Indicates the address where the application provisioning or operational firmware is programmed (required if --provisioning is set to 1).
--mode: Specifies the provisioning mode, which can be either test mode or production mode. In test mode, the DAC private key must be stored in flash memory, while in production mode, it must be stored in secure storage. This argument is required if --provisioning is set to 1. It is specific to the STM32WB55-based platform, and its value is passed as an argument to the provisioning script, which subsequently forwards it to the provisioning application firmware in the STM32.
security: For the STM32WBA6 platform, It indicates the security level and is mandatory present if --provisioning is set 1. It is set to 0 for no security, 1 for security with OEMiRoT only, 2 for security with OEMiRoT and TFM. For security level 1 and 2 the regression.bat/.sh and provisioning.bat/.sh scripts will be used to program the firmware on the device.
--flashMagicTrailer: Indicate the path to the magic trailer binary (required if --security is set 1) or 2).
--flashMagicTrailerAddr: Indicate the flash address for the magic trailer --flashMagicTrailer (required if --security is set 1) or 2).
--verbose or -v: Enable verbose output for detailed logs.

Usage examples

- STM32WBA6 based device without OEMiRoT - provisioning mode with security level 0 (provisioning = 1, security = 0)

python genFactoryData.py --provisioning 1 --security 0 --json Provisioning_FactoryData.json --flashAddr 0x81EC000 --flashProvisioningFW STM_Provisioning.bin --flashAppFW Lighting-App.bin --AppFwAddr 0x08000000 --provisioning_script STM32_provisioning.py <!----mode production--->

In this example, the embedded provisioning firmware (STM_Provisioning.bin) is flashed directly (no secure) at the specified address. It stores the development certificates (development DAC and PAI certificates) and keys (development DAC private and public keys) in the flash memory. This process completes the remaining factory data written by the provisioning script on the programming PC to achieve a full set of factory data.

After successfully factory data provisioning, the operational application firmware (Lighting-App.bin) is programmed at the specified address.

- STM32WBA6 based device with OEMiRoT but without TFM - provisioning production with security level 1 (provisioning = 1, security = 1)

python genFactoryData.py --provisioning 1 --security 1 --json Provisioning_FactoryData.json --flashAddr 0x81EC000 --flashAppFW oemirot_tz_ns_app_enc_sign.bin --AppFwAddr 0x700060000 --provisioning_script STM32_provisioning.py --flashMagicTrailer MagicTrailerValue.bin --flashMagicTrailerAddr 0x701CBFF0 -v

This example corresponds to secure board provisioning using TrustZone (Secure Bootloader and OTA) without TFM. The --security argument set to 1 enables the secure process, which consists of the following operations:

Erase and configure the board securely using the regression.bat script in Windows or the regression.sh script in Linux.
Program the provisioning firmware without TFM using the provisioning.bat script in Windows or the provisioning.sh script in Linux.
Program the application firmware (oemirot_tz_ns_app_enc_sign.bin) in the non-secure area.
Program the magic trailer (MagicTrailerValue.bin) at the specified address (0x701BFFF0) to trigger the OTA after provisioning.

- STM32WBA6 platform-based device with OEMiRoT and TFM - provisioning mode (provisioning = 1, security = 2)

python genFactoryData.py --provisioning 1 --security 2 --json Provisioning_FactoryData.json --flashAddr 0x81EC000 --flashAppFW oemirot_tz_ns_app_enc_sign.bin --AppFwAddr 0x70040000 --provisioning_script STM32_provisioning.py --flashMagicTrailer MagicTrailerValue.bin --flashMagicTrailerAddr 0x701BFFF0 -v

This example corresponds to secure board provisioning using TrustZone (Secure Bootloader and OTA) and TFM. The security argument set to 2 enables the secure process, which consists of the following operations:

Erase and configure the board securely using the regression.bat script in Windows or the regression.sh script in Linux.
Program the provisioning firmware and TFM using the provisioning.bat script in Windows or the provisioning.sh script in Linux.
Program the application firmware (oemirot_tz_ns_app_enc_sign.bin) in the non-secure area.
Program the magic trailer (MagicTrailerValue.bin) at the specified address (0x701BFFF0) to trigger the OTA after provisioning.

- STM32WB55 based device provisioning test mode (provisioning = 1, mode = test)

Warning

The STM32WB55 platform for Matter is no more maintained after X-CUBE-MATTER 1.4.0.

python genFactoryData.py --provisioning 1 --json Provisioning_FactoryData.json --flashAddr data_factory_address --flashCoFW <coprocessor_fw_file>.bin --CoFwAddr coprocessor_fw_address --flashProvisioningFW <provisioning_fw_file>.bin --flashAppFW <app_fw_file>.bin --AppFwAddr application_fw_address --provisioning_script provisioning_script.py --mode test

For STM32WB55, the data_factory_address value is configured (#define FACTORY_DATA_START_ADDR <address value>, #define FACTORY_DATA_START_ADDR 0x901C0000U in X-CUBE-MATTER V1.4.0 meaning that the data_factory_address in the command line is replaced by 0x901C0000) in the file stm32_factorydata.c within the folder X-CUBE-MATTER\Projects\STM32WB5MM-DK\Applications\Matter\<XXX-App>\Matter\Src.

The provisioning process manager (provisioning_script) is either the script provided by ST for demonstration (STM32_provisioning.py) or the third-party script used in provisioning mode.

- Any STM32 platform-based device reprogramming mode (provisioning = 0)

python genFactoryData.py --provisioning 0 --json Full_FactoryData.json --flashAddr data_factory_address

In this example, the full factory data is programmed at the specified address.

The data_factory_address value is configured (#define FACTORY_DATA_START_ADDR <address value>) in the file stm32_factorydata.c within a folder depending on the STM32 platform and indicated in the above corresponding bullets.

2.3.2. Provisioning script on the programming PC

The provisioning script (STM32_provisioning.py provided by ST or its customization for an end customer) manages the communication with the STM32 target over a serial (COM) port to perform the provisioning process. It synchronizes with the device, triggers provisioning, and interprets the result codes sent back by the STM32 firmware. The detailed operations performed by the script are the following:

It opens the specified COM port configured with a baud rate of 115200, 8 data bits, no parity, and 1 stop bit.
It sends an initialization command (Init\n) and waits for the STM32 to respond with the Start_provisioning keyword, indicating that synchronization is complete.
Once synchronized, it listens for a line matching the pattern finish:XYZ, where XYZ is a three-digit status code returned by the STM32.
It interprets this code and prints a corresponding message. The possible messages are as follows:

0x0000 Provisioning Done: indicates that the provisioning has been completed successfully.
0x0001 Data not found: indicates that the required data was not found on the device.
0x0002 Buffer too small: indicates that the buffer provided was too small.
0x0003 Parameter error: indicates that there was an erroneous parameter in the request.
0x0004 STM32 not init or fail in synchronization: indicates that the STM32 did not initialize or failed to synchronize.
0xFFFE Provisioning completed with unknown error: indicates that an unknown error occurred during provisioning.
0xFFFF Provisioning interrupted by user: indicates that the process was interrupted by the user.

The script uses a timeout of 30 seconds for both synchronization and result waiting and is robust to user interruption (Ctrl+C) and unexpected serial errors.

2.3.3. Embedded firmware for device provisioning demonstration

The device provisioning firmware STM_Provisioning, delivered by ST within X-CUBE-MATTER, is used for provisioning testing or demonstration purposes. It can be flashed to the device by the programming PC using the provided Python script genFactoryData.py. This provisioning firmware programs predefined certificates (DAC, PAI) and DAC keys (public and private) into the flash memory, then sends the result of this operation to the programming PC over the UART interface. After receiving the successful result, the programming PC programs the device with the operational Matter application.

2.3.4. Embedded firmware for device provisioning during manufacturing

In provisioning mode, a third-party customized STM_Provisioning embedded firmware, excluding hardcoded certificates and keys, is used. This embedded firmware relies on the third-party middleware to compute the DAC keypair, send CSR to and obtain certificates from the programming PC. Then, it writes certificates on flash memory and the private key on secure storage.

In provisioning mode, the provisioning process manager is provided by third-party and acts as proxy between the device to be programmed and the PKI server.

For more information on third-party, contact ST partners referenced in section ST provisioning services integration with ST partners secure provisioning frameworks.

3. Provisioning procedure

3.1. Provisioning procedure for STM32WBA6 with OEMiRoT without TFM

A typical STM32WBA6 with OEMiRoT and without TFM provisioning sequence in provisioning mode is as follows:

The ST Python script genFactoryData.py:

- Enumerates and selects STLINK and COM ports.

- Writes all parameters except DAC/PAI certificates and DAC public/private keys into the device flash memory using the JTAG interface.

- Puts the STM32 device in a clean and secure state (erases the memory and configures the security registers) using the regression.bat/sh script from ...\ROT_Provisioning_STM_Prov_OEMiRoT\OEMiRoT.

- Programs the device with the provisioning firmware using the provisioning.bat/sh script from ...\ROT_Provisioning_STM_Prov_OEMiRoT\OEMiRoT.

- Launches an instance of the provisioning process manager on the programming PC for each selected COM port.

- Waits for the provisioning completion and, if successful, programs the device with the operational application firmware: writes oemirot_tz_ns_app_enc_sign.bin in the non-secure area of the external flash at the specified address, then writes the magic trailer MagicTrailerValue.bin at the specified address.

- The application firmware is installed after the device reboots.

The provisioning process manager (STM32_provisioning.py customized by a third party) on the programming PC, upon being launched on a given COM port:

- Prints a start message and attempts to open the port.

- Sends an Init\n on the port repeatedly until it receives Start_provisioning from the STM32 or times out.

- Waits for and forwards the CSR request to the PKI server.

- Retrieves the DAC and PAI certificates from the PKI server and sends them to the embedded firmware on the device through the UART interface.

- Waits for the finish:XYZ message from the device, then closes the COM port and returns control to the script with the provisioning result.

The provisioning embedded firmware, upon receipt of the synchronization message Init\n:

- Sends the Start_provisioning message as a response.

- Generates the DAC key pair, prepares the CSR and sends it to the programming PC using the UART interface.

- Waits for the CSR response.

- Writes the DAC and PAI certificates and the DAC public and private keys to the device flash memory.

- Signals the successful completion of the provisioning to the provisioning process manager (third-party software on the programming PC), which then notifies the ST Python script.

3.2. Provisioning procedure for STM32WBA6 with OEMiRoT and TFM

A typical STM32WBA6 with OEMiRoT and TFM provisioning sequence in provisioning mode is as follows:

The ST Python script genFactoryData.py:

- Enumerates and selects STLINK and COM ports.

- Writes all parameters except DAC/PAI certificates and DAC public/private keys into the device flash memory using the JTAG interface.

- Puts the STM32 device in a clean and secure state (erases the memory and configures the security registers) using the regression.bat/sh script from ...\ROT_Provisioning_STM_Prov_TFM\OEMiRoT.

- Programs the device with the TFM binary and the provisioning firmware using the provisioning.bat/sh script from ...\ROT_Provisioning_STM_Prov_TFM\OEMiRoT.

- Launches an instance of the provisioning process manager on the programming PC for each selected COM port.

- Waits for the provisioning completion and, if successful, programs the device with the operational application firmware: writes oemirot_tz_ns_app_enc_sign.bin in the non-secure area of the external flash at the specified address, then writes the magic trailer MagicTrailerValue.bin at the specified address.

- The application firmware is installed after the device reboots.

The provisioning process manager (STM32_provisioning.py customized by a third party) on the programming PC, upon being launched on a given COM port:

- Prints a start message and attempts to open the port.

- Sends an Init\n on the port repeatedly until it receives Start_provisioning from the STM32 or times out.

- Waits for and forwards the CSR request to the PKI server.

- Retrieves the DAC and PAI certificates from the PKI server and sends them to the embedded firmware on the device through the UART interface.

- Waits for the finish:XYZ message from the device, then closes the COM port and returns control to the script with the provisioning result.

The provisioning embedded firmware, upon receipt of the synchronization message Init\n:

- Sends the Start_provisioning message as a response.

- Generates the DAC key pair, prepares the CSR and sends it to the programming PC using the UART interface.

- Waits for the CSR response.

- Writes the DAC/PAI certificates and the DAC public key to the device flash memory and store the DAC private key in the ITS area of the TFM.

- Signals the successful completion of the provisioning to the provisioning process manager (third-party software on the programming PC), which then notifies the ST Python script.

3.3. Provisioning procedure for STM32WB55

A typical provisioning sequence in provisioning mode is as follows:

The ST Python script genFactoryData.py:

- Enumerates and selects STLINK and COM ports.

- Writes all parameters except DAC/PAI certificates and DAC public/private keys into the device flash memory using the JTAG interface.

- Programs the device with the provisioning software through the JTAG interface. Once installed, this firmware generates the DAC keypair, prepares, and sends the CSR to the programming PC using the UART interface.

- Launches an instance of the provisioning process manager on the programming PC for each selected COM port.

- Programs the device with the operational software through the JTAG interface at the end of the provisioning.

The provisioning process manager (third-party software) on the programming PC:

- Forwards the CSR request to the PKI server.

- Retrieves the DAC and PAI certificates from the PKI server and sends them to the embedded firmware on the device through the UART interface.

- Ends and returns control to the genFactoryData.py script.

Upon receipt of the CSR response, the provisioning embedded firmware writes DAC/PAI certificates and the DAC public key to the device flash memory, and the DAC private key to flash memory in test mode or secure storage in production mode. It then signals the successful completion of the provisioning to the provisioning process manager (third-party software on the programming PC), which in turn signals the ST Python script.

4. Factory data implementation

4.1. STM32WBA6 factory data implementation

Note: provisioning and operational software in the above figure are not present at the same time. The provisioning software is loaded for provisioning and is replaced by the operational software at the end of the provisioning.

In STM32WBA6 Matter platform, the secure storage of the DAC private key is the ITS storage of the TFM. The ITS usage is enabled when TFM is used (USE_TFM_PSA compilation flag defined and set to 1 in X-CUBE-MATTER\Projects\STM32WBA65I-DK1\Applications\ROT_TFM\OEMiROT_Appli_TrustZone\NonSecure\Core\Inc\app_conf.h.

The following procedure will be used to store DAC private key in ITS:

Initialize the PSA
```
 psa_status_t psa_crypto_init(void);
```

Initialize the key attributes

 key_attributes = psa_key_attributes_init();

Reset the key attributes

 psa_reset_key_attributes(&key_attributes);

Setup the key policy for private key

psa_set_key_usage_flags(&key_attributes, PSA_KEY_USAGE_SIGN_MESSAGE);
psa_set_key_algorithm(&key_attributes, PSA_ALG_ECDSA(PSA_ALG_SHA_256));
psa_set_key_type(&key_attributes, PSA_KEY_TYPE_ECC_KEY_PAIR(PSA_ECC_FAMILY_SECP_R1));
psa_set_key_bits(&key_attributes, 8U*sizeof(Private_Key));
psa_set_key_lifetime(&key_attributes, PSA_KEY_LIFETIME_FROM_PERSISTENCE_AND_LOCATION(PSA_KEY_PERSISTENCE_DEFAULT, PSA_KEY_LOCATION_LOCAL_STORAGE));
psa_set_key_id(&key_attributes, PSA_ECDSA_KEY_ID_USER);

Finally store the key in TFM ITS area

 psa_import_key(&key_attributes, Private_Key, sizeof(Private_Key), &key_handle_private);

With:

&key_attributes: reference to the key attributes
Private_Key: the DAC private key
&key_handle_private: a handle to DAC private key that will be used by the non-secure part (the Matter application) for operations involving the key

The following procedure is used to sign a message

Get the DAC private key handle

 psa_open_key(DEVICE_ATTESTATION_PRIVATE_KEY_ID_USER, &key_handle_private);

Sign the message with DAC private key

 psa_sign_message(key_handle_private, PSA_ALG_ECDSA(PSA_ALG_SHA_256), messageToSign.data(), messageToSign.size(), signature.Bytes(), signature.Capacity(), &outputLen);

Close the DAC private key handle
```
 psa_close_key(key_handle_private);
```

Warning

Be careful while setting DAC private key, it can only be done once. Any further attempt to update DAC private key is denied. Storing a wrong DAC private key results in a broken device.

4.2. STM32WB55 factory data implementation

Note: provisioning and operational software in the above figure are not present at the same time. The provisioning software is loaded for provisioning and is replaced by the operational software at the end of the provisioning.

In STM32WB55 Matter platform, the secure storage of the DAC private key is the CKS storage. The CKS usage is enabled by USE_STM32WBXX_DAC_CRYPTO compilation flag defined and set to 1 in X-CUBE-MATTER\Projects\STM32WB5MM-DK\Applications\Matter\<App>\System\Inc\app_conf.h.

The following API can be used to store DAC private key in CKS:

otError otCksDacInitialize(const uint8_t *DAC_private_key);

With:

DAC_private_key: pointer to DAC private key in raw format.



   Warning



Be careful while setting DAC private key, it can only be done once.
Any further attempt to update DAC private key is denied.
Storing a wrong DAC private key results in a broken device.

DAC private key stored in CKS area can be used to sign Matter challenge using the following API:

otError otCksDacSignature(const uint8_t *message_to_sign, const size_t msg_length, const uint8_t *DAC_public_key, uint8_t *out_signature);

With:

message_to_sign: pointer to message to be signed.
msg_length: length of message to be signed.
DAC_public_key: pointer to DAC public_key in raw format. Shall be consistent with DAC private key stored in CKS area. DAC_public_key length is 65 bytes.
Out_signature: pointer to output signature. Signature size is 64 bytes (kP256_ECDSA_Signature_Length_Raw).

To use the DAC private key stored in CKS area for Matter challenge signing, the key is loaded from the CKS, and signature is performed on M0 side in a fully isolated environment.
ECDSA signature is computed calling MbedTLS crypto functions.

5. ST provisioning services integration with ST partners' secure provisioning frameworks

ST has established privileged partnership with Arris Technology Inc to support secure provisioning of Matter devices with CSA Matter DAC and PAI certificates. Dedicated provisioning application is included in X-CUBE-MATTER software package. 

The Arris Technology Inc provisioning application is available both for STM32WB55-based and STM32WBA6-based Matter devices. 

More details can be found in ST partner portal.

6. Acronyms and definitions




Term
Definition


CKS
Customer key storage


CSR
Certificate signing request


DAC
Device attestation certificate


ECDSA
Elliptic curve digital signature algorithm


ITS
Internal Trusted Storage


OEMiRoT
Original Equipment Manufacturer immutable (unchangeable) Root of Trust


PAI
Product attestation intermediate


PSA
Platform Security Architecture


TFM or TF-M
Trusted Firmware-M