Factory Data

Factory data is a set of default parameters during the manufacturing process. It includes sorts of certification, firmware information, cryptographic keys, product id, etc.

Overview

Content of Factory data

The detailed component with its size of factory data is as below.

Content of Factory Data

Name	Size(Bytes)	Description
CertificationDeclaration	600	A cryptographic document from CSA.
PAI Certificate	600	A certificate signed by PAA.
DAC Certificate	600	A certificate signed by PAI.
DAC key	32(or 256)	private key to DAC(or encrypted in case of data breach in production line).
Discriminator	2	A 12-bit unsigned integer, used to distinguish between advertising devices.
Spake2pIterationCount	4	Actually a PBKDF parameter in SPAKE2+. A fixed value that determines how many times the PRF iterates to generate one block of the MK.
Spake2pSalt	32	A PBKDF parameter in SPAKE2+. It is a random number used against dictionary attack.
Spake2pVerifier	97	A verification value in SPAKE2+ for the verifier, which is derived from passcode, spake2psalt.
Passcode	4	The setup passcode for pairing, range: 0x01-0x5F5E0FE.
VendorName	32	A human-readable ASCII name for the vendor.
VendorId	2	A 16-bit number that uniquely identifies a particular product manufacturer, vendor, or group thereof.
ProductName	32	A human-readable ASCII name for the product.
ProductId	2	A 16-bit number that uniquely identifies a product of a vendor.
ManufacturingDate	4	A human-readable ASCII string for the manufacturing date in the format 'YYYY-MM-DD'.
HardwareVersion	4	A version number of the hardware of the device.
HardwareVersionString	64	A human-readable ASCII string for HardwareVersion.
RotatingDeviceIdUniqueId	16	It provides a non-trackable identifier for the device.
SerialNum	Up to 32	Defined a unique identifier for manufacturing equipment.

Format of Factory Data

The factory data is saved as a bin file(factory_data.bin) that can be downloaded into the region starting at 0x4000000. It is encoded by Protocol Buffers which are language-neutral, platform-neutral extensible mechanisms for serializing structured data. Protocol Buffers uses .proto file to define the format of the data structure. Reference https://protobuf.dev/overview/ for more details.

Enable Factory Data Support

The default configuration of the Matter platform code does not enable the customer Factory Data.

Users can enable it by setting ENABLE_FACTORY_DATA to ON in the preset chosen in ./subsys/openthread/CMakePresets.json.

Factory Data Generation

This section introduces the use of scripts to generate factory data.

1. Script Location:subsys/matter/vendor/factory_data/tool.

   • factory_data.proto: Define the message format of factory data as described above.

   • factory_data_pb2.py: It is auto-generated by protocol buffer tools with factory_data.proto. It facilitates factory data to generate factory_data.bin.

   • factory_data.py: It is the main script to generate factory_data.bin, manual_pairing_code.txt, qrcode.txt, qrcode.png.

   • factory_data_invoke.py: It batch generates factory data bin files with a large number of DAC of RTK PKI. Actually, it invokes factory_data.py indirectly.

   • requirements.txt: It is a text file used to define and manage the dependencies of python scripts. To download python dependency, please run pip install -r requirements.txt.

   • spake2p: It is used for generating spake parameters. It is the best practice to build it on user's own PC.

2. Script Usage: Run factory_data.py to generate a single factory_data.bin and three related files.

   • manual_pairing_code.txt: It is output of factory_data.py. It contains the manual pairing code for commissioning process.

   • qrcode.txt: It is an output of factory_data.py. It contains the QR code for commissioning process.

   • qrcode.png: It is an output of factory_data.py and an image of QR code.

Mandatory Arguments

1. --spake2p_path: The path of spake2p. Building for spake2p is as follows:

cd connectedhomeip
source scripts/activate.sh
cd src/tools/spake2p
gn gen out
ninja -C out

2. --passcode or -p: The setup passcode for pairing, range: 0x01-0x5F5E0FE.

3. --discriminator or -d: The discriminator for pairing, range: 0x00-0x0FFF.

Optional Arguments

1. --vendor-id

2. --vendor-name

3. --product-id

4. --product-name

5. --hw-ver: Hardware version.

6. --hw-ver-str: Hardware version string.

7. --mfg-date: Manufacturing date in format 'YYYY-MM-DD'.

8. --serial-num: Serial number.

9. --dac_cert: The path to the DAC certificate in der format.

10. --dac_key: The path to the DAC private key in der format.

