Examples#

Overview#

The examples for HSE-SVH Anti-Tamper module are described in the following table.

Note: Unless specified in the example, these examples can be applied to other HSE-SVH devices.

Using a Platform Example#

Simplicity Studio 5 includes the SE Manager platform example for tamper. This application note uses platform examples of GSDK v4.1.0. The console output may be different on the other version of GSDK.

Refer to the corresponding readme file for details about each SE Manager platform example. This file also includes the procedures to create the project and run the example.

Using Simplicity Commander#

1. This application note uses Simplicity Commander v1.14.6. The procedures and console output may be different on other versions of Simplicity Commander. The latest version of Simplicity Commander can be downloaded from .

   commander --version

   Simplicity Commander 1v14p6b1289
   
   JLink DLL version: 7.70d  
   Qt 5.12.10 Copyright (C) 2017 The Qt Company Ltd.  
   EMDLL Version: 0v18p9b677  
   mbed TLS version: 2.16.6  
   
   DONE

2. The Simplicity Commander's Command Line Interface (CLI) is invoked by commander.exe in the Simplicity Commander folder. The location for Simplicity Studio 5 in Windows is C:\SiliconLabs\SimplicityStudio\v5\developer\adapter_packs\commander. For ease of use, it is highly recommended to add the path of commander.exe to the system PATH in Windows.

3. If more than one Wireless Starter Kit (WSTK) is connected via USB, the target WSTK must be specified using the --serialno \<J-Link serial number> option.

4. If the WSTK is in debug mode OUT, the target device must be specified using the --device \<device name> option.

For more information about Simplicity Commander, see the Simplicity Commander Reference Guide.

Using Simplicity Studio#

The security operations are performed in the Security Settings of Simplicity Studio. This application note uses Simplicity Studio v5.4.0.0. The procedures and pictures may be different on the other version of Simplicity Studio 5.

1. Right-click the selected debug adapter RB (ID:J-Link serial number) to display the context menu.

2. Click Device configuration... to open the Configuration of device: J-Link Silicon Labs (serial number) dialog box. Click the Security Settings tab to get the selected device configuration.

Using an External Tool#

The tamper disable example uses OpenSSL to sign the access certificate and challenge response. The Windows version of OpenSSL can be downloaded from Shining Light Productions. This application note uses OpenSSL Version 1.1.1h (Win64).

openssl version

OpenSSL 1.1.1h  22 Sep 2020

The OpenSSL's Command Line Interface (CLI) is invoked by openssl.exe in the OpenSSL folder. The location in Windows (Win64) is C:\Program Files\OpenSSL-Win64\bin. For ease of use, it is highly recommended to add the path of openssl.exe to the system PATH in Windows.

Provision Public Command Key and Tamper Configuration#

The Public Command Key pair can be generated from the "unsafe" private key delivered with Simplicity Studio, by Simplicity Commander, or by a Hardware Security Module (HSM). Using an HSM is recommended for production systems.

Generated from "Unsafe" Key

External tools such as openssl can be used to generate a public key from the reference private key provided in Simplicity Studio. Note that this private key is well known and should not be used in production devices.

Run the openssl ec command to generate the Public Command Key from the Private Command Key.

openssl ec -in /c/SiliconLabs/SimplicityStudio/v5/developer/adapter_packs/secmgr/scripts/offline/cmd-unsafe-privkey.pem -pubout -out cmd-unsafe-pubkey.pem

Generated Using Simplicity Commander

Run the util genkey command to generate the Public Command Key pair (command_key.pem and command_pubkey.pem) and Public Command Key token file (command_pubkey.txt).

commander util genkey --type ecc-p256 --privkey command_key.pem --pubkey command_pubkey.pem --tokenfile command_pubkey.txt

Generating ECC P256 key pair...
Writing private key file in PEM format to command_key.pem
Writing public key file in PEM format to command_pubkey.pem
Writing EC tokens to command_pubkey.txt...
DONE

SE Manager - Tamper Platform Example#

Click the View Project Documentation link to open the readme file for instructions on creating the project and running the example.

1. Press ENTER two times to program the secure boot and tamper configuration to the HSE OTP of an uninitialized device.

   SE Manager Tamper Example - Core running at 38000 kHz.
     . SE manager initialization... SL_STATUS_OK (cycles: 7 time: 0 us)
     . Read EMU RSTCAUSE register... SL_STATUS_OK (cycles: 3728 time: 98 us)
     + The EMU RSTCAUSE register (MSB..LSB): 00000043
     . Read SE OTP configuration... SL_STATUS_NOT_INITIALIZED (cycles: 7487 time: 197 us)
     + Cannot read SE OTP configuration.
     + Press ENTER to initialize SE OTP for tamper configuration or press SPACE to abort.
     + Warning: The OTP configuration cannot be changed once written!
     + Press ENTER to confirm or press SPACE to abort if you are not sure.
     + Initialize SE OTP for tamper configuration... SL_STATUS_OK (cycles: 267256 time: 7033 us)
     + Issue a power-on or pin reset to activate the new tamper configuration.
     . SE manager deinitialization... SL_STATUS_OK (cycles: 9 time: 0 us)

   Note: This example does not enable the secure boot.

