Manufacturing a Product#

This section provides information on how to mass manufacture a Silicon Labs Sidewalk-enabled product. It is based on Amazon's documentation called Manufacturing Amazon Sidewalk devices for mass production and describes the Silicon Labs specific steps in detail as well as a short summary of the global production flow in the factory.

To enable the production of your Sidewalk-based product, it needs to be certified (see corresponding documentation on qualification). Amazon provides a set of tools to facilitate production and this section describes the specific Silicon Labs tools that integrate with them. For more information on those tools and how to obtain them, check Amazon documentation on manufacturing or contact your Amazon Sidewalk business representative.

Standard Amazon Manufacturing Flow#

Amazon documentation describes how a manufacturer can mass produce Sidewalk products. This flow is used to manufacture a large number of devices, and can be divided into 4 phases:

• Setting up the factory infrastructure

• Manufacturing at the factory

• Uploading the device records (control logs) to Amazon

• Creating the recorded devices in your AWS cloud account

The Silicon Labs added-value elements described in the following sections impact the "Manufacturing at the factory" phase. All other steps stay unchanged and follow the Amazon standard flow described in the figure below.

1. The endpoint key pair is generated directly on the device. A custom application (leveraging Amazon Provisioning Libraries) triggers the certificates generation by calling the Signing Tool provided by Amazon.

2. The HSM, provisioned by Amazon, is used to sign the Certificate Signing Request (CSR) and outputs the certificate.

3. The signing tool is used along with the HSM to create the certificate chain from the endpoint certificate to the Sidewalk Network server and Application certificates. Control logs are generated as well.

4. Once the certificate chain is generated, it can be added to the manufacturing page generated during this flow.

5. Control logs are assembled into a database and can be uploaded to the cloud to populate the devices record.

6. Once all devices are entered into the record, the devices are known to the backend and can be created using the import tasks. A list of all SMSNs of created devices can be uploaded to the cloud to create the corresponding virtual devices in IoT Core.

For added security, the step requiring AWS connection can be done periodically on another computer. This way, the production PC can be totally offline and only the control logs database is shared to the computer handling AWS and connectivity tasks.

Silicon Labs Security Added Value#

On Silicon Labs EFR32 Series 2 platforms, you can leverage Secure Vault to store sensitive data (private keys) in a secure place. A set of scripts and a device application, called Production Device Provisioner (PDP), is provided to use the Secure Element in the Amazon Sidewalk context.

The goal of the production scripts is to facilitate data provisioning by providing ready-to-use scripts and a way of communicating with the embedded device from a host computer. The production flow for development and manufacturing setups stays the same, which makes the transition from development to manufacturing transparent.

In addition to the production scripts, to communicate between the device and the production line PC, Silicon Labs provides a PDP application. It is used to exchange certificate data and to communicate with the Secure Element through APIs. The PDP application can be used for provisioning and is automatically deleted upon reboot, as it is a transient application running in RAM.

Generating the key pair directly on the device limits the exposure of the private key. Amazon security requirements are evolving to require this "on-device" generation of the private key or new products. Starting with Amazon Sidewalk SDK 1.16, all products must be produced using the on-device certification generation. YubiHSM requested after Sidewalk SDK 1.16 release must use the on-device certification generation. For products released before Sidewalk SDK 1.16, keys can be generated on the production machine following the legacy flow described in the OpenSSL Private Key Provisioning section.

Provisioning Methods#

All available methods to provision a device appear in the following table. It includes the prototyping method used during development, and the two manufacturing methods (depending on your Amazon Sidewalk SDK version). All of these methods can be used alongside the Secure Vault to store the credentials.

The prototyping flow leveraging Secure Vault is covered in the OpenSSL Private Key Provisioning section below.

On-Device Certificate Generation#

