Step 2: Provision the Device

To join a Matter network, smart home devices must present proper credentials to prove their certification as authentic Matter products. These credentials include a device attestation certificate (DAC) and a certification declaration (CD). A DAC is an X.509 v3 certificate that chains to a trusted root certificate authority (CA) through an intermediate certificate. In the Matter CA hierarchy, the product attestation authority (PAA) sits at the top of the trust chain and the product attestation intermediate (PAI) operates at the second level. The PAI serves as the CA that issues DACs. For more details, see The Matter CA hierarchy for DACs. The CD provides proof of certification from the Connectivity Standards Alliance (CSA). The CD is a cryptographically signed statement that confirms a vendor ID (VID) and product ID (PID) pair received Matter certification. You provision these credentials to the device. During commissioning, the Matter commissioner uses the DAC and CD to establish the authenticity of the device in a process called attestation. For more details, see Matter Attestation. In this step, you generate a PAI certificate, DAC, and CD for the test VID and PID, and then copy the credentials to the development kit. The credentials generated in this step are specifically designed to test prototype devices. Don’t use these credentials to secure production devices.

Prerequisites

You installed the Matter tools in your development environment. For more details, see Build Matter tools.

Steps to generate certificates

Complete the following steps to generate and provision testing certificates used to join a Matter network.

Generate a PAI certificate.
Generate a certification declaration.
Create the provisioning configuration file.
Provision the device with Matter credentials.

Step 2.1: Generate a PAI certificate

In this step, you generate a PAI certificate and private key by using the Product Attestation Authority (PAA) root certificate that comes with the SDK. The PAI is an X.509 v3 intermediate certificate used to sign the DAC during provisioning. For prototype devices, you store the PAI in the Amazon Web Services (AWS) IoT cloud. To generate a PAI certificate and private key

In an Ubuntu VM terminal window, navigate to the Cyprus-SDK/tools directory.
To generate the certificate, at the command prompt, enter the following command.
Set Matter Device Type ID to 0x010C which represents the device type ID for a Color Temperature Light.

    python3 Cyprus-SDK/tools/generate_certs.py \
    -device-type-id 0x010C \
    -dsn ABC123EFG456HI \
    -pid 007B \
    -vid FFF1 \
    -paa smartlight-mtr-app/third_party/connectedhomeip/credentials/development/attestation/Chip-Development-PAA-Cert.pem \
    -paa-pk smartlight-mtr-app/third_party/connectedhomeip/credentials/development/attestation/Chip-Development-PAA-Key.pem \
    -out-pai pai.pem \
    -out-pai-pk pai-pk.pem

If you receive the following error, update your python cryptography module, and then repeat Step 2.

  Traceback (most recent call last):
  File "tools/generate_certs.py", line 332, in <module>
  TEST_DAC_CERT, TEST_PAI_CERT, dac_pk = generate_sample_dac_detailed()
  File "tools/generate_certs.py", line 65, in generate_sample_dac_detailed
  paa_pk = serialization.load_pem_private_key(pk, password=None)
  TypeError: load_pem_private_key() missing 1 required positional argument: backend

For prototype products, you register the PAI certificate with AWS IoT. Please contact your ACK support engineer and provide the device type and pai.pem file. This step is required for prototype products.

Step 2.2: Generate a certification declaration

In this step, you generate a test Certification Declaration (CD) for the smart light. The generation process uses a test certificate and private key from the Matter SDK to sign the CD. You embed the CD in the device firmware during provisioning. To generate a CD for testing

In a terminal window, navigate to the Matter tools directory.
You defined the directory name when you installed Matter tools.
At the command prompt, enter the following command.

./chip-cert gen-cd \
--key Cyprus-SDK/ace/sdk/external/matter/repo/credentials/test/certification-declaration/Chip-Test-CD-Signing-Key.pem \
--cert Cyprus-SDK/ace/sdk/external/matter/repo/credentials/test/certification-declaration/Chip-Test-CD-Signing-Cert.pem \
--out ./Chip-Test-CD-FFF1-007B.der \
--format-version 1 \
--vendor-id FFF1 \
--product-id 007B \
--device-type-id 0x010C \
--certificate-id "ZIG20141ZB330001-24" \
--security-level 0 \
--security-info 0 \
--version-number 9876 \
--certification-type 0