2. Press the RESET button on the WSTK to restart the program. It will display the current tamper configuration of the device.

   SE Manager Tamper Example - Core running at 38000 kHz.
     . SE manager initialization... SL_STATUS_OK (cycles: 10 time: 0 us)
     . Read EMU RSTCAUSE register... SL_STATUS_OK (cycles: 3736 time: 98 us)
     + The EMU RSTCAUSE register (MSB..LSB): 00000043
     . Read SE OTP configuration... SL_STATUS_OK (cycles: 7174 time: 188 us)
     + Secure boot: Disabled  
     + Tamper source level  
       Filter counter         :  1  
       SE watchdog            :  4  
       SE RAM CRC             :  4  
       SE hard fault          :  4  
       SE software assertion  :  4  
       SE secure boot         :  4  
       User secure boot       :  0  
       Mailbox authorization  :  1  
       DCI authorization      :  0  
       OTP read               :  4  
       Self test              :  4  
       TRNG monitor           :  1  
       PRS0                   :  1  
       PRS1                   :  1  
       PRS2                   :  2  
       PRS3                   :  2  
       PRS4                   :  4  
       PRS5                   :  4  
       PRS6                   :  7  
       PRS7                   :  7  
       Decouple BOD           :  4  
       Temperature sensor     :  2  
       Voltage glitch falling :  2  
       Voltage glitch rising  :  2  
       Secure lock            :  4  
       SE debug               :  0  
       Digital glitch         :  2  
       SE ICACHE              :  4
     + Reset period for the tamper filter counter: ~32 ms x 1024
     + Activation threshold for the tamper filter: 4  
     + Digital glitch detector always on: Disabled  
     + Tamper reset threshold: 5
   
     . Current tamper test is NORMAL.
     + Press SPACE to select NORMAL or TAMPER DISABLE, press ENTER to run.

Simplicity Commander#

1. Run the security writekey command to provision the Public Command Key (e.g., command_pubkey.pem).

   commander security writekey --command **command_pubkey.pem** --device EFR32MG21B010F1024 --serialno 440030580

   Device has serial number 000000000000000014b457fffe0f77ce
   
   ================================================================================
   Please look through any warnings before proceeding.
   THIS IS A ONE-TIME command which permanently ties debug and tamper access to certificates signed by this key.
   Type 'continue' and hit enter to proceed or Ctrl-C to abort:
   ================================================================================
   continue
   DONE

   Note: The Public Command Key cannot be changed once written.

2. Run the security readkey command to read the Public Command Key from the HSE OTP for verification with the key in step 1.

   commander security readkey --command --device EFR32MG21B010F1024 --serialno 440030580 

   B1BC6F6FA56640ED522B2EE0F5B3CF7E5D48F60BE8148F0DC08440F0A4E1DCA4
   7C04119ED6A1BE31B7707E5F9D001A659A051003E95E1B936F05C37EA793AD63
   DONE

3. Run the security genconfig command to generate a default user_configuration.jsonfile for secure boot and tamper configuration.

   commander security genconfig --nostore -o user_configuration.json --device EFR32MG21B010F1024 --serialno 440030580

   Configuration file written to user_configuration.json
   DONE

   Note: Simplicity Commander Version 1.14.6 or above is required to support tamper configuration for all HSE-SVH devices.

4. Use a text editor to modify the default tamper responses in user_configuration.json to the desired configuration as below.

   {
       "OPN": "EFR32MG21B010F1024",
       "VERSION": "1.0.0",
       "mcu_flags": {
           "SECURE_BOOT_ANTI_ROLLBACK": false,
           "SECURE_BOOT_ENABLE": false,
           "SECURE_BOOT_PAGE_LOCK_FULL": false,
           "SECURE_BOOT_PAGE_LOCK_NARROW": false,
           "SECURE_BOOT_VERIFY_CERTIFICATE": false
       },
       "tamper_filter": {
           "FILTER_PERIOD": 10,
           "FILTER_THRESHOLD": 6,
           "RESET_THRESHOLD": 5
       },
       "tamper_flags": {
           "DGLITCH_ALWAYS_ON": false
       },
       "tamper_levels": {
           "DCI_AUTH": 0,
           "DECOUPLE_BOD": 4,
           "DGLITCH": 2,
           "FILTER_COUNTER": 1,
           "MAILBOX_AUTH": 1,
           "OTP_READ": 4,
           "PRS0": 1,
           "PRS1": 1,
           "PRS2": 2,
           "PRS3": 2,
           "PRS4": 4,
           "PRS5": 4,
           "PRS6": 7,
           "PRS7": 7,
           "SECURE_LOCK": 4,
           "SELF_TEST": 4,
           "SE_CODE_AUTH": 4,
           "SE_DEBUG": 0,
           "SE_HARDFAULT": 4,
           "SE_ICACHE": 4,
           "SE_RAM_CRC": 4,
           "SOFTWARE_ASSERTION": 4,
           "TEMP_SENSOR": 2,
           "TRNG_MONITOR": 1,
           "USER_CODE_AUTH": 0,
           "VGLITCH_FALLING": 2,
           "VGLITCH_RISING": 2,
           "WATCHDOG": 4
       }
   }

   Note: This example does not enable the secure boot.

