Provision ACK-based Matter Prototype Devices

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.

Follow these steps to 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. For details about how to generate credentials for production devices, see Provision Matter-Enabled ACK Modules for Production.

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 testing certificates used to join a Matter network.

  1. Generate a PAI certificate.
  2. Generate a certification declaration.
  3. Create the provisioning file.
  4. Provision the device with Matter credentials.

Step 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 device attestation certificate (DAC) used in commissioning. For prototype devices, you store the PAI in the Amazon Web Services (AWS) IoT cloud. For production devices, you use a hardware security module (HSM) to generate a PAI from the Amazon PAA root certificate.

To generate a PAI certificate and private key

  1. In an Ubuntu VM terminal window, navigate to the Cyprus-SDK/tools directory.
  2. 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.

Copied to clipboard.

    python3 Cyprus-SDK/tools/generate_certs.py \
    -device-type-id 0x010C \
    -dsn ABC123EFG456HI \
    -pid 007B \
    -vid FFF1 \
    -paa Cyprus-SDK/ace/sdk/external/matter/repo/credentials/test/attestation/Chip-Test-PAAFFF1-Cert.pem \
    -paa-pk Cyprus-SDK/ace/sdk/external/matter/repo/credentials/test/attestation/Chip-TestPAA-FFF1-Key.pem \
    -out-pai pai.pem \
    -out-pai-pk pai-pk.pem
  1. 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
  2. For prototype products, you register the PAI certificate with AWS IoT. Please contact your ACK support team and provide the device type and pai.pem file. This step is required for prototype products.

Step 2: Generate a certification declaration

In this step, you generate a Matter certification declaration (CD) for testing purposes. A CD is a digital document issued by the Connectivity Standards Alliance (CSA) that confirms a smart home device complies with Matter protocol standards. After your product receives CSA certification, the CSA generates a CD for your production product. You embed this document in the device firmware to verify device authenticity.

For more examples, see gen-test-cds on GitHub.

To generate a CD for testing

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

Copied to clipboard.

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

Step 3: Create the provisioning file

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

To create the provisioning file

  1. Create a file called ProvisioningInfo_<device_type>.conf.
  2. 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 VID and PID.

Copied to clipboard.

amazon_device_type_id  ABCD1234
matter_vendor_id FFF1
matter_product_id 007B
apid abcd
auth_material_public_key MFkw...ZA
  1. 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
  2. Navigate to Frustration-Free Setup > Products, and then, under Your FFS Products, choose your product.
  3. Under FFS Product Details, copy and paste the following values to the ProvisioningInfo_<device_type>.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 follows:
    auth_material_public_key MABCDEF...XYZ

  4. To provision production devices, update the file with your CSA-issued Matter VID and PID.
  5. Save and close the file.

Step 4: Provision the device with Matter credentials

In this step, you provision the device into a Matter commission-ready state by using ACK SDK for Matter tools. You can provision the device using one of the following methods:

  • Local file-based provisioning – A provisioning method used to test prototype products. This method requires the Matter PAI certificate and key files generated in Step 1.
  • Client-server provisioning – A provisioning method used for production products. This method requires a YubiHSM from Amazon.

Local provisioning for prototype products

Provisioning generates a new DSN and then writes the certificates and DSN to the development kit. This step uses local provisioning, appropriate to 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

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

Copied to clipboard.

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

Client-server provisioning for production devices

To set up client-server provisioning for production devices, contact your ACK support engineer. For more details about provisioning production devices, see Provision Matter-Enabled ACK Modules for Production.

Was this page helpful?

Last updated: frontmatter-missing