In Amazon Sidewalk SDK 1.16, Amazon introduced a new flow called On-Device Certificate Generation. The main point of this flow is to generate the private key directly on the device and only communicate the CSR and public certificate to the production PC. The private keys never leave the device. Silicon Labs provides a tool that builds on the On-Device Certificate Generation flow and leverages Secure Vault to store the keys. This enhanced flow is described in the figure below.

1. The endpoint key pair is generated directly on the device. The private keys are wrapped by the Secure Element as described in the Secure Vault documentation section 3.3.2 using the Production Device Provisioner application provided by Silicon Labs.

2. The HSM, provisioned by Amazon, is used to sign the Certificate Signing Request (CSR) and outputs the certificate.

3. The signing tool is used along with the HSM to create the certificate chain from the endpoint certificate to the Sidewalk Network server and Application certificates. Control logs are generated as well.

4. Once the certificate chain is generated, it can be added to the manufacturing page generated during this flow. The manufacturing page, containing the private keys ID from Secure Vault, is written to the device flash.

5. Control logs are assembled into a database and can be uploaded to the cloud to populate the devices record.

6. Once all devices are entered into the record, the devices are known to the backend and can be created using the import tasks. A list of all SMSNs of created devices can be uploaded to the cloud to create the corresponding virtual devices in IoT Core.

Silicon Labs Production Provisioning Walkthrough#

Both on-device and offline manufacturing certificate generation flows use the production scripts and application.

Production provisioning scripts consist of two functions: initialization and provisioning.

The initialization script generates an image with the static data of a Sidewalk device (the common part of the Amazon Sidewalk certificate) and optionally a Sidewalk application. The generated image is identical for all the devices in question. In the case of on-device certificate generation, the output of this script is just the custom application binary without any static data added.

The provisioning script, on the other hand, flashes the initialization image generated in the previous step, flashes the Production Device Provisioner RAM application, and provisions device-specific information via this application. Each device is provisioned with a unique set of security credentials (device-specific part of the Sidewalk certificate).

The scripts can be used in two certificate generation modes:

• On-device certificate generation: Device certificate is generated and private keys are wrapped by the Secure Element on the device.

• Private key provisioning: Device certificate is generated outside of the device and private keys are wrapped by the Secure Element. Deprecated since Amazon Sidewalk SDK 1.16, see the section at the end of this page.

The production scripts are located in tools/scripts/public/pdp folder of the extension.

Enabling the Secure Element#

For starters, the Secure Vault should be enabled in your Sidewalk application. To enable Secure Vault in the application, you must modify the config/sl_sidewalk_common_config.h file in your project as follows:

In file config/sl_sidewalk_common_config.h, add definition for SV_ENABLED.

#ifndef SV_ENABLE
  #define SV_ENABLE 1
#endif //SV_ENABLE

Compiling the Production Device Provisioner Application#

The production scripts communicate between the Amazon Signing Tool and with a device through the Production Device Provisioner application.

To create a Production Device Provisioner application, follow the getting started documentation and compile the Production Device Provisioner instead of the Hello Neighbor application: Create an Amazon Sidewalk Project.

To compile the application, go to your newly created Production Device Provisioner application folder in the Simplicity IDE persective. In the left explorer view, right-click the project and select Build Project. When the compilation is finished, you will find the compiled binary in your Simplicity Studio workspace under your_pdp_project_name/GNU ARM v10.3.1 - Default/your_project_name.s37. This file is needed by the production provisioning script in the next step.

On-Device Certificate Generation#

For On-Device Certificate Generation, we generate the private keys on the device; only the CSR and public certificate are communicated to the production PC. Private data never leaves the device. Only the public data needed to create the device on the cloud is communicated to the production PC.

Here is a detailed description of the steps:

1. Production Device Provisioner (PDP) script sends a command to the device that triggers Amazon on-device certificate generation module's init API, which initializes the process context.

2. PDP script sends a command to the device that triggers amazon on-device certificate generation module's generate SMSN (Sidewalk MAnuafacturing Serial Number) API. It sends the command along with the device type (provided by Amazon), device serial number (generated per device), and ApID (provided by Amazon) parameters. The device sends back generated SMSN.