5. Run the security writeconfig command to program the secure boot and tamper configuration to the HSE OTP. This command can be executed once per device.

   commander security writeconfig --configfile user_configuration.json --device EFR32MG21B010F1024 --serialno 440030580

   ================================================================================
   THIS IS A ONE-TIME configuration: Please inspect file before confirming:
   user_configuration.json
   Type 'continue' and hit enter to proceed or Ctrl-C to abort:
   ================================================================================
   continue
   DONE

6. Run the security readconfig command to check the secure boot and tamper configuration of the device.

   commander security readconfig --serialno 440030580

   MCU Flags
   Secure Boot                    : Disabled
   Secure Boot Verify Certificate : Disabled
   Secure Boot Anti Rollback      : Disabled
   Secure Boot Page Lock Narrow   : Disabled
   Secure Boot Page Lock Full     : Disabled
   
   Tamper Levels
   FILTER_COUNTER     : 1
   WATCHDOG           : 4
   SE_RAM_CRC         : 4
   SE_HARDFAULT       : 4
   SOFTWARE_ASSERTION : 4
   SE_CODE_AUTH       : 4
   USER_CODE_AUTH     : 0
   MAILBOX_AUTH       : 1
   DCI_AUTH           : 0
   OTP_READ           : 4
   SELF_TEST          : 4
   TRNG_MONITOR       : 1
   PRS0               : 1
   PRS1               : 1
   PRS2               : 2
   PRS3               : 2
   PRS4               : 4
   PRS5               : 4
   PRS6               : 7
   PRS7               : 7
   DECOUPLE_BOD       : 4
   TEMP_SENSOR        : 2
   VGLITCH_FALLING    : 2
   VGLITCH_RISING     : 2
   SECURE_LOCK        : 4
   SE_DEBUG           : 0
   DGLITCH            : 2
   SE_ICACHE          : 4
   
   Tamper Filter
   Filter Period   : 10
   Filter Threshold : 6
   Reset Threshold  : 5
   
   Tamper Flags
   Digital Glitch Detector Always On: Disabled
   DONE

Simplicity Studio#

This example focuses on provisioning the Public Command Key and tamper configuration. It skips the procedures for provisioning of the Public Sign Key and Secure Boot Enabling.

1. Run the util keytotoken command to convert the Public Command Key file (PEM format) into a text file (command_pubkey.txt).

   commander util keytotoken command_pubkey.pem --outfile command_pubkey.txt

   Writing EC tokens to command_pubkey.txt...
   DONE

2. Open the Security Settings of the selected device as described in Using Simplicity Studio..

3. Click [Start Provisioning Wizard...] in the upper right corner to display the Secure Initialization dialog box.

   

4. Click [Edit] to open the Tamper Source Configuration dialog box. Use the dropdown menus to modify the default tamper responses to the desired configuration. Click [OK] to exit.

   

5. Click [Next >]. The Security Keys dialog box is displayed.

   

6. Using a text editor, open the command_pubkey.txt file generated in step 1.

   MFG_SIGNED_BOOTLOADER_KEY_X : B1BC6F6FA56640ED522B2EE0F5B3CF7E5D48F60BE8148F0DC08440F0A4E1DCA4
   MFG_SIGNED_BOOTLOADER_KEY_Y : 7C04119ED6A1BE31B7707E5F9D001A659A051003E95E1B936F05C37EA793AD63

7. Check Enable Writing Command Key. Copy the Public Command Key (X-point B1BC... first, then Y-point 7C04...) to the Key: box under Command Key:.

   

   Note: This example does not enable the secure boot (not checking Enable Writing Sign Key option).

8. Click [Next >]. The Secure Locks dialog box is displayed. The Debug locks are set by default. Uncheck Enable secure debug unlock and Enable debug lock.

   