To verify that the command succeeded, you should see the following generated CD file in the current directory.
/Chip-Test-CD-FFF1-007B.der
In a convenient place, such as Notepad on Windows or TextEdit on Mac, paste the directory path and CD file name.

Step 2.3: Create the provisioning configuration file

To provision your device, create a provisioning configuration file that contains Matter and Frustration-Free Setup (FFS) data. To create the provisioning file

Navigate to the Cyprus-SDK\smartlight-mtr-app directory.
Create a file called ProvisioningInfo_color_light.conf.
Copy the following key-value pairs, and then paste them into the file. Leave a single space following the key.
The example contains the prototype values for Matter Vendor and Product IDs.

amazon_device_type_id  ABCD1234
matter_vendor_id FFF1
matter_product_id 007B
apid abcd
auth_material_public_key MFkw...ZA

To get the amazon_device_type_id, apid, and auth_material_public_key values, sign in to the Frustration-Free Setup console with your Amazon developer account.
Navigate to Frustration-Free Setup > Products, and then, under Your FFS Products, choose Matter Color Light.
Under FFS Product Details, copy and paste the following values to the ProvisioningInfo_color_light.conf file.
- Under Device Type ID, copy the ID, and then paste after amazon_device_type_id.
- Under Advertised Product Id, copy the ID, and then paste after apid.
- Under Device Cryptographic Material, to view the key, select Show.
  You might have to log in again with your Amazon developer account.
- Copy the key without the BEGIN header and END footer, and then paste after auth_material_public_key.
  For example, if you see the following key information:
  -----BEGIN PUBLIC KEY----- MABCDEF...XYZ -----END PUBLIC KEY-----
  Set the value as:
  auth_material_public_key MABCDEF...XYZ
Save and close the file.

Step 2.4: Provision the device with Matter credentials

In this step, you provision the device into a Matter commission-ready state. Provisioning generates a device attestation certificate (DAC) and a new device serial number (DSN), and then writes these, along with the CD, to the development kit. This step uses local provisioning which is appropriate for prototype products only. Before you start, make sure that you installed the ACK_SDK_Tools-matter package. For more details, see Install ACK SDK tools. To provision the device locally

Connect your host machine to the development kit.
For details, see Connect your host machine to the development kit.
In a terminal window, navigate to the Cyprus-SDK directory.
At the command prompt, enter the following command.
- Set <port> to the serial port, such as /dev/ttyUSB0 on Ubuntu, /dev/cu.usbserial-USB0 on Mac, or COM9 on Windows.

provision -p <port> -x smartlight-mtr-app/ProvisioningInfo_color_light.conf -g A1 -pc tools/pai.pem -pk tools/pai-key.pem -cd <path to Chip-Test-CD-FFF1-007B.der> -l DEBUG

To verify that the command succeeded, you should see the following response.

Logging into provision.log with logging level DEBUG
Writing certificate to the module
Provisioning successful!

Get Started

Product Development Guidelines

Tutorials

Troubleshooting

Reference

Prerequisites

Steps to generate certificates

Step 2.1: Generate a PAI certificate

Step 2.2: Generate a certification declaration

Step 2.3: Create the provisioning configuration file

Step 2.4: Provision the device with Matter credentials

​Prerequisites

​Steps to generate certificates

​Step 2.1: Generate a PAI certificate

​Step 2.2: Generate a certification declaration

​Step 2.3: Create the provisioning configuration file

​Step 2.4: Provision the device with Matter credentials

Prerequisites

Steps to generate certificates

Step 2.1: Generate a PAI certificate

Step 2.2: Generate a certification declaration

Step 2.3: Create the provisioning configuration file

Step 2.4: Provision the device with Matter credentials