3. PDP script sends a command to the device that triggers Amazon on-device certificate generation module's generate CSR API, two times in a row, one for ED25519 elliptic curve and another for P256R1 elliptic curve. It's at this stage that the device private keys (two keys, one for each curve) are generated in Secure Vault and wrapped with the device private key before being stored on the default NVM3 instance.

4. PDP script calls Sidewalk signing tool provided by Amazon. It passes production tag, HSM connection address, HSM PIN, ED25519 CSR, p256r1 CSR and ApID parameters to the signing tool.

5. Signing tool sends back signed CSRs (certificate chain for each curve) to the PDP script. PDP script sends a command to the device that triggers Amazon on-device certificate generation module's write certificate chain API to insert signed CSRs to the device.

6. PDP script sends a command to the device that triggers Amazon on-device certificate generation module's write application server public key API to insert the application server public key to the device.

7. PDP script sends a command to the device that triggers Amazon on-device certificate generation module's verify and store API. This basically writes all the generated manufacturing information onto the manufacturing image NVM3 instance.

In this walkthrough, we are going to use the manufacturing provisioning script that leverages Secure Vault to store the private keys.

Running the Initialization Script#

For On-Device Certificate Generation, the initialization script is not needed anymore. Instead, directly use the Sidewalk application as input to the provisioning script.

Running the Provisioning Script#

The provisioning script takes an SoC family, Sidewalk application image, Production Device Provisioner image, and YubiHSM related information as input arguments, and provisions the end device with device credentials generated on the device. This script must be run on each device in production, using the following steps:

1. Connect your device with a supported EFR32 chip.

2. Connect the YubiHSM key.

3. Run the following command in as administrator: sudo yubihsm-connector -d.

4. Navigate to tools/scripts/public/pdp directory.

5. Fill the configuration file with the product information.

6. Run the following commands.

Ⓘ INFO Ⓘ: If you prefer to flash the initialization image before the provisioning, leave the sid-init-img field empty.

{
    "part": "part_number_like_efr32zg28b322f1024im68",
    "sid_init_img": "out/sid_init_img.s37",
    "pdp_img": "/path/to/pdp/app.s37",
    "dev_type": "dev_type_like_A232AX65BNIW2J",
    "apid": "advertised_product_id_like_zGhh",
    "app_srv_pub_key": "app_srv_pub_key_like_887fc49bb23ffbbdb98550040506c7eddf696707519b0c1c603e4bf8801631c6",
    "sst_prod_tag": "prod_tag_like_RNET_DAK_DUMMY",
    "sst_hsm_conn_addr": "hsm_yubi_connector_addr_like_http://localhost:12345",
    "sst_hsm_pin": "yubi_hsm_pin_like_1234"
}

python3 provision_silabs.py \
  --dsn <device_serial_no_like_G6F1JN06119201GP> \
  --prod-config template_prod_config.json
  --pdp-mode on_dev_cert_gen

With fields as follows:

• part: Part number (efr32zg28b322f1024im68)

• sid_init_img: Sidewalk custom application binary (.s37 file)

• pdp_img: Sidewalk Production Device Provisioner application binary (.s37 file)

• dev_type: This field is provided by Amazon upon HSM provisioning request

• apid: This value can be extracted from the device profile associated to your HSM

• app_srv_pub_key: This value can be extracted from the device profile associated to your HSM

• sst_prod_tag: This field is provided by Amazon upon HSM provisioning request

• sst_hsm_conn_addr: This is the socket address connected to your HSM usb key, it is http://localhost:12345 by default in yubico toolkit

• sst_hsm_pin: This field is provided by Amazon upon HSM provisioning request

And arguments as follows:

• dsn: This field is used to generate the Sidewalk SMSN, it shall be unique for each device

• pdp-mode: To choose between On-device certificate generation and OpenSSL private key provisioning

