Matter Provisioning#

Tools in the Silicon Labs Matter GitHub provision folder are used to load mandatory authentication information into Matter devices. For more information on accessing the provision tools and cloning the Silicon Labs Matter GitHub repository, see the documentation located here: Silicon Labs Matter GitHub repo.

Most of the required parameters are stored once during the manufacturing process, and shall not change during the lifetime of the device. During runtime, two interfaces are used to pull the authentication data from permanent storage:

The provisioning script in this folder now supersedes the following tool:

Provisioned Data#

The Commissionable Data includes Serial Number, Vendor Id, Product Id, and the Setup Payload (typically displayed in the QR), while the Attestation Credentials includes the Certificate Declaration (CD), the Product Attestation Intermediate (PAI) certificate, and the DAC (Device Attestation Certificate).

During commissioning, Matter devices perform a Password Authenticated Key Exchange using the SPAKE2+ protocol. The SPAKE2+ verifier is pre-calculated using an external tool.

The passcode is used to derive a QR code, typically printed on the label, or displayed by the device itself. The QR code contains the pre-computed setup payload, which allows the commissioner to establish a session with the device. The parameters required to generate and validate the session keys are static and stored in NVM3.

To protect the attestation private-key (used to generate the DAC), the asymmetric key-pair should be generated on-device, using PSA, and the most secure storage location available to the specific part. However, the private-key may be generated externally, and imported using the --dac_key parameter.

The DAC is generated and signed by a Certification Authority (CA), which may reside on a separate host. The modules/signing_server.py script simulates the role of the CA, and uses OpenSSL to to generate and sign the DAC. In a real factory environment, this script is replaced by an actual CA.

Generator Firmware#

The Generator Firmware (GFW) is a baremetal application that runs on the targeted device, and assists with the initial setup of the device. The GFW performs the following tasks:

  • Generates the device key-pair on the most secure location available

  • Returns a CSR (Certificate Signing Request) to the provisioning script. The CSR contains the device public-key, Vendor Id, Product Id, and Serial Number.

  • Calculates the Setup Payload

  • Stores the Commissionable Data into NVM3 (including the Setup Payload)

  • Stores the Attestation Data on the main flash (CD, PAI, DAC)

  • Stores the size and offsets used to store the Attestation Data, along with the KeyId used to generate the private-key

The main source code of the GFW is located under provision/generator, while the board support is located under provision/support. Pre-compiled images for the supported chips can be found in provision/images.

The directory structure is as follows:

  • provision

    • generator

    • images

    • modules

    • support

      • efr32mg12

      • efr32mg24

Provisioner Script#

The provision.py file is the main script used to load all the required data on the Matter device. This script requires:

sudo pip3 install ecdsa

The Provisioner script executes the following steps:

  1. Parses and validates the command-line arguments.

  2. Obtains the Part Number from the connected device (using Simplicity Commander).

  3. If no SPAKE2+ verifier is provided:

    • Generates SPAKE2+ verifier (using the external spake2p tool).

  4. Loads the Generator Firmware into the device (if no GFW path is provided, the Part Number is used to choose the corresponding file from the provision/images).

  5. Configures the NVM3 based on the flash size of the connected device.

  6. If CSR mode is used (--csr):

    • Requests a CSR from the device. The GFW generates the key-pair and CSR, then returns the the CSR to the host script.

    • Sends the CSR to the Signing Server (provision/modules/signing_server.py), and retrieves the DAC.

  7. Sends CD, PAI, and DAC to the GFW.

    • The GFW stores CD, PAI, and DAC on the last page of main flash, and updates the offsets and sizes in NVM3

  8. Sends the Commissionable Data to the GFW.

    • The GFW initializes the flash, generates the Setup Payload, and stores the data into NVM3

  9. If a PFW is provided, writes the PFW into flash using Simplicity Commander.

The provisioning script and the GFW communicates through J-Link RTT using the PyLink module.

Arguments#

Arguments

Conformance

Type

Description

-c, --config

optional

string

Path to a JSON configuration file.

-j, --jlink

optional ^1

dec/hex

JLink connection string.

-l, --pylink_lib

optional

string

Path to the PyLink library.

-g, --generate

optional

flag

Auto-generate test certificates.

-m, --stop

optional

flag

Stop mode: When true, only generate the JSON configuration, and exit.

-r, --csr

optional

flag

CSR mode: When true, instructs the GFW to generate the private key, and issue a CSR.

-gf, --gen_fw

optional

dec/hex

Path to the Generator Firmware image.

-pf, --prod_fw

optional

dec/hex

Path to the Production Firmware image.

-v, --vendor_id

optional

dec/hex

Vendor ID. e.g: 65521 or 0xFFF1 (Max 2 bytes).

-V, --vendor_name

optional

string

Vendor name (Max 32 char).

-p, --product_id

optional

dec/hex

Product ID. e.g: 32773 or 0x8005 (Max 2 bytes).

-P, --product_name

optional

string

Product name (Max 32 char).

-pl, --product_label

optional

string

Product label.

-pu, --product_url

optional

string

Product URL.

-pn, --part_number

optional

dec/hex

Device Part Number (Max 32 char).

-hv, --hw_version

optional

dec/hex

The hardware version value (Max 2 bytes).

-hs, --hw_version_str

optional

string

The hardware version string (Max 64 char).

-cf, --commissioning_flow

optional

dec/hex

Commissioning Flow 0=Standard, 1=User Action, 2=Custom.

-rf, --rendezvous_flags

optional

dec/hex

Rendez-vous flag: 1=SoftAP, 2=BLE 4=OnNetwork (Can be combined).

-md, --manufacturing_date

optional

string

Manufacturing date.

-d, --discriminator

optional ^2

dec/hex

BLE pairing discriminator. e.g: 3840 or 0xF00. (12-bit).

-ct, --cert_tool

optional

string

Path to the chip-cert tool. Defaults to ../out/tools/chip-cert.

-ki, --key_id

required

dec/hex

Attestation Key ID.

-kp, --key_pass

optional ^3

string

Password for the key file.

-xc, --att_certs

optional ^3

string

Path to the PKCS#12 attestation certificates file.

-ic, --pai_cert

required

string

Path to the PAI certificate.

-dc, --dac_cert

optional ^3

string

Path to the PAI certificate.

-dk, --dac_key

optional ^3

dec/hex

Path to the PAI private-key.

-cd, --certification

required

string

Path to the Certification Declaration (CD) file.

-cn, --common_name

optional ^4

string

Common Name to use in the Device Certificate (DAC).

-u, --unique_id

optional ^5

hex string

A 128 bits hex string unique id (without 0x).

-sv, --spake2p_verifier

optional

string ^6

Pre-generated SPAKE2+ verifier.

-sp, --spake2p_passcode

required

dec/hex

Session passcode used to generate the SPAKE2+ verifier.

-ss, --spake2p_salt

required

string ^6

Salt used to generate the SPAKE2+ verifier.

-si, --spake2p_iterations

required

dec/hex

Iteration count used to generate the SPAKE2+ verifier.