Examples#
Provisioning for secure boot using Simplicity Commander#
This section demonstrates how to provision the security settings onto a factory new SiWx917 device. The most reliable method of provisioning settings is to place the device into ISP mode. For instance, hold the ISP button on the radioboard (BRD4338A), and press and release the reset button on the WSTK/WPK board before releasing the ISP button.
Check the version of Simplicity Commander. The version should be at least 1v16p8b1613 to support SiWx917 operations.
commander -vSimplicity Commander 1v16p8b1613 JLink DLL version: 7.94e Qt 5.12.10 Copyright (C) 2017 The Qt Company Ltd. EMDLL Version: 0v19p5b744 mbed TLS version: 2.16.6 DONEUpdate the board controller firmware to 1v5p0b240, or higher
Please see the “Adapter Firmware” section of https://docs.silabs.com/simplicity-studio-5-users-guide/5.3.0/ss-5-users-guide-about-the-launcher/welcome-and-device-tabs for specific instructions, as needed.
Initialize security features:
Put the device in ISP mode. On Silicon Labs development kits, hold down the ISP button on the radio board, then press and release the reset button on the WPK board, then release the ISP button on the radio board. Next, enter the following command
commander manufacturing init --mbr defaultUsing default MBR for SiWG917M111MGTBA... Loading RAM code (321776 bytes)... Starting RAM code... Calibration code initialized. Activation code generated successfully DONENote: Only execute this command once per device.
Create a JSON file with the keys data:
commander util genkeyconfig --outfile keys\keys.json --device Si917Generating symmetric key... Generating symmetric key... Generating ECC P256 key pair... Generating ECC P256 key pair... Generating ECC P256 key pair... Key configuration written to keys\keys.json DONESave the keys to PEM format as follows:
commander util extractkeys keys\keys.json --dir keysWriting ATTESTATION_PRIVATE_KEY to 'keys/attestation_private_key.pem' Writing ATTESTATION_PUBLIC_KEY to 'keys/attestation_public_key.der' Writing M4_OTA_KEY to 'keys/m4_ota_key.txt' Writing M4_PRIVATE_KEY to 'keys/m4_private_key.pem' Writing M4_PUBLIC_KEY to 'keys/m4_public_key.der' Writing OTA_KEY to 'keys/ota_key.txt' Writing TA_PRIVATE_KEY to 'keys/ta_private_key.pem' Writing TA_PUBLIC_KEY to 'keys/ta_public_key.der' DONEProvision keys to the device. Ensure that the device is in ISP mode, according to the instructions at the beginning of this section, and enter the following command:
commander mfg917 provision --keys keys\keys.jsonNote:
commander mfg917 …is a shorthand alias forcommander manufacturing …Reading MBR from the connected device... Reading 496 bytes from 0x04000000 Reading keys from provided JSON file... Reading 1024 bytes from 0x040003e0 Reading 496 bytes from 0x04000000 Reading 112 bytes from 0x040001f0 Reading 88 bytes from 0x04000300 Reading 1024 bytes from 0x040003e0 Reading 58 bytes from 0x04000561 Reading 200 bytes from 0x04000238 Reading 72 bytes from 0x040001f0 Loading RAM code (321776 bytes)... Starting RAM code... Calibration code initialized. Intrinsic keys generated successfully. Programming TA OTA Key... Key successfully stored Programming M4 OTA Key... Key successfully stored Programming TA Public Key... Key successfully stored Programming M4 Public Key... Key successfully stored Programming attestation Key... Key successfully stored Programming ROM patch... Reading 200 bytes from 0x04000238 ROM patch is already present on the device. Programming TA MBR... Reading 496 bytes from 0x04000000 The on-device TA MBR is already up to date. Programming M4 MBR... Data loaded successfully Programming key descriptor table... Data loaded successfully DONEEnable secure boot with signature validation and rollback protection by creating an mbr json file as below.
{ "valids": 0, "puf_activation_code_addr": 8192, "valids": 0, "efuse_data": { "disable_m4ss_kh_access": 0, "m4_digital_signature_validation": 1, "m4_encrypt_firmware": 0, "m4_fw_encryption_mode": 0, "m4_secure_boot_enable": 1, "m4_anti_roll_back":1, "ta_digital_signature_validation": 1, "ta_encrypt_firmware": 0, "disable_m4_access_frm_tass_sec": 1, "ta_secure_boot_enable": 1, "disable_ta_jtag":0, "disable_m4_jtag":0 }, "key_desc_table_addr": 768 }Place the board in ISP mode as described previously and provision the new MBR settings.
commander mfg917 provision --data mbr_security_an1442.jsonReading MBR from the connected device... Updating MBR fields... Reading JSON... Loading RAM code (321776 bytes)... Starting RAM code... Programming TA MBR... Data loaded successfully Programming ROM patch... ROM patch is already present on the device. Programming M4 MBR... Data loaded successfully Programming IPMU data... The on-device M4 IPMU data is already up to date. DONE
Signing an Application for Secure boot using Simplicity Commander#
This section provides a method for signing an RPS image for secure boot.
Build a sample app, such as the “SL Blinky” demo found in the WiSeConnect SDK available in the Simplicity Studio IDE.
Convert the RPS file created in the previous step to add the signature and MIC.
commander rps convert sl_blinky_secure.rps --sign keys\keys.json --sha SHA-256 --mic keys\keys.json --app sl_si91x_blinky.rpsWARNING: App image size (39432 B) is not aligned to 16 B (128 bits), which is a requirement for image encryption and MIC calculation. Appending zero-bytes to align... Parsing MIC key 'keys.json'... Calculating MIC of image... Parsing signing key 'keys.json'... Signing image... Image SHA256: 2b4d974a43af3c3864431b4ee5c6a2cd23a8b086ba99689caf88ac470f073458 R = 2EB730D634471932F0AB72D7FE9719DAB6A91A270B31B9B588020B4C0D14B0AF S = 21E2E1A5BD51F8181886E47465E51F7C0BB284AFC6E674D278BD0C3128700B57 RPS file successfully created at 'sl_blinky_secure.rps'. DONEOptionally, display the RPS file information to confirm that the file was created as intended.
commander util rpsinfo m4_signed_oob_demo.rpsRPS application image Application info: Combined image bit set : No Image type : M4 application Image size : 0x00018D18 (101656) B Flash address : 0x00201000 Firmware version : 0x00000001 Firmware version ext. : 0x00000000 PSRAM : No Security settings: Integrity check : MIC MIC : 26 07 4E C6 6F 62 A5 3B 68 90 74 7A DE B7 81 D3 Encrypted : No Signed : Yes SHA type : SHA-256 Signature : 3045022019B1666F7161B5529063391B7BA201B16DB29C8AB39B26E68B88928CAC99A259022100F371B2DED144E7CF65 845834BC48BA406114D9615C2372A00CB6A7D72338FF8A00 Boot descriptor info: Boot desc. offset : 0x0000 IVT offset : 0x08202000 1 boot descriptor entry found: Length : 0x000000 (0) Destination : 0x00000000 DONEFlash the RPS file to the target board.
commander rps load m4_signed_oob_demo.rpsUploading flashloader... Waiting for flashloader to become ready Writing data... Waiting for bootloader to perform upgrade... Resetting DONE
Using and Testing Anti-rollback Protection#
This example covers the steps to perform an application update, using anti-rollback prevention to prevent older firmware from being installed.
Ensure that anti-rollback protection is enabled through setting the
m4_anti_roll_backeFuse in your target device. To accomplish this, follow steps 1-6 in Provisioning for secure boot using Simplicity Commander.Create an RPS file with the firmware version set to 0. The firmware version is set to 0by default so you can use the RPS file created in step 1 in the previous example Signing an Application for Secure boot using Simplicity Commander.
Load the application to your target device, if you have not already done so. The command is shown in step 4 of Signing an Application for Secure boot using Simplicity Commander.
Increase the security version of the application using the –app-version option as shown below. Refer to Table Firmware Version Layout in RPS Files for the layout of the firmware version, as necessary.
commander rps convert m4_out_of_box_demo_security_version1.rps --app "out_of_box_demo.rps" --sha SHA-256 --sign json\m4_private_key.pem --mic json\keys.json --app-version 0x00000100WARNING: App image size (101636 B) is not aligned to 16 B (128 bits), which is a requirement for image encryption and MIC calculation. Appending zero-bytes to align... Parsing MIC key 'json\m4_ota_key.h'... Calculating MIC of image... Parsing signing key 'json\m4_private_key.pem'... Signing image... Image SHA256: cc192cff152919cdc085a5226c39435f6278fd89589beff03cbad8227fdb3725 R = BE4390FF2A1778DF48FA3C7523568ED7DBA61C9251943D0FC031C09372BE8694 S = 1F4B4502DA2D183C8601DFDD26FA16B8F7922CB18F6A8901390BCB5C6D156531 RPS file successfully created at 'm4_out_of_box_demo_security_version1.rps'. DONEFlash the new RPS image to the target device, the image should load and boot normally.
commander rps load m4_out_of_box_demo_security_version1.rpsUploading flashloader... Waiting for flashloader to become ready Writing data... Waiting for bootloader to perform upgrade... Resetting DONEOptional step – confirm that the security version has been stored in OTP memory
commander mfg917 read efuse --out efuse.jsonReading data from region: efuse Reading 1024 bytes from 0x40012000 Writing JSON... Manufacturing data saved to file 'efuse.json' DONENote: In eFuse.json, the security version is stored in big-endian format.
"anti_rollback_bitmap_m4_image": "0100000000000000",Confirm that anti-rollback protection is working by attempting to load the previous image with security version 0 as follows:
commander rps load m4_signed_m4key_oob_demo.rpsUploading flashloader... Waiting for flashloader to become ready Writing data... Waiting for bootloader to perform upgrade... ERROR: Waiting for flashloader failed: 108 DONENote: The image is rejected due to the anti-rollback check failing.
Reset the device to resume running the previously loaded application.
Moving to Production#
This section describes the steps recommended for moving to production. The main difference between development and production is that during development, the master boot record (MBR) is used to configure security settings so that they can be changed if needed and the JTAG ports are enabled, while in production, the eFuses (OTP) are used to make the security settings immutable and the JTAG ports are locked.
Read the eFuses from a factory new device.
commander mfg917 read efuse --out efuse.json --device SIWG917M111MGTBAReading data from region: efuse Reading 1024 bytes from 0x40012000 Writing JSON... Manufacturing data saved to file 'efuse.json' DONEOpen
eFuse.jsonin a text editor and make the following changes to enable secure boot with anti-rollback protection and signature verification for both cores. Themagic_bytefield is used to indicate that the contents of the eFuse block is valid."bootloader_config": { "m4_anti_roll_back": 1, "m4_digital_signature_validation": 1, "safe_upgrade_frm_host": 0, "sdio_combo_mode": 0, "ta_anti_roll_back": 1, "ta_digital_signature_validation": 1, "ta_secure_boot_enable": 1, }, "m4_and_security_config": { "common_flash_enabled": 0, "m4_encrypt_firmware": 0, "m4_flash_pinset": 0, "m4_flash_present": 0, "m4_flash_type": 0, "m4_secure_boot_enable": 1 }As a final step in production, disable the JTAG ports by making the following changes to `eFuse.json’, it is safe to skip this step for now if you need frequent access to the debug ports.
"mcu_chip_modes": { "disable_analog_periph": 0, "disable_can_interface": 0, "disable_cci": 0, "disable_ethernet": 0, "disable_fim_cop": 0, "disable_m4": 0, "disable_m4_access_frm_tass_sec": 0, "disable_m4_jtag": 1, "disable_m4_ulp_mode": 0, "disable_m4ss_kh_access": 0, "disable_tass_kh_access": 0, "disable_touch": 0, "disable_usb": 0, "disable_vad": 0, "disable_wurx": 0, "limit_m4_freq_110mhz": 0, "m4_flash_size": 0, "m4_otp_lock": 0 },Save the file
eFuse.json.Write the new eFusesettings back to the target device as follows:
commander mfg917 write efuse --data efuse.json -d SIWG917M111MBTGAcontinueReading JSON... The provided data can be applied to the current Efuse. Determining which OTP words need updating... ================================================================================ THIS IS A ONE-TIME command which PERMANENTLY writes data to the Efuse region of your device. This command CANNOT be undone. Type 'continue' and hit enter to proceed or Ctrl-C to abort:Reset the target device for the settings to take effect.
Writing 16 bytes to OTP... Loading RAM code (321776 bytes)... Starting RAM code... Efuse was successfully written to the device's OTP. DONE