9. Click [Next >] to display the Summary dialog box. Verify the tamper configuration and Public Command Key in the Provisioning Summary are correct.

   

10. If the information displayed is correct, click [Provision]. Click [Yes] to confirm.

    

    Note: The Public Command Key and tamper configuration cannot be changed once written.

11. The Provisioning Status is displayed in the Summary dialog box.

    

12. Click [Done] to exit the provisioning process. The device configuration is updated.

    

13. Click the View... link to check the tamper configuration or click [OK] to exit.

Tamper Disable and Roll Challenge#

PRS Tamper Sources#

The tamper configuration in the SE Manager Tamper platform example is used to demonstrate the tamper disable on HSE-SVH devices. The following tables list the PRS tamper source usage on EFR32xG21B and other HSE-SVH devices on this example. The push buttons PB0 and PB1 are on the Wireless Starter Kit (WSTK) Mainboard.

Table: PRS Tamper Source Usage on EFR32xG21B Devices

Notes:

1. The tamper disable mask is 0x00fa0000 to restore the tamper sources PRS1, PRS3, PRS4, PRS5, PRS6, and PRS7 to default response (Ignore).

2. The Software PRS triggers the tamper source PRS5 to reset the device if the filter counter reaches the trigger threshold (4) within the filter reset period (~32 ms x 1024).

Table: PRS Tamper Source Usage on Other HSE-SVH Devices

Notes:

1. The HSE-SVH devices with ETAMPDET peripheral only have PRS0 (bit 26) to PRS5 (bit 31).

2. The tamper disable mask depends on whether the HSE-SVH device has an ETAMPDET peripheral.

   1. Without ETAMPDET peripheral, the tamper disable mask is 0xf2000000 to restore the tamper sources PRS0, PRS3, PRS4, PRS5, and PRS6 to default response (Ignore).

   2. With ETAMPDET peripheral, the tamper disable mask is 0xe4000000 to restore the tamper sources PRS0, PRS3, PRS4, and PRS5 to default response (Ignore).

3. The Software PRS triggers the tamper source PRS5 to reset the device if the filter counter reaches the trigger threshold (4) within the filter reset period (~32 ms x 1024).

SE Manager - Tamper Platform Example#

Click the View Project Documentation link to open the readme file for instructions on creating the project and running the example.

Follow the procedures in SE Manager - Tamper Platform Example if the HSE OTP is uninitialized. The following sections describe an initialized device that runs in Normal and Tamper Disable modes.

Normal#

1. Press ENTER to run the NORMAL tamper demo. Follow the instructions to go through the example.

     . Current tamper test is NORMAL.
     + Press SPACE to select NORMAL or TAMPER DISABLE, press ENTER to run.
   
     . Normal tamper test instructions:
     + Press PB0 to increase filter counter and tamper status is displayed.
     + PRS will issue a tamper reset if filter counter reaches 4 within ~32 ms x 1024.
     + Press PB1 to issue a tamper reset.
     + Device will enter diagnostic mode if tamper reset reaches 5.

2. Press PB0 to trigger PRS0 (Interrupt) and PRS2 (Filter) to issue an interrupt. The active tamper sources (0x00050000) of the EFR32xG21B device are PRS0 (bit 16) and PRS2 (bit 18).

     . Get tamper status... SL_STATUS_OK (cycles: 11937 time: 314 us)
     + Recorded tamper status (MSB..LSB): 00050001
     + Currently active tamper sources (MSB..LSB): 00050000

3. Press PB0 (Filter on PRS2) 4 times within ~32 ms x 1024 to trigger an interrupt when reaching the filer counter threshold. The program will use software PRS to issue a tamper reset through the PRS5 tamper source. The active tamper sources (0x00050002) of the EFR32xG21B device are Filter (bit 2), PRS0 (bit 16), and PRS2 (bit 18).

     . Get tamper status... SL_STATUS_OK (cycles: 11725 time: 308 us)
     + Recorded tamper status (MSB..LSB): 00050002
     + Currently active tamper sources (MSB..LSB): 00050002
     + Tamper filter threshold is reached, issue a reset through PRS

4. Press PB1 to trigger PRS4 (Reset) to issue a tamper reset.

5. After a tamper reset, the SETAMPER (bit 13) in EMU->RSTCAUSE register is set. Note that bit 1 indicates a pin reset and will also be set.

     . Read EMU RSTCAUSE register... SL_STATUS_OK (cycles: 4071 time: 107 us)
     + The EMU RSTCAUSE register (MSB..LSB): 00002002
     + The tamper reset is observed

6. After five consecutive tamper resets (reset threshold in this example), the device will enter diagnostic mode until a power-on or pin reset.

Tamper Disable#