• prod-config: Path to the configuration file

To use the script with command-line arguments instead of a configuration file, simply drop the --prod-config parameter and add all configuration fields as arguments.

After completing this step, the Sidewalk end device is now provisioned and all public information is stored in the out/ folder for the device upload to the cloud following the standard Amazon flow.

OpenSSL Private Key Provisioning (Deprecated)#

This manufacturing flow is deprecated as of Amazon Sidewalk SDK 1.16. See the security section above for information on whether or not you can use this flow for your product.

This flow is an extension of the now deprecated Standard Amazon flow below.

In the Silicon Lab version of this flow, the private key are wrapped by the Secure Vault instead of the flash. The manufacturing page contains references to the Secure Vault slot storing the private keys.

1. The endpoint key pair is generated on the production computer and the Signing Tool provided by Amazon is called to start certificate generation.

2. The HSM, provisioned by Amazon, is used to sign the Certificate Signing Request (CSR) and outputs the certificate.

3. The signing tool is used along with the HSM to create the certificate chain from the endpoint certificate to the Sidewalk Network server and Application certificates. Control logs are generated as well.

4. Once the certificate chain is generated, it can be used to generate the manufacturing page with the provisioning script. The private keys are wrapped by the Secure Element as described in the Secure Vault documentation section 3.3.1. The manufacturing page, containing the private keys ID from Secure Vault, is flashed to the device.

5. Control logs are assembled into a database and can be uploaded to the cloud to populate the devices record.

6. Once all devices are entered into the record, the devices are known to the backend and can be created using the import tasks. A list of all SMSNs of created devices can be uploaded to the cloud to create the corresponding virtual devices in IoT Core.

Leveraging Secure Vault does not use the manufacturing page (MFG) generated by the prototyping scripts. Instead it uses the WirelessDevice.json and DeviceProfile.json files obtained as outputs from the prototyping scripts described in the Prototyping APIs section. The steps are as follows:

1. The initialization script creates an output file (.s37) containing a part of the manufacturing page that is identical for all the devices created using the same Device Profile.

2. The output of this initialization script can optionally include the Sidewalk application binary.

3. The device-specific information is provisioned to the device using the provisioning script. Here, the rest of the manufacturing page on the device will be completed with the device-specific information.

To summarize, the initialization script generates an output file that can be flashed to all devices. Then the provisioning script is used to provision the device credentials. The credentials are wrapped by keys contained in the Secure Vault and stored in the Default NVM3 Instance as described in the Non-Volatile Memory Use section.

OpenSSL Private Key Provisioning Walkthrough (Deprecated)#

Device certificate is generated outside of the device so it is intrinsically less secure. Amazon's signing server tool generates device certificates using OpenSSL and YubiHSM.

Here is an overview of what happens in this mode:

1. All dynamic data is sent to the device.

2. ED25519 and P256R1 device private keys are wrapped by the Secure Vault.

Production provisioning scripts consist of two functions: initialization and provisioning. The scripts can be used in three different configurations:

1. You can include the application binary in the initialization script and use the output of the script in the provisioning script. This flashes both binaries containing the application, MFG common section, and MFG device-specific section.

2. You can call the initialization script with the application binary. Flash the resulting image, which contains the application and MFG common section, on your device. Then call the provisioning script without the initialization image (sid-init-img) option to flash the remaining MFG device-specific information.

3. You can omit the application binary in the initialization script (sid-app option). You will have to flash the output of the initialization script (MFG common section) before calling the provisioning one. Then you can call the provisioning script (MFG device-specific section). The application binary can be flashed at any point or added as an argument of the provisioning script (using the sid-init-img option).

In all the flows, the only hard requirement is to flash the output of initialize_silabs.py (sid.s37) before calling silabs_provision.py. The common information in the manufacturing page must be on the device before the device-specific one. See the diagram below for more details.