11. --pai_cert: The path to the PAI certificate in der format.

12. --cd: The path to the certificate declaration der format.

13. --rd-id-uid: 128-bit unique identifier for generating rotating device identifier, provide 32-byte hex string, e.g. 1234567890abcdef1234567890abcdef.

14. --factorydata-key: 32-byte key to encrypt factorydata.

15. --factorydata-iv: 16-byte iv to encrypt factorydata.

16. --gen_qrcode: Generate QR code for onboarding payload.

17. --gen_manual_pairing_code: Generate manual pairing code for onboarding payload.

18. --chip_cert: if exists, it will check DAC certificate chain.

19. --paa_cert: It is used in combination with --chip_cert to check DAC certificate chain.

Example:

python3 factory_data.py -p 20202021 -d 3840 --spake2p_path ./spake2p --vendor-id 0x1316 --vendor-name "TEST_VENDOR" --product-id 0x8702 --product-name "TEST_PRODUCT" --serial-num "TEST_sn" --hw-ver 1 --hw-ver-str "1.0" --rd-id-uid 00112233445566778899aabbccddeeff --dac_cert ../test/certs/Matter-Test-DAC-Cert.der --dac_key ../test/certs/Matter-Test-DAC-Key.der --pai_cert ../test/certs/Matter-Test-PAI-Cert.der --cd ../test/certs/cd.der --chip_cert ../../../connectedhomeip/out/host/chip-cert --paa_cert ../test/certs/Matter-Test-PAA-Cert.der

Batch generation will be mentioned in Batch Generation of Factory Data with RealTek Certificates.

Program Factory Data

Factory_data.bin should be downloaded into MCU by MP Tool (tools/BeeMPTool).

1. Press the User Data beneath the Load Layout input box.

2. There is a dialog displaying all extra bin files.

   Press the Browse to choose the Factory_data.bin generated by factory_data.py. It turns out to give an address of 0x04000000 for downloading.

   Note

   Bin file in User Data should be downloaded with a normal bin file.

3. Enable the User Data checkbox to make the MP Tool download bin files in User Data.

4. Please press the Download button to download the bin file as normal.

Enable User Data Downloading

Security of Factory Data

For security concerns, especially DAC key, factory_data.bin should be encrypted into flash by MPPG Tool.

Enable Secure Factory Data Support

The default configuration of the Matter platform code does not enable security for factory data.

Users can enable it by setting ENABLE_FACTORY_DATA_ENCRYPTION to ON in the preset chosen in ./subsys/openthread/CMakePresets.json.

It is already implemented in the current SDK and needs to be used in conjunction with Program Secure Factory Data.

In addition, users can protect the DAC private key from production line disclosure by setting ENABLE_DAC_KEY_ENCRYPTION to ON.

It is implemented in the current SDK and needs to be used in conjunction with Factory Data with RealTek's PKIs.

Program Secure Factory Data

Encryption Configuration (DEK Configuration)

MPPGTool should download an Efuse bin file to configure encryption including encryption mode, key length, encryption algorithm. This configuration is called 'DEK Configuration'.

1. Preload factory_data.bin:

   1. Click User Data.

   2. Choose the factory_data.bin by Browse Button.

   3. Click Confirm.

Preload a Factory Data Bin

2. Set DEK configuration: DEK is encryption key set for bin files.

   1. Click RD_Setting to configure DEK.

   2. Set DEK0 with the encryption type expected.

   3. Set factory data bin's key to DEK0.

   4. Click the confirm button. Then MPPGTool will generate EfuseWriteFile_xxx file which is mentioned efuse file above.

DEK Configuration

Pack Factory Data Bin into Pack Bin File

Factory data must be packed into pack bin using MP Pack Tool when encryption is needed.

1. Add all images by using the browse button.

2. Choose user data and factory data bin.

3. Click the confirm button.

4. Ignore the warning dialog, then generate the ImgPacketFile_WithUserData_xxx file.

Pack Bin

Download Pack Bin and DEK Configuration

1. Download Configuration.

   1. Get into MP_Setting page by MP_Setting.

   2. UNLOCK this page by putting the password as 1. After configuration, then LOCK it.

   3. Choose Efuse file. Don’t enable Only Write Efuse.

   4. Choose pack bin image.

Downloading Pack Bin and Dek Configuration

1. Downloading: Click the Download button to download.

Downloading

Factory Data with RealTek's PKIs

For convenience, RealTek provides a set of PKI to distribute certificates for customers.