This example uses the tamper disable mask (0x00fa0000) to restore the tamper sources PRS1, PRS3, PRS4, PRS5, PRS6, and PRS7 of EFR32xG21B device to default response (Ignore).

1. Press SPACE to select TAMPER DISABLE, press ENTER to run.

     . Current tamper test is NORMAL.
     + Press SPACE to select NORMAL or TAMPER DISABLE, press ENTER to run.
     + Current tamper test is TAMPER DISABLE.

2. This example will prompt to program the default Public Command Key in flash to the HSE OTP if this key does not exist. Press ENTER two times to confirm and ENTER again to restore the default tamper level. Follow the instructions shown in step 3 to go through the example (steps 4 to 6).

     . Verify the device public command key in SE OTP.
     + Exporting a public command key from a hard-coded private command key... SL_STATUS_OK (cycles: 210999 time: 5552 us)
     + Reading the public command key from SE OTP... SL_STATUS_NOT_INITIALIZED (cycles: 7763 time: 204 us)
     + Press ENTER to program public command key in SE OTP or press SPACE to abort.
     + Warning: The public command key in SE OTP cannot be changed once written!
     + Press ENTER to confirm or press SPACE to skip if you are not sure.
     + Programming a public command key to SE OTP... SL_STATUS_OK (cycles: 79656 time: 2096 us)
     + Press ENTER to disable tamper signals or press SPACE to exit.

3. Press ENTER to restore the default tamper level if the default Public Command Key in flash matches with the key in the HSE OTP. Follow the instructions to go through the example (steps 4 to 6).

     . Verify the device public command key in SE OTP.
     + Exporting a public command key from a hard-coded private command key... SL_STATUS_OK (cycles: 200804 time: 5284 us)
     + Reading the public command key from SE OTP... SL_STATUS_OK (cycles: 7134 time: 187 us)
     + Comparing exported public command key with SE OTP public command key... OK
     + Press ENTER to disable tamper signals or press SPACE to exit.
   
     . Start the tamper disable processes.
     + Creating a private certificate key in a buffer... SL_STATUS_OK (cycles: 214059 time: 5633 us)
     + Exporting a public certificate key from a private certificate key... SL_STATUS_OK (cycles: 206545 time: 5435 us)
     + Read the serial number of the SE and save it to access certificate... SL_STATUS_OK (cycles: 7930 time: 208 us)
     + Signing the access certificate with private command key... SL_STATUS_OK (cycles: 222650 time: 5859 us)
     + Request challenge from the SE and save it to challenge response... SL_STATUS_OK (cycles: 4208 time: 110 us)
     + Signing the challenge response with private certificate key... SL_STATUS_OK (cycles: 223559 time: 5883 us)
     + Creating a tamper disable token to disable tamper signals... SL_STATUS_OK (cycles: 946431 time: 24906 us)
     + Success to disable the tamper signals!
     
     . Tamper disable test instructions:
     + Press PB0 to increase filter counter and tamper status is displayed.
     + PRS will NOT issue a tamper reset even filter counter reaches 4 within ~32 ms x 1024.
     + Press PB1 will NOT issue a tamper reset.
     + Issue a power-on or pin reset to re-enable the tamper signals.
     + Press ENTER to roll the challenge to invalidate the current tamper disable token or press SPACE to exit.

4. Press PB0 to verify tamper sources PRS0 (Interrupt) and PRS2 (Filter) of EFR32xG21B device can still issue an interrupt.

     . Get tamper status... SL_STATUS_OK (cycles: 11259 time: 296 us)
     + Recorded tamper status (MSB..LSB): 00050001
     + Currently active tamper sources (MSB..LSB): 00050000

5. The PRS5 tamper source (configured as Reset) was restored to the default (Ignore), so it cannot issue a tamper reset even if users press PB0 (Filter on PRS2) 4 times within ~32 ms x 1024.

6. The PRS4 tamper source (configured as Reset) was restored to the default (Ignore), so it cannot issue a tamper reset even if users press PB1.

7. Issue a power-on or pin reset to exit the tamper disable state or press ENTER to roll the challenge.

     . Check and roll the challenge.
     + Request current challenge from the SE... SL_STATUS_OK (cycles: 0 time: 0 us)
     + The current challenge (16 bytes):
       AA C1 79 FC FC C5 78 8E A0 3F 91 AB 5D A9 C5 04
     + Rolling the challenge... SL_STATUS_OK (cycles: 0 time: 0 us)
     + Request rolled challenge from the SE... SL_STATUS_OK (cycles: 0 time: 0 us)
     + The rolled challenge (16 bytes):
       0F 63 9C 44 46 E4 7C B2 C9 CA 66 13 34 34 92 8E
     + Issue a power-on or pin reset to activate the rolled challenge.
   
     . SE manager deinitialization... SL_STATUS_OK (cycles: 0 time: 0 us)

