Matter device factory data provisioning

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 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 certificate. 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 (STM_Provisioning project), delivered in source code, runs on the device (STM32) 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 writes/stores the DAC private key, DAC certificate and PAI certificate to the target storage area. DAC private key is stored in flash memory for test mode and in secure storage (for example Customer Key Storage (CKS) in WB55 platform) for production mode.

- It is provided in X-CUBE-MATTER within the Project\<STM32 platform>\Applications\Matter folder.

2.3.1. genFactoryData python script description

• Features

- Read JSON files containing device configuration data, compute a binary DataFactory output file and flash it to a specified address.

- Program firmware to a specified address (or specified addresses for dual-core STM32 such as STM32WB55 with M0 and M4 cores).

- Use a script (STM32_provisioning.py) that monitors the provisioning process, to be replaced by third-party script in provisioning mode.

- List and check the availability of serial ports.

- Handle multiple devices concurrently using threading (instances of STM32_provisioning.py in reconfigure mode, or third-party script in provisioning mode).

• Requirements

Installation of:

- Python 3.x

- STM32CubeProgrammer (default path: `c:\Program Files\STMicroelectronics\STM32Cube\STM32CubeProgrammer\bin`)

- Required python packages: serial, concurrent.futures, argparse, json, struct, subprocess, tempfile, os, re, ssl, enum, threading and datetime.

• 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 development phase to a device already configured with application firmware and on which the ST tool is used to reconfigure the factory data.
• --json: to indicate the path to an input JSON file containing device configuration data. The json file includes or does not include DAC/PAI certificate and DAC public/private key if provisioning is set to 0 or 1 respectively. The 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.
• --provisioning_script: to indicate the path to the provisioning script STM32_provisioning.py in reconfigure mode or third-party script in provisioning mode (required if --provisioning is set to 1).
• --flashAddr or -fa: to indicate the address where the DataFactory binary output file is programmed (mandatory argument).
• -programmerPath or -pp: to indicate the path to STM32CubeProgrammer and the executable file name (if not set, the default path defined in programmer is used).
• --externalLoader or -el: to indicate 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: to indicate the path to the coprocessor firmware file for a dual-core STM32 (required if `--provisioning` is 1). The file is programmed at the address indicated by option --CoFwAddr.
• --flashProvisioningFW: to indicate the path to the provisioning application firmware file (required if '--provisioning' is set to 1). The file is programmed at the address indicated by 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: to indicate the path to the operational application firmware file (required if `--provisioning` is 1). The file is programmed at the address indicated by option --AppFwAddr.
• --CoFwAddr or -cofwa: to indicate the address where the coprocessor firmware is programmed (required if `--provisioning` is 1).
• --AppFwAddr or -afwa: to indicate the address where the application provisioning or operational firmware is programmed (required if `--provisioning` is 1).
• --mode: to indicate the provisioning mode which either is test mode or production mode indicating respectively that the DAC private key must be stored in flash memory or secure storage (required if `--provisioning` is 1). The value of mode is passed as argument to the provisioning script which then passes it to the provisioning application firmware in the STM32.
  

• Usage examples

- STM32WBA6 based device - provisioning production mode (provisioning = 1, mode = production)

python genFactoryData.py --provisioning 1 --json config.json --flashAddr data_factory_address --flashProvisioningFW <provisioning_fw_file>.bin --flashAppFW <app_fw_file>.bin --AppFwAddr application_fw_address --provisioning_script provisioning_script.py --mode production

For STM32WBA6, the data_factory_address value is configured (#define FACTORY_DATA_START_ADDR <address value>, "#define FACTORY_DATA_START_ADDR 0x81EC000U" in X-CUBE-MATTER V1.4.0 meaning that the data_factory_address in the command line is replaced by 0x81EC000) in the file stm32_factorydata.c within the folder X-CUBE-MATTER\Projects\STM32WBA65I-DK1\Applications\Matter\<XXX-App>\Core\Src.

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

python genFactoryData.py --provisioning 1 --json config.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.

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

python genFactoryData.py --provisioning 1 --json config.json --flashAddr data_factory_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.

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

2.3.2. Embedded firmware for device provisioning demonstration

For testing and demonstration purposes, ST includes a device provisioning firmware within X-CUBE-MATTER, which can be flashed by the programming PC using the provided python script. This programming firmware programs predefined certificates (DAC, PAI) and DAC keys (public, private), then sends the result of this operation to the programming PC over the UART interface.

The STM_provisioning embedded firmware allows to choose the provisioning mode, which is either test mode, where the DAC private key is written in flash memory, or product mode, where the DAC private key is written in secure storage (for example, CKS for STM32WB55 based platform).

An instance of the provisioning process manager application is used to manage a device connected to the UART port. The STM32_provisioning.py simply monitors the provisioning process: it displays a start message, reads the UART port to obtain the results, and displays the end status.

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

Note: The current versions of X-CUBE-MATTER does not include third-party software. For more information, contact ST partners referenced in section ST provisioning services integration with ST partners secure provisioning frameworks

3. Provisioning procedure

A typical provisioning sequence in provisioning mode would be the following:

• The ST python script genFactoryData :

- Enumerates/selects STLINK and COM ports.

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

- Programs the device with the provisioning software through the JTAG interface. Upon 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.

- Gets 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 to the script.

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

4. Factory data implementation

4.1. STM32WB55 factory data implementation

Note: provisional and operational software in the above figure are not present at the same time. The provisional 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 partners to securely provision the device with CSA Matter DAC and PAI certificates.

For STM32WB55 based Matter device provisioning, ST partners provide available pre-integrated frameworks for STM32WB55-based Matter device provisioning, along with related details that 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
PAI	Product attestation intermediate