Get RealTek's DAC & PAI

Several steps to get RealTek's DAC & PAI:

1. Install openssl

   sudo apt update
   sudo apt-get install openssl
   

2. Generate a 2048-bit RSA key pair. The private key will be created as private.pem. In order to reduce the risk of disclosure about DAC's private key, this key pair is used to encrypt DAC's private key.

   openssl genrsa -out private.pem 2048
   

3. Extract the public key. The public key will be created as public.pem.

   openssl rsa -in private.pem -pubout -out public.pem
   

4. If DAC application is accepted by CA administrator, customer will receive zip file from Anchor Account.

Please contact Realtek PM or AE via Anchor Account for more detailed documents.

Output Naming and Layout of The Zip File

1. If DAC application is accepted by CA administrator, customer will receive zip file named as CUST_NAME-Cert.

   1. Each zip file corresponds to a single batch, containing a tarball file and a sha1 file for hash checking to ensure the integrity of the data after unzipping.

      └── CUST_NAME-Cert
         ├── CUST_NAME-Cert.sha1
         └── CUST_NAME-Cert.tar
      

   2. The tarball file includes DAC Key (encrypted with public key), DAC Cert, and PAI Cert.

2. The extracted tar file will consist of 1 set of PanKore Matter PAI certificate (.der & .pem) and a DAC-VID-PID-Batch ID folder.

3. Sub-folder named according to DAC-VID-PID-Batch ID-Unit No, which consists of Certificate and Key, will be named according to its Batch ID followed by Unit ID.

4. Once the tarball file is unzipped, then the full sample of layout will be as:

   └── CUST_NAME-Cert
      ├── DAC-1316-1A25-A0001
         ├── DAC-1316-1A21-A0001-00000001
            ├── DAC-1316-1A21-cert-A0001-00000001.der
            ├── DAC-1316-1A21-cert-A0001-00000001.pem
            ├── DAC-1316-1A21-Key-A0001-00000001.pem.enc
            └── DAC-1316-1A21-PrivateKey-A0001-00000001.der.enc
         ├── DAC-1316-1A21-A0001-00000002
            ├── DAC-1316-1A21-cert-A0001-00000002.der
            ├── DAC-1316-1A21-cert-A0001-00000002.pem
            ├── DAC-1316-1A21-Key-A0001-00000002.pem.enc
            └── DAC-1316-1A21-PrivateKey-A0001-00000002.der.enc
         └── DAC-1316-1A21-A0001-00000003
            ├── DAC-1316-1A21-cert-A0001-00000003.der
            ├── DAC-1316-1A21-cert-A0001-00000003.pem
            ├── DAC-1316-1A21-Key-A0001-00000003.pem.enc
            └── DAC-1316-1A21-PrivateKey-A0001-00000003.der.enc
      ├── Pankore-Test-PAA-novid-Cert.der
      ├── Pankore-Test-PAA-novid-Cert.pem
      ├── Chip-Test-CD-1316-1A25.der
      ├── Test-PAI-1316-1A25-Cert.der
      └── Test-PAI-1316-1A25-Cert.pem
   

Batch Generation of Factory Data with RealTek Certificates

Factory_data_invoke.py is a sample code for batch generation of factory data which indirectly invokes factory_data.py. It is located in subsys/matter/vendor/factory_data/tool. Run this script with parameters below:

1. --sn: The start sequence number for this batch.

2. --rtk_dir: The RealTek Certificates directory CUST_NAME-Cert.

3. --chip_cert: The file path of CHIP Certificate Tool. Please reference CHIP Certificate Tool. It is an optional argument. If exists, DAC certificate chain will be validated when generating factory data bin file.

An example:

python3 factory_data_invoke.py --rtk_dir subsys/matter/vendor/factory_data/test/cn4-Cert --sn 0x0011223344556677 --chip_cert subsys/matter/connectedhomeip/out/host/chip-cert

Factory_data_invoke.py will generate files as follows