Simplicity Commander#

The tamper disable was designed with three organizations in mind:

1. The Direct Customer to whom Silicon Labs sells the chip. This chip has the Public Command Key installed in the SE OTP.

2. The Product Company is a customer of the Direct Customer. This is applicable if the Direct Customer is creating a white-labeled product for another company or a sub-component that goes into another company’s product.

3. The Debug Party could be anyone, internal or external, that the Product Company decides is qualified to debug the device.

Because the Public Command Key is installed into the SE OTP of a large number of devices and cannot be changed, the corresponding Private Command Key must be guarded by a very stringent process. If this Private Command Key is ever leaked, all the devices programmed with the corresponding Public Command Key will be compromised.

A tamper disable use case is described in the following figure, and the signing process is performed by a Hardware Security Module (HSM).

The tamper disable flow moving across the time axis from left to right is explained below:

1. The Product Company creates a Private/Public Certificate Key pair for each device. Because the key pair is assigned only to a single device, the company may not need to protect the Private Certificate Key as securely as the Private Command Key by the Direct Customer.

   In this example, the Private/Public Certificate Key pair (cert_key.pemand and cert_pubkey.pem) is generated by running the util genkey command.

   commander util genkey --type ecc-p256 --privkey cert_key.pem --pubkey cert_pubkey.pem

   Generating ECC P256 key pair...
   Writing private key file in PEM format to cert_key.pem
   Writing public key file in PEM format to cert_pubkey.pem
   DONE

2. The Public Certificate Key (cert_pubkey.pem) for each device is passed to the Silicon Labs Direct Customer. The part number and serial number are also required if Direct Customer cannot access the device.

   Run the security status command to get the device serial number. The --serialno option is for the J-Link serial number of the WSTK.

   commander security status --device EFR32MG21B010F1024 --serialno 440030580

   SE Firmware version   : 1.2.9
   Serial number         : 000000000000000014b457fffe0f77ce
   Debug lock            : Disabled
   Device erase          : Enabled
   Secure debug unlock   : Disabled
   Tamper status         : OK
   Secure boot           : Disabled
   Boot status           : 0x20 - OK
   Command key installed : True
   Sign key installed    : False
   DONE

3. The Direct Customer then places that Public Certificate Key in the access certificate. The access certificate is per device because it contains the unique device serial number. This certificate is generated once upon creation of the device, and thereafter, is generally only modified when the Private/Public Certificate Key pair is changed by the Product Company.

   The following two steps are OPTIONAL for customization of Authorizations and Tamper Authorizations.

   a. (Optional) Run the security genauth command to generate the default certificate authorization file (certificate_authorization.json).

   commander security genauth -o certificate_authorizations.json --nostore --serialno 440030580

   DONE

   b. (Optional) Use a text editor to modify the default Authorizations and Tamper Authorizations in the json file.

   Run the security gencert command with the following parameters from the Product Company to generate an unsigned access certificate (access_certificate.extsign) in Security Store:

   • Device part number

   • Device serial number

   • Public Certificate Key

   commander security gencert --device EFR32MG21B010F1024 --deviceserialno 000000000000000014b457fffe0f77ce
   --cert-pubkey cert_pubkey.pem --extsign

   Authorization file written to Security Store:
   C:/Users/<username>/AppData/Local/SiliconLabs/commander/SecurityStore/device_000000000000000014b457fffe0f77ce/certificate_authorizations.json
   Cert key written to Security Store:
   C:/Users/<username>/AppData/Local/SiliconLabs/commander/SecurityStore/device_000000000000000014b457fffe0f77ce/cert_pubkey.pem
   Created an unsigned certificate in Security Store:
   C:/Users/<username>/AppData/Local/SiliconLabs/commander/SecurityStore/device_000000000000000014b457fffe0f77ce/access_certificate.extsign
   DONE

   Notes:

   • The --extsign option to create an unsigned access certificate is only available in Simplicity Commander Version 1.11.2 or above.

   • The unsigned access certificate is generated with the default certificate authorization file (certificate_authorization.json) which uses 0x0000003e for Authorizations and 0xffffffb6 (HSE-SVH device) for Tamper Authorizations (Table Elements of the Access Certificate on page).

   • (Optional) Use --authorization option if the customized json file generated in the above optional steps (a) and (b) is used.

     commander security gencert --device EFR32MG21B010F1024 --authorization certificate_authorizations.json
     --deviceserialno 000000000000000014b457fffe0f77ce --cert-pubkey cert_pubkey.pem --extsign

