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. These data do not change during the device lifetime. ST provides a tool with X-CUBE-MATTER to store data in the flash memory and manages them. ST also has partners that provides infrastructure for Device Attestation Certificate (DAC) and Product Attestation Intermediate (PAI) certificate provisioning.
Enable factory data provisioning by defining and setting the CONFIG_STM32_FACTORY_DATA_ENABLE flag to 1 in the app_conf.h header file for STM32WBA65I-DK1 and STM32WB5MM-DK and in the app_config.h header file for NUCLEO-U575ZI-Q. If the CONFIG_STM32_FACTORY_DATA_ENABLE flag is not set, Matter test VID/PID and certificates are used at commissioning. Development DAC/PAI certificates are available in the X-CUBE-MATTER\Middlewares\Third_Party\connectedhomeip\src\credentials\examples\ExampleDACs.cpp and ExamplePAI.cpp files. The user can select the VID and PID using the CHIP_DEVICE_CONFIG_DEVICE_VENDOR_ID and CHIP_DEVICE_CONFIG_DEVICE_PRODUCT_ID compilation flags, defined in the CHIPProjectConfig.h file for STM32WBA65I-DK1 and STM32WB5MM-DK, and in the STM32CHIPConfig.h file for NUCLEO-U575ZI-Q.

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 the DAC private key.
The answer to the CSR request is also signed using the 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. The 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 and runs on the STM32 device to perform secure provisioning of sensitive data such as the device attestation certificate (DAC) private key.

- The firmware uses a customizable interface to interact with the programming PC. This interface allows the device to receive DAC and product attestation intermediate (PAI) certificates from the programming PC.

- The firmware stores the DAC private key, DAC certificate, and PAI certificate in the target storage area. The DAC private key is stored in flash memory by default (Test mode). The DAC private key can also be stored in secure storage (available on STM32WB55 with production mode & STM32WBA6 with OEMiRoT and TFM).

The secure storage is Internal Trusted Storage (ITS) for STM32WBA6 with OEMiRoT and trusted firmware-m (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 flash memory.
X-CUBE-MATTER\Projects\STM32WBA65I-DK1\Applications\ROT_STM_Prov_OEMiRoT\OEMiROT_Appli_TrustZone\Binary 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\Binary 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 STM32WB55-based platform. It is used to store the DAC private key securely in CKS using the OpenThread CKS API in production mode, or directly in flash memory in test mode.
X-CUBE-MATTER\Projects\NUCLEO-U575ZI-Q\Applications\ROT_STM_Prov_OEMiRoT\SBSFU_Appli\Binary folder for STM32U75ZI-based platform

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

X-CUBE-MATTER\Projects\<STM32-Platform>\<ROT_Provisioning-Application>\OEMiROT. where:
<STM32-Platform> is either STM32WBA6 or STM32U5
<ROT_Provisioning-Application> belongs to:
- ROT_Provisioning_STM_Prov_OEMiRoT
- ROT_Provisioning_Lighting_OEMiRoT
- ROT_Provisioning_STM_Prov_TFM
- ROT_Provisioning_Lighting_TFM

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: 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 dataThis argument is 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 X-CUBE-MATTER\Utilities\DataFactory folder.
--binary: Indicates the path to a binary file containing device configuration data. This argument is 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. This argument is required if --provisioning is set to 1).
--flashAddr or -fa: Indicates the address where the DataFactory binary output file is programmed. This argument is mandatory.
-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's 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 --CoFwAddr option.
--flashProvisioningFW: Indicates the path to the provisioning application firmware file. This argument is required if --provisioning is set to 1. The file is programmed at the address indicated by the --AppFwAddroption . The user can obtain the provisioning file binary by compiling the provisioning firmware project STM_Provisioning provided in X-CUBE-MATTER within the X-CUBE-MATTER\Projects\STM32WB5MM-DK\Applications\Matter folder.
--flashAppFW: Indicates the path to the operational application firmware file. This argument is required if --provisioning is set to 1). The file is programmed at the address indicated by the --AppFwAddr option.
--CoFwAddr or -cofwa: Indicates the address where the coprocessor firmware is programmed. This argument is required if --provisioning is set to 1).
--AppFwAddr or -afwa: Indicates the address where the application provisioning or operational firmware is programmed. This argument is 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. 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, indicates the security level. This argument is mandatory if --provisioning is set 1. Set to 0 for no security, 1 for security with OEMiRoT only, 2 for security with OEMiRoT and TFM. For STM32WBA6 with security level 1 and 2, the regression.bat/.sh and provisioning.bat/.sh scripts are used to initialize and program the firmware on the device. For STM32U5 with security level 1, the regression.sh and SBSFU_UPDATE.sh scripts are used to initialize and program the firmware on the device.
--platform: Indicates the STM32 platform (STM32WBA6 or STM32U575). This argument is mandatory only when the value of the security argument is higher than or equal to 1
--flashMagicTrailer: Indicates the path to the magic trailer binary. This argument is required if --security is set 1) or 2).
--flashMagicTrailerAddr: Indicates the flash address for the magic trailer specified by --flashMagicTrailer. This argument is required if --security is set 1) or 2).
--verbose or -v: Enables 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 (nonsecure) 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 --platform wba --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 nonsecure 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 --platform wba --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 nonsecure area.
Program the magic trailer (MagicTrailerValue.bin) at the specified address (0x701BFFF0) to trigger the OTA after provisioning.

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

python genFactoryData.py --provisioning 1 --security 1 --platform u5 --json Provisioning_FactoryData.json --flashAddr 0x81EC000 --flashAppFW sbsfu_app_enc_sign.bin --AppFwAddr 0x08100000 --provisioning_script STM32_provisioning.py --flashMagicTrailer MagicTrailerValue.bin --flashMagicTrailerAddr 0x081E5FF0 -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.sh script.
Program the provisioning firmware without TFM using the SBSFU_UPDATE.sh script.
Program the application firmware (sbsfu_app_enc_sign.bin) in the nonsecure area.
Program the magic trailer (MagicTrailerValue.bin) at the specified address (0x081E5FF0) 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.2.

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 & STM32U5 with OEMiRoT

Typical provisioning sequence with OEMiRoT is as follow:

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.

- Programs the device with the provisioning firmware using the provisioning.bat/sh script.

- 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 nonsecure 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 key to the device flash memory.

- Writes the DAC private key into the device flash memory if TFM is not enabled (default). Alternatively, writes the DAC private key into the ITS area of the TFM if TFM is enabled.

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

Notes:

regression.bat/sh & provisioning.bat/sh can be found under ...\<ROT_Provisioning_STM_Prov_xxx>\OEMiRoT.
<ROT_Provisioning_STM_Prov_xxx> is either ROT_Provisioning_STM_Prov_OEMiRoT or ROT_Provisioning_STM_Prov_TFM depending on whether or not you are using TFM.
TFM is currently only available on STM32WBA6.
If TFM is used on STM32WBA6, DAC private key is stored in the ITS area of the TFM.

3.2. 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 nonsecure 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