└── CUST_NAME-Cert
   ├── DAC-1316-1A25-A0001                            The "DAC-VID-PID-Batch ID" folder.
   └── device_1316_1A25                               Generated top folder for factory data bin files and related files.
      ├── 001122334455667A                            Generated folder for a single DAC/device, named by sequence number.
         ├── factory_data_001122334455667A.bin        Generated factory_data bin file.
         ├── pairing_code.txt                         Generated pairing code file.
         └── qrcode.png                               Generated QR code image file.
      ├── 001122334455667B                            Generated top folder for factory data bin files and related files.
         ├── factory_data_001122334455667B.bin        Generated factory_data bin file.
         ├── pairing_code.txt                         Generated pairing code file.
         └── qrcode.png                               Generated QR code image file.
      └── 001122334455667C                            Generated top folder for factory data bin files and related files.
         ├── factory_data_001122334455667C.bin        Generated factory_data bin file.
         ├── pairing_code.txt                         Generated pairing code file.
         └── qrcode.png                               Generated QR code image file.
   └── sn_device_map.csv                              Generated statistic file for all DAC/device.

Mass Production Download with MPCli

Using MPCli to download factory_data bin files is more convenient compared to MP Tool, because MP Tool can only batch-download with identical image for all devices.

Mandatory arguments:

1. -c: Com port

2. -u: Program eFuse json file (for file encryption)

3. -F: File path for downloading. There is the factory data bin file.

4. -A: Address in Hex, e.g. -A 0x801000

5. -S: Size

6. -e: Erase sector, used with -A and -S together

7. -p: Download the file specified by -F and used with -A and -S together

8. -v: Verify download image, used with -A and -S together

An example:

mpcli.exe -c COM3 -u EfuseWriteFile.json -F factory_bin -A 0x4000000 -S 1803 -e -p -v

MPCli will encrypt image file according to eFuse json file which gives the specification for encryption. There is a template eFuse json file:

{
   "data_protection":        {
         "key":      [{
               "id": 0,
               "type":       "AES128_CTR",
               "key_gen":    "TRNG"
            }],
         "data":     [{
               "key_id":     0,
               "address":    "0x04000000",
               "size":       "1708"
            }]
   }
}

Usually, users should only change the value of the size field with the size of the generated factory data bin file.

For more information, please reference the document in doc/ of the MPCli folder.

Different DAC/FactoryData Configuration and Build Methods

This section introduces several common ways to configure and build combinations of FactoryData and DAC, which are suitable for different product R&D, testing, and mass production scenarios.

1. Custom DAC, generate FactoryData containing the DAC, TrustZone disabled

• Configuration:

  "ENABLE_FACTORY_DATA": "ON",
  "ENABLE_FACTORY_DATA_ENCRYPTION": "OFF",  // Optional
  "ENABLE_DAC_KEY_ENCRYPTION": "OFF",
  

• Build example:

  ./build.py rtl8777g lighting
  

2. Custom DAC, generate FactoryData containing the DAC, TrustZone enabled

• Configuration:

  "ENABLE_FACTORY_DATA": "ON",
  "ENABLE_FACTORY_DATA_ENCRYPTION": "OFF",  // Optional
  "ENABLE_DAC_KEY_ENCRYPTION": "OFF",
  

• Build example:

  ./build.py rtl8777g lighting --preset secure
  

• Output sample path:

  subsys\openthread\vendor\rtl87x2g\rtl8777g\firmware\trustzone_enable
  

3. RTK DAC, generate FactoryData containing the RTK DAC, TrustZone disabled

• Configuration:

  "ENABLE_FACTORY_DATA": "ON",
  "ENABLE_FACTORY_DATA_ENCRYPTION": "OFF",  // Optional
  "ENABLE_DAC_KEY_ENCRYPTION": "ON",
  

• Build example:

  ./build.py rtl8777g lighting
  

4. Mass production mode, RTK DAC, generate FactoryData containing the RTK DAC, TrustZone enabled

• Configuration:

  "ENABLE_FACTORY_DATA": "ON",
  "ENABLE_FACTORY_DATA_ENCRYPTION": "OFF",  // Optional
  "ENABLE_DAC_KEY_ENCRYPTION": "ON",
  

• Build example:

  ./build.py rtl8777g lighting --preset secure
  

5. Changingtec mass production mode, FactoryData does not contain DAC, Changingtec custom bin contains DAC, TrustZone enabled

• Configuration:

  "ENABLE_CG_SECURE_DAC_VENDOR": "ON",
  "ENABLE_FACTORY_DATA": "ON",
  "ENABLE_FACTORY_DATA_ENCRYPTION": "OFF",
  "ENABLE_DAC_KEY_ENCRYPTION": "OFF",
  

• Build example:

  ./build.py rtl8777g lighting --preset secure
  

Note

• Please select the most suitable solution according to the actual project requirements.

• If custom FactoryData or bin files are required, please refer to the relevant toolchain or script documentation.