4. The signing of the access certificate can be done by passing an unsigned access certificate to a Hardware Security Module (HSM) containing the Private Command Key.

   In this example, the OpenSSL is used to sign the access certificate (access_certificate.extsign) in Security Store with the Private Command Key (command_key.pem). The access certificate signature is in the cert_signature.bin file.

   openssl dgst -sha256 -binary -sign command_key.pem -out cert_signature.binaccess_certificate.extsign

   Run the util signcert command with the following parameters to verify the signature and generate the signed access certificate (access_certificate.bin):

   • Unsigned access certificate

   • Access certificate signature

   • Public Command Key

   commander util signcert access_certificate.extsign --cert-type access --signature cert_signature.bin
   --verify command_pubkey.pem --outfile access_certificate.bin

   R = 76CDC5BA18E5248FDA5418002F250F149B449829A005D6F0726268016CC53ED4
   S = E4B8ABA2CF742B0E6CC5BA2C1023D76BEEF3C4A11DA97CC4D23459F32237A206
   Successfully verified signature
   Successfully signed certificate
   DONE

   Notes:

   • Put the required files in the same folder to run the command.

   • The util signcert command for access certificate is only available in Simplicity Commander Version 1.11.2 or above.

   • The access certificate signature can be in a Raw or Distinguished Encoding Rules (DER) format.

5. The access certificate is passed to the Product Company. The purpose of the access certificate is to grant overall debug access capabilities to the Product Company and authorize them to allow third parties to debug the device. The Product Company can now use the access certificate to generate the Disable Tamper Token. The same access certificate can be used to generate as many Disable Tamper Tokens as necessary without having to ever go back to the Direct Customer.

6. To create the Disable Tamper Token, a debug session must be started with the device and the challenge value (which is a random number Challenge 1 in this example) should be read out to generate the challenge response.

   Run the security gencommandcommand to generate the challenge response without disable tamper command signature and store it in a file (command_unsign.bin).

   commander security gencommand --action disable-tamper --disable-param 0x00fa0000 -o command_unsign.bin
   --nostore --device EFR32MG21B010F1024 --serialno 440030580

   Unsigned command file written to:
   command_unsign.bin
   DONE

   • The tamper disable mask (0x00fa0000) is based on the Tamper platform example on EFR32xG21B devices (Table PRS Tamper Source Usage on EFR32xG21B Devices).

   • If the --disable-param option is not provided, it will restore all tamper sources (0xffffffb6) by default.

7. The challenge response is then cryptographically hashed (SHA-256) to create a digest. The digest is then signed by the Private Certificate Key to generate the disable tamper command signature.

   The signing of the challenge response can be done by passing an unsigned challenge response to a Hardware Security Module (HSM) containing the Private Certificate Key.

   In this example, the OpenSSL is used to sign the challenge response (command_unsign.bin) with the Private Certificate Key (cert_key.pem). The disable tamper command signature is in the command_signature.bin file.

   openssl dgst -sha256 -binary -sign cert_key.pem -out command_signature.bincommand_unsign.bin

8. Run the security disabletamper command with the access certificate (access_certificate.bin) from Direct Customer and disable tamper command signature (command_signature.bin) in step 7 to generate the Disable Tamper Token.

   commander security disabletamper --disable-param  0x00fa0000 --cert access_certificate.bin
   --command-signature command_signature.bin EFR32MG21B010F1024 --serialno 440030580

   Certificate written to Security Store:
   C:/Users/<username>/AppData/Local/SiliconLabs/commander/SecurityStore/device_000000000000000014b457fffe0f77ce/access_certificate.bin
   R = A70834D97640A92510D151765F0EED6C6A05CB8BE81E06E905C230ED24E71659
   S = 9B69C113C2B7DEE60BF0BC7D72719F7F9465840D68EADBBB4F9BCE7A1267B936
   Command signature is valid
   Tamper successfully disabled.
   Command disable tamper payload was stored in Security Store
   DONE

   Notes:

   • Put the required files in the same folder to run the command.

   • The disable tamper command signature can be in a Raw or Distinguished Encoding Rules (DER) format.

   • Simplicity Commander Version 1.11.2 or above is required to support signature in DER format.

9. (Alternative) Key protection is not required if the Private Certificate Key is ephemeral. Steps 6 to 8 can be implemented by running the security disabletamper command with the access certificate (access_certificate.bin) from the Direct Customer and Private Certificate Key (cert_key.pem) to generate the Disable Tamper Token.

   commander security disabletamper --disable-param 0x00fa0000 --cert access_certificate.bin --cert-privkey cert_key.pem --device EFR32MG21B010F1024 --serialno 440030580

   Certificate written to Security Store:
   C:/Users/<username>/AppData/Local/SiliconLabs/commander/SecurityStore/device_000000000000000014b457fffe0f77ce/access_certificate.bin
   Cert key written to Security Store:
   C:/Users/<username>/AppData/Local/SiliconLabs/commander/SecurityStore/device_000000000000000014b457fffe0f77ce/cert_pubkey.pem
   Created unsigned disable tamper command
   Signed disable tamper command using
   C:/Users/<username>/AppData/Local/SiliconLabs/commander/SecurityStore/device_000000000000000014b457fffe0f77ce/cert_key.pem
   Tamper successfully disabled.
   Command disable tamper payload was stored in Security Store
   DONE