The production script folder contains several python scripts (initialization_silabs.py and provision_silabs.py). In the following instructions on each script, two commands are shown, one for prototyping and one for manufacturing. The prototyping one can be used with the output files of the Amazon prototyping flow (DeviceProfile.json and WirelessDevice.json) while the manufacturing one can be used with Amazon manufacturing flow output files containing the private keys.

Before provisioning your device, you will need to enable Secure Vault in your Sidewalk application and to compile the Production Device Provisioner application needed in the next steps.

Running the Initialization Script#

The initialization script takes an Amazon Sidewalk device certificate, SoC family and Sidewalk application binary as input arguments and generates a binary file that contains the static (common) part of the Sidewalk certificate and the Sidewalk application provided as input arguments. The output binary file is common to all the product instances so it does not contain any device-specific information (device-specific information is provisioned in the next step). This script can be run once to generate the common binary in the production, following these steps:

1. Navigate to tools/scripts/public/pdp directory.

2. Run the commands below.

pip3 install -r requirements.txt
 
# For manufacturing
python3 initialize_silabs.py --sid-cert </path/to/certificate.json> --sid-cert-type prod --soc <soc> --sid-usr-app-img </path/to/user/sid/app.s37> --pdp-mode priv_key_prov
 
# For prototyping
python3 initialize_silabs.py --sid-cert </path/to/WirelessDevice.json> --sid-cert-type proto --sid-dev-prof </path/to/DeviceProfile.json> --soc <soc> --sid-usr-app-img </path/to/user/sid/app.s37> --pdp-mode priv_key_prov

With arguments as follows:

• sid-cert: Sidewalk device certificate containing private key pairs or Wireless Device JSON file from AWS.

• sid-cert-type: Either prod or proto depending on the flow in use (manufacturing or prototyping)

• sid-dev-prof: If prototyping flow, we need to give the Device Profile JSON file

• part: Part number (like efr32zg28b322f1024im68)

• sid-usr-app-img: Sidewalk custom application

• pdp-mode: To choose between On-device certificate generation and OpenSSL private key provisioning

At the end of this step, an output file (in tools/scripts/public/pdp/out) that contains the static (common) part of the Sidewalk certificate and the Sidewalk application is generated. It will be used as an input argument in the next step.

Running the Provisioning Script#

The provisioning script takes a Sidewalk device certificate, SoC family, initialization image (generated in the previous step), and provisioning image (.bin image generated in Simplicity Studio by compiling the Production Device Provisioner sample application) as input arguments and provisions the end device with device credentials extracted from the Sidewalk device certificate. This script must be run per device in production, using the following steps:

1. Connect your device with a supported EFR32 chip.

2. Navigate to tools/scripts/public/pdp directory.

3. Run the following commands.

Ⓘ INFO Ⓘ: If you prefer to flash the initialization image before the provisioning, you can skip the --sid-init-img argument.

# For manufacturing
python3 provision_silabs.py --sid-cert </path/to/certificate.json> --sid-cert-type prod --soc <soc> --sid-init-img out/sid_init_img.s37 --pdp-img </path/to/pdp/app.s37> --pdp-mode --pdp-mode priv_key_prov
 
# For prototyping
python3 provision_silabs.py --sid-cert </path/to/WirelessDevice.json> --sid-cert-type proto --soc <soc> --sid-init-img out/sid_init_img.s37 --pdp-img </path/to/pdp/app.s37> --pdp-mode priv_key_prov

With arguments as follows:

• sid-cert: Sidewalk device certificate containing private key pairs or Wireless Device JSON file from AWS.

• sid-cert-type: Either prod or proto depending on the flow in use (manufacturing or prototyping)

• soc: SOC family (xg21, xg24...)

• sid-init-img: Initialization image generated in the previous step

• pdp-img: Sidewalk Production Device Provisioner application

• pdp-mode: To choose between On-device certificate generation and OpenSSL private key provisioning

After completing this step, the Sidewalk end device is now provisioned with device-specific credentials.