10. The Disable Tamper Token (aka Command disable tamper payload) file (tamper_payload_111110100000000000000000.bin, where 111110100000000000000000 is 0x00fa0000 for tamper disable mask) is stored in the Security Store. The location in Windows is C:\Users\<PC user name>\AppData\Local\SiliconLabs\commander\SecurityStore\device_<Serial number>\challenge_<Challenge value>.

    

    Users can also use the security getpath command to get the path of the Security Store or a specified device.

    commander security getpath

    C:/Users/<username>/AppData/Local/SiliconLabs/commander/SecurityStore
    DONE

    commander security getpath --deviceserialno 0000000000000000588e81fffe70350d

    C:/Users/<username>/AppData/Local/SiliconLabs/commander/SecurityStore/device_0000000000000000588e81fffe70350d
    DONE

11. The Disable Tamper Token and the device are now delivered to the Debug Party.

    Run the security gencommand command to create the Security Store to place the Disable Tamper Token file.

    commander security gencommand --action disable-tamper --disable-param 0x00fa0000 --device EFR32MG21B010F1024 --serialno 440030580

    Unsigned command file written to Security Store:
    C:/Users/<username>/AppData/Local/SiliconLabs/commander/SecurityStore/device_000000000000000014b457fffe0f77ce/challenge_8e7f73e6322edda06b62997155334f29/disable_tamper_command_to_be_signed09_08_2021.bin
    DONE

    Copy the Disable Tamper Token file (tamper_payload_111110100000000000000000.bin) from Product Company to the Windows Security Store challenge_<Challenge value> folder located in C:\Users\<PC username>\AppData\Local\SiliconLabs\commander\SecurityStore\device_<Serial number>\challenge_<Challenge value>.

12. The device compares the Disable Tamper Token contents with its internal serial number, challenge value, and Public Command Key to determine the token’s authenticity. If authentic, it will execute the disable tamper command to restore the default levels on the tamper disable mask (0xfa000000); otherwise, it will ignore the command.

    Run the security disabletamper command to disable the tamper.

    commander security disabletamper --disable-param 0x00fa0000 --device EFR32MG21B010F1024 --serialno 440030580

    Disabling tamper with tamper payload:
    C:/Users/<username>/AppData/Local/SiliconLabs/commander/SecurityStore/device_000000000000000014b457fffe0f77ce/challenge_8e7f73e6322edda06b62997155334f29/tamper_payload_111110100000000000000000.binTamper successfully disabled.
    DONE

    Note: Users can verify the Disable Tamper Token by following steps 4 to 6 in Tamper Disable if the EFR32xG21B device is running in the Normal mode of the SE Manager Tamper platform example.

13. The Debug Party can now use this same Disable Tamper Token to disable the tamper (step 12), over and over again after each power-on or pin reset, until they have finished debugging the device.

14. Once the Debug Party has finished debugging, they will send the device back to the Product Company.

15. Once the Product Company receives the device, they will immediately start a debug session to roll the challenge (from Challenge 1 to Challenge 2 in this example). Rolling the challenge will effectively invalidate any Disable Tamper Token that has been previously given to any third party.

    Run the security rollchallenge command and reset the device to invalidate the current Disable Tamper Token. The challenge cannot be rolled before it has been used at least once — that is, by running the security disabletamper or security unlock command.

    commander security rollchallenge --device EFR32MG21B010F1024 --serialno 440030580

    Challenge was rolled successfully.
    DONE

    The unlock token is invalidated after rolling the challenge because any previously issued Disable Tamper Token now contains a different challenge value (Challenge 1) than the challenge value currently in the device (Challenge 2).

    The validation process of any previously issued Disable Tamper Token will always fail until a new Disable Tamper Token is issued with a current matching challenge value (Challenge 2).

Note: Direct Customer can directly use the Private Command Key on the connected chip to generate the Disable Tamper Token in Security Store. But it has a high risk (cannot use HSM) to leak the Private Command Key to a party when using this approach.

commander security disabletamper --disable-param 0x00fa0000 --command-key command_key.pem 
--device EFR32MG21B010F1024 --serialno 440030580

Simplicity Studio#

1. Open Security Settings of the selected device as described in Using Simplicity Studio.

2. Click [Roll Challenge] to generate a new challenge value to invalidate the Disable Tamper Token for tamper disable. Click [OK] to exit.