Examples#

Overview#

The following table describes the examples for Series 2 Secure Boot.

Table: Series 2 Secure Boot Examples

Note: Unless specified in the example, these examples can be applied to other Series 2 devices.

Using Simplicity Commander#

1. This application note uses Simplicity Commander v1.12.0. The procedures and console output may be different for the other versions of Simplicity Commander. The latest version of Simplicity Commander can be downloaded from MCU Programming options.

   commander --version

   Simplicity Commander 1v12p0b1057
   JLink DLL version: 7.52d
   Qt 5.12.10 Copyright (C) 2017 The Qt Company Ltd.
   EMDLL Version: 0v17p19b0
   mbed TLS version: 2.16.6
   Emulator found with SN=440048205 USBAddr=0
   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 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 UG162: Simplicity Commander Reference Guide.

Using an External Tool#

The Secure Boot examples use the OpenSSL to sign the image files and certificates. The Windows version of OpenSSL can be downloaded from https://slproweb.com/products/Win32OpenSSL.html. 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.

Using a Platform Example#

Simplicity Studio 5 includes the SE Manager platform example for key provisioning and Secure Boot enabling. This application note uses platform example of GSDK v3.2.3. The console output may be different on other versions of the 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.

Generate Key and Signing#

This section describes how to generate a key to sign an image file or certificate for Secure Boot.

Using Simplicity Commander#

1. Run the util genkey command to generate the ECDSA-P256 Sign Key pair (sign_key.pem and sign_pubkey.pem) and Public Sign Key token file (sign_pubkey.txt). The Simplicity Commander can program the Public Sign Key in token file (sign_pubkey.txt) to the top page of the main flash.

   commander util genkey --type ecc-p256 --privkey sign_key.pem --pubkey sign_pubkey.pem
   --tokenfile sign_pubkey.txt

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

   Note: The same procedure can apply to generate the bootloader certificate and application certificate key pairs for Certificate-Based Secure Boot.

2. Use the convert command with the Private Key (like sign_key.pem) from step 1 to sign an image file or certificate. Refer to Signing for ECDSA-P256-SHA256 Secure Boot and Signing for Certificate-Based Secure Boot for more information about the Simplicity Commander signing process.

Using an HSM and Simplicity Commander#

1. The user can use HSM to generate the ECDSA-P256 Sign Key pair. The Private Sign Key is securely held in HSM and the Public Sign Key can be exported in a specific format (like sign_pubkey.pem).

   Note: The same procedure can apply to generate the bootloader certificate and application certificate key pairs for Certificate-Based Secure Boot.

2. Use the util keytotoken command to convert the Public Sign Key from step 1 to token format (sign_pubkey.txt). The Simplicity Commander can program the Public Sign Key in token file (sign_pubkey.txt) to the top page of the main flash.

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

   Writing EC tokens to sign_pubkey.txt...
   DONE

3. Use the convert command with --extsign option to prepare an unsigned image or certificate for HSM.

4. Use the Private Key from step 1 to generate a signature for the unsigned image or certificate from step 3.

5. Use the convert command with the signature from step 4 to generate a signed image or certificate. Refer to Signing for ECDSA-P256-SHA256 Secure Boot and Signing for Certificate-Based Secure Boot for more information about the HSM and Simplicity Commander signing process.

Note: The Simplicity Commander v1.11.0 or above supports signature in DER format. The older version of Simplicity Commander can only handle signatures in Raw format.

Provision Public Sign Key and Secure Boot Enabling#

The Public Sign Key in SE OTP is used to verify the host image signature or certificate during Secure Boot. The user should provision this key before setting the Secure Boot enabled flag in SE OTP. On HSE-SVH devices, the user requires to provision the anti-tamper protection configuration with Secure Boot settings.

If the user sets the SECURE_BOOT_ANTI_ROLLBACK option with Secure Boot, the SE will store the version counter (4 bytes) for anti-rollback of GBL (SSB) to SE flash and check the bootloader version during an upgrade and on every boot. The version counter will not roll to 0 if it reaches the maximum value (bootloader cannot upgrade anymore). The anti-rollback does not prevent flashing an older signed GBL hex image to the device.

The following table describes the anti-rollback protection on signed GBL when SECURE_BOOT_ANTI_ROLLBACK is enabled or disabled.

• The GBL handles the anti-rollback protection when upgrading the GBL through the GBL upgrade image file (.gbl).

• The SE handles the anti-rollback protection (if SECURE_BOOT_ANTI_ROLLBACK enabled) when booting the GBL.

Note: It needs to execute a mass erase (commander device masserase or commander security erasedevice then reset) before flashing a GBL hex image (.s37) to the device if SECURE_BOOT_PAGE_LOCK_NARROW or SECURE_BOOT_PAGE_LOCK_FULL option in SE OTP is enabled.

For simplicity, the Secure Boot examples in this application note do not enable the following options for Secure Boot.

• SECURE_BOOT_PAGE_LOCK_NARROW

• SECURE_BOOT_PAGE_LOCK_FULL

Simplicity Commander#

The following procedures assume the required files are in the same folder.

1. Follow the procedures in Generate Key and Signing to generate the ECDSA-P256 Sign Key pair (sign_key.pem and sign_pubkey.pem) and Public Sign Key token file (sign_pubkey.txt).

2. Run the security writekey command to provision the Public Sign Key (sign_pubkey.pem). The Public Sign Key cannot be changed once written.

   commander security writekey --sign sign_pubkey.pem --device EFR32MG21A010F1024 --serialno 440048205

   Device has serial number 000000000000000014b457fffe045b21
   ================================================================================
   Please look through any warnings before proceeding.
   THIS IS A ONE-TIME command, all code to be run on the device must be signed by this key.
   Type 'continue' and hit enter to proceed or Ctrl-C to abort:
   ================================================================================
   continue
   DONE

3. Run the security readkey command to verify the Public Sign Key with the Public Sign Key in the token file (sign_pubkey.txt).

   commander security readkey --sign --device EFR32MG21A010F1024 --serialno 440048205

   C4AF4AC69AAB9512DB50F7A26AE5B4801183D85417E729A56DA974F4E08A562C
   DE6019DEA9411332DC1A743372D170B436238A34597C410EA177024DE20FC819
   DONE

4. For Series 2VSE devices (like EFR32MG22C224F512IM40), run the flash command to program the Public Sign Key in the token file (sign_pubkey.txt) to the top page of the main flash for ECDSA-P256-SHA256 Secure Boot. It is optional on Series 2HSE devices.

   commander flash --tokengroup znet --tokenfile sign_pubkey.txt --device EFR32MG22C224F512IM40 --serialno 440048205

   Writing 8192 bytes starting at address 0x0007e000
   Comparing range 0x0007E000 - 0x0007FFFF (8 KiB)
   Programming range 0x0007E000 - 0x0007FFFF (8 KiB)
   DONE

   Note: The MCU Series 2 devices (like EFM32PG22C200F512IM40) require Simplicity Commander Version 1.12.2 or above to support the flash --tokengroup znet command.

5. Run the security genconfig command to generate the user_configuration.json file for secure boot.

   commander security genconfig --nostore --outfile user_configuration.json --device EFR32MG21A010F1024
   --serialno 440048205
   DONE

   Name	Description
   SECURE_BOOT_ENABLE	If set, verifies the host image on the Cortex-M33 before releasing the Cortex-M33 from reset.
   SECURE_BOOT_VERIFY_CERTIFICATE	If set, requires certificate-based signing of the host image.
   SECURE_BOOT_ANTI_ROLLBACK	If set, prevents secure upgrading to a host image with a lower version than the image that is currently stored in flash.
   SECURE_BOOT_PAGE_LOCK_NARROW	If set, locks flash pages that have been validated by the Secure Boot process to prevent re-flashing by other means than through the SE. Write/erase locks pages from 0 through the page where the Secure Boot host image signature is located, not including the last page if the signature is not on a page boundary.
   SECURE_BOOT_PAGE_LOCK_FULL	If set, locks flash pages that have been validated by the Secure Boot process to prevent re-flashing by other means than through the SE. Write/erase locks pages from 0 through the page where the Secure Boot host image signature is located, including the last page if the signature is not on a page boundary.

   Note: The host image is the firmware in the device's flash starting address. It is usually the GBL.

6. Use a text editor to modify the default secure boot settings to the desired configurations used in this application note.

   

   Note: If SECURE_BOOT_ENABLE is false, the SE will ignore the other four options regardless they are true or false. The EFR32xG23 and future Series 2 devices do not allow this setting to program to the SE OTP.

7. Follow the procedure in Signing for ECDSA-P256-SHA256 Secure Boot to flash a bootloader image for signature based secure boot.

   OR

   Follow the procedure in Signing for Certificate-Based Secure Boot to flash a bootloader image for certificate based secure boot

8. Run the security writeconfig command to program the secure boot configuration to the SE OTP. The user can execute this command once per device.

   commander security writeconfig --configfile user_configuration.json --device EFR32MG21A010F1024
   --serialno 440048205

   ================================================================================
   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

9. Run the security readconfig command to check the secure boot configuration of the device.

commander security readconfig --serialno 440048205

SE Manager Key Provisioning Platform Example#

Click the View Project Documentation link to open the readme file.

1. Modify the default Public Sign Key in public_sign_key[PUB_KEY_SIZE] array in app_process.c to the desired values.

   /// Public sign key
   SL_ALIGN(4) static const uint8_t public_sign_key[PUB_KEY_SIZE] = {
     0xc4, 0xaf, 0x4a, 0xc6, 0x9a, 0xab, 0x95, 0x12,
     0xdb, 0x50, 0xf7, 0xa2, 0x6a, 0xe5, 0xb4, 0x80,
     0x11, 0x83, 0xd8, 0x54, 0x17, 0xe7, 0x29, 0xa5,
     0x6d, 0xa9, 0x74, 0xf4, 0xe0, 0x8a, 0x56, 0x2c,
     0xde, 0x60, 0x19, 0xde, 0xa9, 0x41, 0x13, 0x32,
     0xdc, 0x1a, 0x74, 0x33, 0x72, 0xd1, 0x70, 0xb4,
     0x36, 0x23, 0x8a, 0x34, 0x59, 0x7c, 0x41, 0x0e,
     0xa1, 0x77, 0x02, 0x4d, 0xe2, 0x0f, 0xc8, 0x19
   };

2. Modify the default secure boot settings in init_se_otp_conf() function in app_se_manager_key_provisioning.c to the desired configuration.

     // Overwrite secure boot options in SL_SE_OTP_INIT_DEFAULT if necessary.
     otp_init.enable_secure_boot = true;
     otp_init.verify_secure_boot_certificate = false;
     otp_init.enable_anti_rollback = true;
     otp_init.secure_boot_page_lock_narrow = false;
     otp_init.secure_boot_page_lock_full = false;

   Note: If enable_secure_boot is false, the SE will ignore the other four options regardless of whether they are true or false. The EFR32xG23 and future Series 2 devices do not allow this setting to program to the SE OTP.

3. Follow the procedures in Generate an Unsigned Application Image to generate the unsigned application image if the GBL is present in the device.

4. Build the project and run the application. Follow the procedures in Signing for ECDSA-P256-SHA256 Secure Boot or Signing for Certificate-Based Secure Boot if a signed application image is required.

5. Then press SPACE to skip the programming of the AES-128 key (HSE devices only). Optional to press ENTER to program the hard-coded GBL Decryption Key to HSE OTP.

   SE Manager Key Provisioning Example - Core running at 38000 kHz.
     . SE manager initialization... SL_STATUS_OK (cycles: 9 time: 0 us)
     . Get current SE firmware version... SL_STATUS_OK (cycles: 3578 time: 94 us)
     + Current SE firmware version (MSB..LSB): 00010209
     . Read SE OTP configuration... SL_STATUS_COMMAND_IS_INVALID (cycles: 3908 time: 102 us)
     . Press ENTER to program 128-bit AES key in SE OTP or press SPACE to skip.
     . Encrypt 16 bytes plaintext with 128-bit AES OTP key... SL_STATUS_FAIL (cycles: 4627 time: 121 us)
     . Press ENTER to program public sign key in SE OTP or press SPACE to skip.

6. Press ENTER to program the hard-coded Public Sign Key to SE OTP.

     + Warning: The public sign key in SE OTP cannot be changed once written!
     + Press ENTER to confirm or press SPACE to skip if you are not sure.

7. Press ENTER to confirm the operation. The SE returns SL_STATUS_INVALID_PARAMETER if the Public Sign Key is present in SE OTP.

     . Initialize public sign key... SL_STATUS_OK (cycles: 56052 time: 1475 us)
     . Get public sign key... SL_STATUS_OK (cycles: 8450 time: 222 us)
     + The public sign key (64 bytes):
       C4 AF 4A C6 9A AB 95 12 DB 50 F7 A2 6A E5 B4 80
       11 83 D8 54 17 E7 29 A5 6D A9 74 F4 E0 8A 56 2C
       DE 60 19 DE A9 41 13 32 DC 1A 74 33 72 D1 70 B4
       36 23 8A 34 59 7C 41 0E A1 77 02 4D E2 0F C8 19
     . Press ENTER to program public command key in SE OTP or press SPACE to skip.

     . Initialize public sign key... SL_STATUS_INVALID_PARAMETER (cycles: 4375 time: 115 us)
     . Get public sign key... SL_STATUS_OK (cycles: 8435 time: 221 us)
     + The public sign key (64 bytes):
       C4 AF 4A C6 9A AB 95 12 DB 50 F7 A2 6A E5 B4 80
       11 83 D8 54 17 E7 29 A5 6D A9 74 F4 E0 8A 56 2C
       DE 60 19 DE A9 41 13 32 DC 1A 74 33 72 D1 70 B4
       36 23 8A 34 59 7C 41 0E A1 77 02 4D E2 0F C8 19
     . Press ENTER to program public command key in SE OTP or press SPACE to skip.

8. Press SPACE to skip the programming of the Public Command Key. Optional to press ENTER to program the hard-coded Public Command Key to SE OTP.

     . Get public command key... SL_STATUS_FAIL (cycles: 4126 time: 108 us)
     . Press ENTER to initialize SE OTP for secure boot configuration or press SPACE to skip.

9. Press ENTER to program the secure boot configuration.

     + Warning: The SE OTP configuration cannot be changed once written!
     + Press ENTER to confirm or press SPACE to skip if you are not sure.

10. Press ENTER to confirm the operation. The SE returns SL_STATUS_COMMAND_IS_INVALID if an invalid setting from step 2 or the secure boot configuration has been programmed in SE OTP.

      . Initialize SE OTP... SL_STATUS_OK (cycles: 267256 time: 7033 us)
      + Read SE OTP configuration... SL_STATUS_OK (cycles: 6865 time: 180 us)
      + Secure boot                    : Enabled
      + Secure boot verify certificate : Disabled
      + Secure boot anti-rollback      : Enabled
      + Secure boot page lock narrow   : Disabled
      + Secure boot page lock full     : Disabled
      . SE manager deinitialization... SL_STATUS_OK (cycles: 5 time: 0 us)

      . Initialize SE OTP... SL_STATUS_COMMAND_IS_INVALID (cycles: 3989 time: 104 us)
      . SE manager deinitialization... SL_STATUS_OK (cycles: 5 time: 0 us)

Simplicity Studio#

The security operations are performed in the Security Settings of Simplicity Studio. This application note uses Simplicity Studio v5.2.3.1. The procedures and pictures may be different for the other versions 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.

3. Click [Start Provisioning Wizard…] in the upper right corner to display the Secure Initialization dialog box. Checking the Enable Version Rollback Prevention of Host Image option is recommended. The Verify intermediate certificate before secure boot option is for Certificate-based Secure Boot.

   

   Note: The SECURE_BOOT_PAGE_LOCK_NARROW and SECURE_BOOT_PAGE_LOCK_FULL options are not yet available in Simplicity Studio.

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

   

5. Checking the Enable Writing Sign Key checkbox will automatically enable Secure Boot. The following Secure Boot Warning is displayed. Click [Yes] to confirm.

   

6. Open the Public Sign Key token file (sign_pubkey.txt).

   MFG_SIGNED_BOOTLOADER_KEY_X : 997011ED1708580BD4A6B7F8AD6EE19B0B8722611FB76A3A5702D5141180E101
   MFG_SIGNED_BOOTLOADER_KEY_Y : 0AC8673C8ACC26EE2B534C004F4A4B7EBBC23D04506DD66E3EF0DDC81E3CA55E

7. Copy Public Sign Key (X-point 9970... first, then Y-point 0AC8...) to Key: box under Sign Key:.

   

8. Click [Next >]. The Secure Locks dialog box is displayed. When Secure Boot is enabled, the Debug Locks are not set by default. Refer to Series 2 Secure Debug for more information about these locks.

   

9. Click [Next >] to display the Summary dialog box.

   

10. If the information displayed is correct, click [Provision]. Click [Yes] to confirm. The Public Sign Key and Secure Boot configuration cannot be changed once written.

    

11. The Summary dialog box displays the Provisioning Status.

    

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

Provision GBL Decryption Key#

The GBL Decryption Key is used to decrypt the GBL upgrade image file payloads during firmware upgrade. The user should provision this key before enabling the Require encrypted firmware upgrade files option in AppBuilder or Bootloader-core Software Component.

The following figure and table describe two (VSE) or three (HSE) options to select which GBL Decryption Key for GBL upgrade image file (bootloader, SE, or application) decryption.

Note:

• Option 2 requires ApplicationProperties_t struct v1.2 or higher (defined in application_properties.h in the Windows folder C:\Users\<PC USER NAME>\SimplicityStudio\SDKs\gecko_sdk\platform\bootloader\api) in GSDK v4.1 or higher to store the GBL Decryption Key.

/// Major version number of the AppliationProperties_t struct
#define APPLICATION_PROPERTIES_VERSION_MAJOR (1UL)
/// Minor version number of the AppliationProperties_t struct
#define APPLICATION_PROPERTIES_VERSION_MINOR (2UL)

/// Application Properties struct
typedef struct {
  /// @brief Magic value indicating this is an ApplicationProperties_t struct.
  /// Must equal @ref APPLICATION_PROPERTIES_MAGIC
  uint8_t magic[16];
  /// Version number of this struct
  uint32_t structVersion;
  /// Type of signature this application is signed with
  uint32_t signatureType;
  /// Location of the signature. Typically points to the end of the application
  uint32_t signatureLocation;
  /// Information about the application
  ApplicationData_t app;
  /// Pointer to information about the certificate
  ApplicationCertificate_t *cert;
  /// Pointer to Long Token Data Section
  uint8_t *longTokenSectionAddress;
  /// Parser Decryption Key
  const uint8_t decryptKey[16];
} ApplicationProperties_t;

• Option 2 must be implemented before signing the GBL image for ECDSA-P256-SHA256 or certificate-basedSecure Boot.

• The options for the GBL Decryption Key are mutually exclusive. Either one of the two (VSE) or three (HSE) key storages will be selected for decryption.

• From a security point of view, it is highly recommended to use or upgrade to option 1 for HSE devices and option 2 for VSE devices.

• If the GBL Decryption Key in the selected option is compromised, the simple way is to upgrade the GBL to option 2 (if the existing option is 1 or 3) with the new GBL Decryption Key.

Simplicity Commander#

The following procedures describe how to program the GBL Decryption Key for the options below. All procedures assume the required files are in the same folder.

• Use symmetric key stored in Secure Element storage (HSE devices only and GSDK ≥ v3.0)

• Use symmetric key stored in Application Properties Struct (GSDK ≥ v4.1)

• Default Storage on the Top Page of the Main Flash

1. Generate a 128-bit Symmetric Key

   Run the util genkey to generate the token file for the GBL Decryption Key.

   commander util genkey --type aes-ccm --outfile aes_key.txt

   Using Windows' Cryptographic random number generator
   DONE

   The aes_key.txt contains the randomly generated AES-128 key. Use the text editor to replace the randomly generated key in aes_key.txt with the desired GBL Decryption Key as below.

   # Key randomly generated by 'util genkey'
   TOKEN_MFG_SECURE_BOOTLOADER_KEY: 81A5E21FA15286F1DF445C2CC120FA3F

2. (Use symmetric key stored in Secure Element storage) Run the security writekey to provision the GBL Decryption Key. The GBL Decryption Key cannot be changed once written.

   commander security writekey --decrypt aes_key.txt --device EFR32MG21A010F1024 --serialno 440030580

   Device has serial number 0000000000000000000d6ffffead3d94
   ================================================================================
   Please look through any warnings before proceeding.
   THIS IS A ONE-TIME command, any encrypting of GBL files must be done with this key.
   Type 'continue' and hit enter to proceed or Ctrl-C to abort:
   ================================================================================
   continue
   DONE

   Note: It cannot read back the GBL Decryption Key from the HSE OTP.

3. (Use symmetric key stored in Application Properties Struct) Run the convert command to program the GBL Decryption Key to the Application Properties Struct of the GBL.

   commander convert bootloader-uart-xmodem.s37 --aeskey aes_key.txt --outfile bootloader-uart-xmodem.s37

   Parsing file bootloader-uart-xmodem.s37...
   Writing to bootloader-uart-xmodem.s37...
   Overwriting file: bootloader-uart-xmodem.s37...
   DONE

   Note:

   • The --aeskey option in the convert command requires Simplicity Commander v1.12.3 or above.

   • The GBL Decryption Key can only be added to the GBL with Application Properties Struct v1.2 or higher.

4. (Default Storage on the Top Page of the Main Flash) Run the flash command to program the GBL Decryption Key in the token file to the top page of the main flash.

   commander flash --tokengroup znet --tokenfile aes_key.txt --device EFR32MG21A010F1024 --serialno 440030580

   Writing 8192 bytes starting at address 0x000fe000
   Comparing range 0x000FE000 - 0x000FFFFF (8 KB)
   Programming range 0x000FE000 - 0x000FFFFF (8 KB)
   DONE

   Note: The MCU Series 2VSE devices (like EFM32PG22C200F512IM40) require Simplicity Commander Version 1.12.2 or above to support the flash --tokengroup znet command.

SE Manager Key Provisioning Platform Example#

This example only applies to option 1 for HSE devices. Click the View Project Documentation link to open the readme file.

1. Modify the default GBL Decryption Key in aes_key[16] array in app_process.c to the desired values.

   /// 128-bit AES key
   SL_ALIGN(4) static const uint8_t aes_key[16] = {
     0x81, 0xa5, 0xe2, 0x1f, 0xa1, 0x52, 0x86, 0xf1,
     0xdf, 0x44, 0x5c, 0x2c, 0xc1, 0x20, 0xfa, 0x3f
   };

2. Modify the ciphertext[16] array in app_process.c to the expected ciphertext for AES ECB on 16 bytes zero plaintext to verify the GBL Decryption Key in step 1.

   /// Ciphertext to verify 128-bit AES key
   static const uint8_t ciphertext[16] = {
     0x66, 0xd2, 0x0f, 0x99, 0x65, 0x3e, 0xa8, 0xd0,
     0x83, 0x05, 0xa6, 0x39, 0xd4, 0x4e, 0x98, 0xa6
   };

3. Follow the procedures in Generate an Unsigned Application Image to generate the unsigned application image if the GBL is present in the device.

4. Build the project and run the application. Follow the procedures in Signing for ECDSA-P256-SHA256 Secure Boot or Signing for Certificate-Based Secure Boot if a signed application image is required.

5. Then press ENTER to program the hard-coded GBL Decryption Key to HSE OTP.

   SE Manager Key Provisioning Example - Core running at 38000 kHz.
     . SE manager initialization... SL_STATUS_OK (cycles: 9 time: 0 us)
     . Get current SE firmware version... SL_STATUS_OK (cycles: 3578 time: 94 us)
     + Current SE firmware version (MSB..LSB): 00010209
     . Read SE OTP configuration... SL_STATUS_COMMAND_IS_INVALID (cycles: 3908 time: 102 us)
     . Press ENTER to program 128-bit AES key in SE OTP or press SPACE to skip.
     + Warning: The 128-bit AES key in SE OTP cannot be changed once written!
     + Press ENTER to confirm or press SPACE to skip if you are not sure.
   

6. Press ENTER to confirm the operation. The program either returns SL_STATUS_OK or SL_STATUS_INVALID_PARAMETER (already present) and performs AES ECB encryption to verify the GBL Decryption Key in HSE OTP.

     . Initialize 128-bit AES key... SL_STATUS_OK (cycles: 39059 time: 1027 us)
     . Encrypt 16 bytes plaintext with 128-bit AES OTP key... SL_STATUS_OK (cycles: 11013 time: 289 us)
     + Compare encrypted message with expected ciphertext... OK
     . Press ENTER to program public sign key in SE OTP or press SPACE to skip.

     . Initialize 128-bit AES key... SL_STATUS_INVALID_PARAMETER (cycles: 4474 time: 117 us)
     . Encrypt 16 bytes plaintext with 128-bit AES OTP key... SL_STATUS_OK (cycles: 11001 time: 289 us)
     + Compare encrypted message with expected ciphertext... OK
     . Press ENTER to program public sign key in SE OTP or press SPACE to skip.

7. Press SPACE to skip the programming of the Public Sign Key.

     . Get public sign key... SL_STATUS_FAIL (cycles: 4126 time: 108 us)
     . Press ENTER to program public command key in SE OTP or press SPACE to skip.

8. Press SPACE to skip the programming of the Public Command Key.

     . Get public command key... SL_STATUS_FAIL (cycles: 4126 time: 108 us)
     . Press ENTER to initialize SE OTP for secure boot configuration or press SPACE to skip.

9. Press SPACE to skip the programming of the secure boot configuration.

     . SE manager deinitialization... SL_STATUS_OK (cycles: 10 time: 0 us)

Secure Boot#

The user should usually not enable the Secure Boot during the development phase to avoid a clash on debugging. The Secure Boot feature is enabled near firmware release and uses the following sections to validate the configuration and system functionality.

Generate an Unsigned GBL Image#

There are two ways to configure the application firmware through a GBL project.

1. Use AppBuilder (.iscfile) in GSDK v3.2 and lower.

2. Use Bootloader-core software component (.slcpfile) in GSDK v4.0 and higher.

The following notes apply to the AppBuilder and Bootloader-core software component.

• Enabling the Allow use of public key from manufacturing token storage option is mandatory on VSE devices (cannot be disabled in AppBuilder and is discarded in Bootloader-core software component) for ECDSA-P256-SHA256 Secure Boot. The HSE device ignores this default enabled option if the Public Sign Key has been provisioned in OTP.

• The GBL stores the application version counter at the end of the bootloader flash space if Enable application rollback protection option (GSDK ≥ v3.0) is enabled. The GBL checks the application version during an upgrade and on every boot. The anti-rollback does not prevent flashing an older application image to the device.

• The Minimum application version allowed option (GSDK ≥ v3.0) configures the minimum application version that should be allowed to boot. This option maintains the application version counter that will reset to 0 after upgrading the GBL.

• The Enable application rollback protection option is not applicable if the SECURE_BOOT_PAGE_LOCK_FULL in SE OTP is enabled. See section "Secure Boot with Application Rollback Protection" in UG266 (for GSDK v3.2 and lower) or Silicon Labs Gecko Bootloader User's Guide for GSDK 4.0 and Higher (for GSDK v4.0 and higher) for details about the application rollback protection.

• The GBL size and starting address are device-dependent. For more information about the bootloader size and starting address on Series 2 devices, see section "Memory Space For Bootloading" in UG103.6: Bootloader Fundamentals.

Refer to Generate a GBL Upgrade Image File for the Require signed firmware upgrade files and Require encrypted firmware upgrade files options on the GBL upgrade image file. For simplicity, the Secure Boot examples in this application note do not enable these options. Refer to UG266/Silicon Labs Gecko Bootloader User's Guide for GSDK 4.0 and Higher for information about these options.

The following sections describe how to build the unsigned GBL image from the UART XMODEM Bootloader (GSDK < v4.1) or Bootloader - NCP UART XMODEM (GSDK ≥ v4.1).

AppBuilder#

This application note uses UART XMODEM Bootloader example v1.12.0 in GSDK v3.2.3. The procedures and pictures may be different for the other versions of this example.

1. Create a UART XMODEM Bootloader project.

2. The Plugins tab in AppBuilder (bootloader-uart-xmodem.isc) shows the default configurations for the UART XMODEM Bootloader example.

3. Use Bootloader Core, provides API: core in the Plugins tab to set up the application firmware configurations.

   1. This application note uses the configuration below for ECDSA-P256-SHA256 Secure Boot.

      

   2. This application note uses the configuration below for Certificate-based Secure Boot.

      

4. Enter a higher version number (default is 0) to the macro BOOTLOADER_VERSION_MAIN_CUSTOMER → Value in the Additional Macros field on the Other tab for anti-rollback protection of GBL.

   

5. The default setting of GBL will overwrite the existing application image when upgrading the GBL or SE. It forces to update the application image even without changes on the firmware. Use the Appbuilder settings below to keep the existing application image when upgrading the GBL or SE.

   1. Enter the required application image size to the macro BTL_APP_SPACE_SIZE → Value in the Additional Macros field on the Other tab. Check the -D? checkbox to add this definition to the project.

      This application note uses 507904 (496 kB) to replace the default value of ((FLASH_BASE + FLASH_SIZE) - BTL_APPLICATION_BASE).

      

   2. The Base address of bootloader upgrade image ≥ (BTL_APP_SPACE_SIZE + size of the GBL).

      The example in this application note uses EFR32MG21A010F1024:

      Base address of bootloader upgrade image = 507904 (496 kB) + 16384 (16 kB for GBL) = 524288 (512 kB)

      

      Note: The default value of Base address of bootloader upgrade image is 32768 (32 kB).

   3. The (Base address of bootloader upgrade image + size of the GBL or SE + upgrade file overhead) ≤ the available size of the device main flash for application use (see project linker file for details).

   The example in this application note uses EFR32MG21A010F1024:

   512 kB (Base address of bootloader upgrade image) + 16 kB (GBL) or 48 kB (SE) + overhead bytes < 1024 kB (size of main flash)

   For more information about the size of the GBL and SE, see section "Storage Space Size Configuration" in UG266.

   Note: It requires GBL v1.11.0 or above to support this feature.

6. Click [Generate] in the right upper corner.

7. In the Generation Successful dialog, click [OK].

8. Build the project to generate the unsigned GBL image file (bootloader-uart-xmodem.s37).

9. (Optional) Run the util appinfo command to check all available information (application properties) in an unsigned GBL image. The App version is the GBL version for the SECURE_BOOT_ANTI_ROLLBACK option.

   commander util appinfo bootloader-uart-xmodem.s37

   Parsing file bootloader-uart-xmodem.s37...
   Found application properties in image.
   Application properties info:
   Application properties location : 0x00002b1c
   Signature location              : 0x00002d08Signature type                  : No signature
   Long token section address      : Not set (0x00000000)
   Application data info:
   For Series 2 devices: If rollback prevention is enabled in the OTP configuration, the device will not boot if the device has seen an application with a higher version number.
   App type                        : Bootloader (APPLICATION_TYPE_BOOTLOADER)App version                     : 0x010c0000
   Product ID                      : Not set (0x00000000000000000000000000000000)
   No certificate found in image.
   For Series 2 devices: If the configuration flag SECURE_BOOT_VERIFY_CERTIFICATE is set or a device has previously seen certificate based signing, it will not accept direct signing.
   DONE

Bootloader-core Software Component#

This application note uses UART XMODEM Bootloader example v2.0.0 in GSDK v4.0. The procedures and pictures may be different for the other versions of this example.

1. Create a UART XMODEM Bootloader project.

2. Checking the Installed Components under the SOFTWARE COMPONENTS tab shows the list of installed components (bootloader-uart-xmodem.slcp) in the UART XMODEM Bootloader example.

3. Click [Configure] in the Bootloader-core component to open the Bootloader Core Configuration.

   

4. Use Bootloader Core Configuration in Bootloader-core to set up the application firmware configurations.

   1. This application note uses the configuration below for ECDSA-P256-SHA256 Secure Boot.

      

   2. This application note uses the configuration below for Certificate-based Secure Boot.

      

5. Enter a higher version number (default is 0) to BOOTLOADER VERSION MAIN CUSTOMER for anti-rollback protection of GBL.

6. The default setting of GBL will overwrite the existing application image when upgrading the GBL or SE. It forces to update the application image even without changes on the firmware. Use the Bootloader-core settings below to keep the existing application image when upgrading the GBL or SE.

   1. Enter the required application image size to the Enter Bootloader App Space Size dialog box after enabling the Use custom Bootloader Application Size option.

      This application note uses 507904 (496 kB) to replace the default value of 0.

      

   2. The Base address of bootloader upgrade image ≥ (Enter Bootloader App Space Size + size of the GBL).

      The example in this application note uses EFR32MG21A010F1024:

      Base address of bootloader upgrade image = 507904 (496 kB) + 16384 (16 kB for GBL) = 524288 (512 kB)

      

      Note: The default value of Base address of bootloader upgrade image is 32768 (32 kB).

   3. The (Base address of bootloader upgrade image + size of the GBL or SE + upgrade file overhead) ≤ the available size of the device main flash for application use (see project linker file for details).

   The example in this application note uses EFR32MG21A010F1024:

   512 kB (Base address of bootloader upgrade image) + 16 kB (GBL) or 48 kB (SE) + overhead bytes < 1024 kB (size of main flash)

   For more information about the size of the GBL and SE, see section Storage Space Size Configuration in Silicon Labs Gecko Bootloader User's Guide for GSDK 4.0 and Higher.

7. Click [X] in the right upper corner to exit the Bootloader Core Configuration.

8. Build the project to generate the unsigned GBL image file (bootloader-uart-xmodem.s37).

9. (Optional) Run the convert command to program the GBL Decryption Key to the Application Properties Struct if this GBL Decryption Key option in GBL (GSDK ≥ v4.1) is selected.

   commander convert bootloader-uart-xmodem.s37 --aeskey aes_key.txt --outfile bootloader-uart-xmodem.s37

   Parsing file bootloader-uart-xmodem.s37...
   Writing to bootloader-uart-xmodem.s37...
   Overwriting file: bootloader-uart-xmodem.s37...
   DONE

10. (Optional) Run the util appinfo command to check all available information (application properties) in an unsigned GBL image. The App version is the GBL version for the SECURE_BOOT_ANTI_ROLLBACK option.

    commander util appinfo bootloader-uart-xmodem.s37

    Parsing file bootloader-uart-xmodem.s37...
    Found application properties in image.
    Application properties info:
    Application properties location : 0x00002b30
    Signature location              : 0x00002c44Signature type                  : No signature
    Long token section address      : Not set (0x00000000)
    Application data info:
    For Series 2 devices: If rollback prevention is enabled in the OTP configuration, the device will not boot if the device has seen an application with a higher version number.
    App type                        : Bootloader (APPLICATION_TYPE_BOOTLOADER)App version                     : 0x02000000
    Product ID                      : Not set (0x00000000000000000000000000000000)
    No certificate found in image.
    For Series 2 devices: If the configuration flag SECURE_BOOT_VERIFY_CERTIFICATE is set or a device has previously seen certificate based signing, it will not accept direct signing.
    DONE

    Note: For the TrustZone-aware bootloaders, the unsigned GBL image is the combined image of Secure and Non-secure bootloaders. The Bootloader-core component is installed in the Secure bootloader.

Generate an Unsigned Application Image#

This section describes how to generate an unsigned application image for the GBL.

1. For Series 2 devices, the application image should place on the main flash page after the GBL. For more information about the application starting address, see section "Memory Space For Bootloading" in UG103.6: Bootloader Fundamentals.

2. (Simplicity Studio 4) Refer to the section "Creating Applications for Use with the Bootloader" in AN0042: USB/UART Bootloader or the Knowledge Article (Simplicity IDE) in Silicon Labs Community to set up the application image start address.

3. (Simplicity Studio 5) The user can use the Bootloader Application Interface component to set up the start address of the application image. This application note uses Platform - Blink Bare-metal example in GSDK v3.2.3. The procedures and pictures may be different on other versions of the GSDK. The following steps can apply to other platform examples in GSDK.

   1. Create a Platform - Blink Bare-metal project.

   2. The Software Components tab shows the list of available components (blink_bardmetal.slcp) that the user can install in the project.

   3. Select Platform → Bootloader → Bootloader Application Interface.

   4. Click [Install].

   

   Note: For the wireless protocol stack example, the Bootloader Application Interface component is already present in the project.

4. The application image should contain an ApplicationProperties_t struct (defined in application_properties.h in the Windows folder below) declaring the application version, capabilities, and other metadata.

   For GSDK v3.2 and lower: C:\SiliconLabs\SimplicityStudio\v5\developer\sdks\gecko_sdk_suite\<GSDK VERSION>\platform\bootloader\api

   For GSDK v4.0 and higher: C:\Users\<PC USER NAME>\SimplicityStudio\SDKs\gecko_sdk\platform\bootloader\api

   Below is an example source file app_properties.c with ApplicationProperties_t struct for Secure Boot on GSDK v3.2 and lower.

   #include <stddef.h>
   #include "application_properties.h"
   const ApplicationProperties_t sl_app_properties = {
   .magic = APPLICATION_PROPERTIES_MAGIC,
   .structVersion = APPLICATION_PROPERTIES_VERSION,
   .signatureType = APPLICATION_SIGNATURE_NONE,.signatureLocation = 0,
   .app = {
     .type = APPLICATION_TYPE_MCU,
     .version = 1UL,
     .capabilities = 0UL,
     .productId = {0U},
   },
   };

   The signatureType and signatureLocation are filled by Simplicity Commander when signing the application image using the convertcommand.

5. The following table describes how to add the app_properties.c file in step 4 to Platform - Blink Bare-metal project. For the wireless protocol stack example, the app_properties.c file with ApplicationProperties_t struct is already present in the project.

   Simplicity Studio 4 & Simplicity Studio 5 with GSDK v3.2 and lower	Simplicity Studio 5 with GSDK v4.0 and higher
   Manually added	Automatically added after installing the Bootloader Application Interface component in step 3 to the project.

   Note: Refer to the Knowledge Article in Silicon Labs Community to add app_properties.c to the project in Simplicity Studio 4.

6. (Simplicity Studio 4 & Simplicity Studio 5 with GSDK v3.2 and lower) Enter a higher version number to .version in app_properties.c for anti-rollback protection (if enabled) of the application.

7. (Simplicity Studio 5 with GSDK v4.0 and higher) Click [Configure] in the App Properties component under Platform → Bootloader to open the App Properties configuration. The example below uses GSDK v4.0. The procedures and pictures may be different on other versions of the GSDK.

   

   Enter a higher version number to Version number for this application dialog box in App Properties settings for anti-rollback protection (if enabled) of the application.

   

   Note: The app_properties.c is in the Windows folder below.

   C:\Users\<PC USER NAME>\SimplicityStudio\SDKs\gecko_sdk\platform\bootloader\app_properties

8. Build the project to generate the unsigned application image file (blink_bardmetal.s37).

9. (Optional) Run the util appinfocommand to check all available information about ApplicationProperties_t struct in an unsigned application image. The App version is for the Enable application rollback protection option in the AppBuilder or Bootloader-core software component.

   commander util appinfo blink_baremetal.s37

   Parsing file blink_baremetal.s37...
   Found application properties in image.
   Application properties info:
   Application properties location : 0x00006198
   Signature location              : Not set (0x00000000)Signature type                  : No signature
   Long token section address      : Not set (0x00000000)
   Application data info:
   For Series 2 devices: If rollback prevention is enabled in the OTP configuration, the device will not boot if the device has seen an application with a higher version number.
   App type                        : MCU application (APPLICATION_TYPE_MCU)App version                     : 0x00000001
   Product ID                      : Not set (0x00000000000000000000000000000000)
   No certificate found in image.
   For Series 2 devices: If the configuration flag SECURE_BOOT_VERIFY_CERTIFICATE is set or a device has previously seen certificate based signing, it will not accept direct signing.
   DONE

   Note: For the TrustZone-aware applications, the unsigned application image is the combined image of Secure and Non-secure applications. The ApplicationProperties_t struct is located in the Secure application.

Signing for ECDSA-P256-SHA256 Secure Boot#

The following figure describes the signing and verification for ECDSA-P256-SHA256 Secure Boot.

Note:

• The bootloader cannot access the Public Sign Key in VSE OTP to verify the application image. Therefore VSE devices need to store a Public Sign Key copy on the top page of the main flash (see section Key Storage in UG266/Silicon Labs Gecko Bootloader User's Guide for GSDK 4.0 and Higher).

The HSE device ignores the default enabled Allow use of public key from manufacturing token storage option once the Public Sign Key has been provisioned.

• To have better protection on the Public Sign Key. The certificate-basedSecure Boot is strongly recommended on VSE devices since the SSB does not require accessing the Public Sign Key to verify the application signature.

The following sections provide two methods to sign the bootloader image and application image files. All procedures assume the required files are in the same folder.

1. Using Simplicity Commander

2. Using an HSM and Simplicity Commander

Bootloader Image File

1. If the SE OTP is not provisioned, follow the procedures in Simplicity Commander to set up the ECDSA-P256-SHA256 Secure Boot configuration for the bootloader.

2. Follow the procedures in AppBuilderor Bootloader-core Software Component to set up the ECDSA-P256-SHA256 Secure Boot configuration for the user application to generate an unsigned bootloader image.

3. (Using Simplicity Commander) Run the convert command with Private Sign Key to overwrite the unsigned bootloader image file with the signed bootloader image file (bootloader-uart-xmodem.s37).

   commander convert bootloader-uart-xmodem.s37 --secureboot --keyfile sign_key.pem --verify sign_pubkey.pem
   --outfile bootloader-uart-xmodem.s37

   Parsing file bootloader-uart-xmodem.s37...
   Found Application Properties at 0x00002b1c
   Writing Application Properties signature pointer to point to 0x00002d08
   Setting signature type in Application Properties: 0x00000001
   Image SHA256: c53bb8a3fd88a5071bfb71444324bb136b276160318488ff89011bbd269e114e
   R = AB62F3A52B13D137FBCC6A2176D4D1852E06B6E4E6B2673DC251FC491450CBDA
   S = 9C7C7AF2624165FD90FB3B114E3FA6FE4F4C5625B15C9F3D50DCB04DD06A7B19
   Verifying signed image...
   Writing to bootloader-uart-xmodem.s37...
   Overwriting file: bootloader-uart-xmodem.s37...
   DONE

4. (Using an HSM and Simplicity Commander) Run the convert command with --extsign option to generate an external signing bootloader image file (bootloader-uart-xmodem.extsign).

   commander convert bootloader-uart-xmodem.s37 --secureboot --extsign --outfile bootloader-uart-xmodem

   Parsing file bootloader-uart-xmodem.s37...
   Found Application Properties at 0x00002b1c
   Writing Application Properties signature pointer to point to 0x00002d08
   Setting signature type in Application Properties: 0x00000001
   Writing to bootloader-uart-xmodem.extsign...
   DONE

   Use an HSM containing the Private Sign Key to generate the signature for the external signing bootloader image. This example uses the OpenSSL with the Private Sign Key to simulate this process. The signature is in the bl_signature.der.

   openssl dgst -sha256 -binary -sign sign_key.pem -out bl_signature.der bootloader-uart-xmodem.extsign

   Run the convert command with the bootloader image signature to overwrite the unsigned bootloader image file with the signed bootloader image file (bootloader-uart-xmodem.s37).

   commander convert bootloader-uart-xmodem.s37 --secureboot --signature bl_signature.der
   --verify sign_pubkey.pem --outfile bootloader-uart-xmodem.s37

   Parsing file bootloader-uart-xmodem.s37...
   Parsing signature file bl_signature.der...
   R = 0E9FC64F41B55367894908D3ADAC40E8D145E33224C4BAA8151EC3EFD107A154
   S = F56230AA6484E55270F22A4D164377CA918F66A367656AB6E10CB3F58641CE84
   Found Application Properties at 0x00002b1c
   Writing Application Properties signature pointer to point to 0x00002d08
   Setting signature type in Application Properties: 0x00000001
   Verifying signed image...
   Writing to bootloader-uart-xmodem.s37...
   Overwriting file: bootloader-uart-xmodem.s37...
   DONE

5. (Optional) Run the util appinfocommand to check all available information about ApplicationProperties_t struct in a signed GBL image.

   commander util appinfo bootloader-uart-xmodem.s37

   Parsing file bootloader-uart-xmodem.s37...
   Found application properties in image.
   Application properties info:
   Application properties location : 0x00002b30
   Signature location              : 0x00002c44Signature type                  : ECDSA-P256
   Long token section address      : Not set (0x00000000)
   Application data info:
   For Series 2 devices: If rollback prevention is enabled in the OTP configuration, the device will not boot if the device has seen an application with a higher version number.
   App type                        : Bootloader (APPLICATION_TYPE_BOOTLOADER)App version                     : 0x02000000
   Product ID                      : Not set (0x00000000000000000000000000000000)
   No certificate found in image.
   For Series 2 devices: If the configuration flag SECURE_BOOT_VERIFY_CERTIFICATE is set or a device has previously seen certificate based signing, it will not accept direct signing.
   DONE

6. The signed bootloader image file (.s37) can be used for production programming or for generating a GBL upgrade image file for bootloader upgrade.

7. Run the flash command to program the signed bootloader image (bootloader-uart-xmodem.s37) to the device if the device does not have a bootloader.

   commander flash bootloader-uart-xmodem.s37 --device EFR32MG21A010F1024 --serialno 440048205

   Parsing file bootloader-uart-xmodem.s37...
   Writing 16384 bytes starting at address 0x00000000
   Comparing range 0x00000000 - 0x00003FFF (16 KiB)
   Programming range 0x00000000 - 0x00001FFF (8 KiB)
   Programming range 0x00002000 - 0x00003FFF (8 KiB)
   DONE

Application Image File

1. Follow the procedures in Generate an Unsigned Application Image to generate an unsigned application image for the bootloader.

2. (Using Simplicity Commander) Run the convert command with Private Sign Key to overwrite the unsigned application image file with the signed application image file (blink_baremetal.s37).

   commander convert blink_baremetal.s37 --secureboot --keyfile sign_key.pem --verify sign_pubkey.pem
   --outfile blink_baremetal.s37

   Parsing file blink_baremetal.s37...
   Found Application Properties at 0x000061bc
   Writing Application Properties signature pointer to point to 0x000064d8
   Setting signature type in Application Properties: 0x00000001
   Image SHA256: 8b58ec567126aa1f6baa88afc916581477745aca6f47697ec093512fc30dcc6f
   R = 056E3AA36BD882B5467D44A56DB7CC1AEE44D45BC9B98FAB05BE2C032573A1F7
   S = BE1D27CE7877D0BC761C0F02690CC74251EBE3A458474C573C21B3A738A03577
   Verifying signed image...
   Writing to blink_baremetal.s37...
   Overwriting file: blink_baremetal.s37...
   DONE

3. (Using an HSM and Simplicity Commander) Run the convert command with --extsign option to generate an external signing application image file (blink_baremetal.extsign).

   commander convert blink_baremetal.s37 --secureboot --extsign --outfile blink_baremetal

   Parsing file blink_baremetal.s37...
   Found Application Properties at 0x00006198
   Writing Application Properties signature pointer to point to 0x0000643c
   Setting signature type in Application Properties: 0x00000001
   Writing to blink_baremetal.extsign...
   DONE

   Use an HSM containing the Private Sign Key to generate the signature for the external signing application image. This example uses the OpenSSL with the Private Sign Key to simulate this process. The signature is in the app_signature.der.

   openssl dgst -sha256 -binary -sign sign_key.pem -out app_signature.der blink_baremetal.extsign

   Run the convert command with the application image signature to overwrite the unsigned application image file with the signed application image file. (blink_baremetal.s37).

   commander convert blink_baremetal.s37 --secureboot --signature app_signature.der --verify sign_pubkey.pem
   --outfile blink_baremetal.s37

   Parsing file blink_baremetal.s37...
   Parsing signature file app_signature.der...
   R = BD5BDC866CE67DA104B1E7B686C45B7BF96F2643154D37ACC63DACDF69C27E89
   S = 2DD3BFFAC857A5B0BD8C9B4DDB23D21944D062F8E431D36541B84EF411C1CC92
   Found Application Properties at 0x000061bc
   Writing Application Properties signature pointer to point to 0x000064d8
   Setting signature type in Application Properties: 0x00000001
   Verifying signed image...
   Writing to blink_baremetal.s37...
   Overwriting file: blink_baremetal.s37...
   DONE

4. (Optional) Run the util appinfocommand to check all available information about ApplicationProperties_t struct in a signed application image.

   commander util appinfo blink_baremetal.s37

   Parsing file blink_baremetal.s37...
   Found application properties in image.
   Application properties info:
   Application properties location : 0x000061bc
   Signature location              : 0x000064d8Signature type                  : ECDSA-P256
   Long token section address      : Not set (0x00000000)
   Application data info:
   For Series 2 devices: If rollback prevention is enabled in the OTP configuration, the device will not boot if the device has seen an application with a higher version number.
   App type                        : MCU application (APPLICATION_TYPE_MCU)App version                     : 0x00000001
   Product ID                      : Not set (0x00000000000000000000000000000000)
   No certificate found in image.
   For Series 2 devices: If the configuration flag SECURE_BOOT_VERIFY_CERTIFICATE is set or a device has previously seen certificate based signing, it will not accept direct signing.
   DONE

5. The signed application image file (.s37) can be used for production programming or for generating a GBL upgrade image file for application upgrade.

Signing for Certificate-Based Secure Boot#

The following figure describes the signing and verification for certificate-based Secure Boot. The user can freely switch between standard and advanced certificate-based Secure Boot by upgrading the application firmware without and with the application certificate.

Certificate#

The following table describes the elements of a certificate.

Table: Certificate Structure

Note:

• The application_properties.h in the Windows folder below defines the parameters of the certificate structure (ApplicationCertificate_t).

  For GSDK v3.2 and lower: C:\SiliconLabs\SimplicityStudio\v5\developer\sdks\gecko_sdk_suite\<GSDK VERSION>\platform\bootloader\api

  For GSDK v4.0 and higher: C:\Users\<PC USER NAME>\SimplicityStudio\SDKs\gecko_sdk\platform\bootloader\api

• The certificate is not in X.509 format.

Private/Public Key Pair#

The following table describes two Private/Public Key pairs used in certificates for certificate-based Secure Boot. The user can use Simplicity Commander or HSM to generate these key pairs.

Table: Certificates and Key Pairs for Certificate-Based Secure Boot Examples

Note:

1. a. Certificate version in the bootloader certificate < certificate version in SE flash - the certificate is rejected.

   b. Certificate version in the bootloader certificate = certificate version in SE flash - the certificate is accepted.

   c. Certificate version in the bootloader certificate > certificate version in SE flash - the certificate is accepted. The certificate version in SE flash is updated to match (revocation mechanism).

2. The certificate version in the application certificate is compared with the certificate version in the bootloader certificate. The application certificate is accepted if its version is equal to or higher than the certificate version in the bootloader certificate.

The following sections provide two methods to sign the bootloader image and application image files. All procedures assume the required files are in the same folder.

1. Using Simplicity Commander

2. Using an HSM and Simplicity Commander

Bootloader Image File

1. If the SE OTP is not provisioned, follow the procedures in Simplicity Commander to set up the certificate-based Secure Boot configuration for the bootloader.

2. Follow the procedures in AppBuilder or Bootloader-core Software Component to set up the certificate-based Secure Boot configuration for the user application to generate an unsigned bootloader image.

3. (Using Simplicity Commander) Run the util gencert command with Public Bootloader Key and Private Sign Key to generate the bootloader certificate (bl_cert.bin). Refer to Certificates and Key Pairs for Certificate-Based Secure Boot Examples for details about the --cert-version for bootloader certificate.

   commander util gencert --cert-type secureboot --cert-version 1 --cert-pubkey bl_cert_pubkey.pem
   --sign sign_key.pem --outfile bl_cert.bin

   Successfully signed certificate
   DONE

   Run the convert command with Bootloader Certificate and Private Bootloader Key to overwrite the unsigned bootloader image file with the signed bootloader image file (bootloader-uart-xmodem.s37).

   commander convert bootloader-uart-xmodem.s37 --secureboot --certificate bl_cert.bin
   --keyfile bl_cert_key.pem --outfile bootloader-uart-xmodem.s37

   Parsing file bootloader-uart-xmodem.s37...
   Writing certificate to location 0x00002cf0
   Private key matches public key in certificate.
   Found Application Properties at 0x00002d78
   Writing Application Properties signature pointer to point to 0x00002f64
   Setting signature type in Application Properties: 0x00000001
   Image SHA256: 3cf574b688853a801e8dc98687414db27f886c60c55dbf7fea2d47633df94e8d
   R = C866592B4CB7BAD9EFC35985F1B9D52C65C26453D4808597EEEFFB16DC4AA962
   S = 94CAA21ED5D7772F96BBF4D24A0711A94DCCB6D4D38DFA45182876B9BE2A8DE3
   Verifying signed image...
   Writing to bootloader-uart-xmodem.s37...
   Overwriting file: bootloader-uart-xmodem.s37...
   DONE

4. (Using an HSM and Simplicity Commander) Run the util gencert command with Public Bootloader Key and --extsign option to generate an external signing bootloader certificate (bl_cert.extsign). Refer to Certificates and Key Pairs for Certificate-Based Secure Boot Examples for details about the --cert-version for bootloader certificate.

   commander util gencert --cert-type secureboot --cert-version 1 --cert-pubkey bl_cert_pubkey.pem--extsign --outfile bl_cert
   DONE

   Use an HSM containing the Private Sign Key to generate the signature for the external signing bootloader certificate. This example uses the OpenSSL with the Private Sign Key to simulate this process. The signature is in the bl_cert_signature.der.

   openssl dgst -sha256 -binary -sign sign_key.pem -out bl_cert_signature.der bl_cert.extsign

   Run the util signcert command with the bootloader certificate signature to generate the bootloader certificate (bl_cert.bin).

   commander util signcert bl_cert.extsign --cert-type secureboot --signature bl_cert_signature.der
   --verify sign_pubkey.pem --outfile bl_cert.bin

   R = 065A58EA6CE6BBA44F3C59C6D255A901DBBC55FA97F261658B2026ABC8CD9680
   S = 8A0011AA6393BC284B13C8313EE6772030DE07E213E74CA0FEA740F3D33E6518
   Successfully verified signature
   Successfully signed certificate
   DONE

   Run the convert command with Bootloader Certificate and --extsign option to generate an external signing bootloader image file (bootloader-uart-xmodem.extsign).

   commander convert bootloader-uart-xmodem.s37 --secureboot --certificate bl_cert.bin--extsign
   --outfile bootloader-uart-xmodem

   Parsing file bootloader-uart-xmodem.s37...
   Writing certificate to location 0x00002cf0
   Found Application Properties at 0x00002d78
   Writing Application Properties signature pointer to point to 0x00002f64
   Setting signature type in Application Properties: 0x00000001
   Writing to bootloader-uart-xmodem.extsign...
   DONE

   Use an HSM containing the Private Bootloader Key to generate the signature for the external signing bootloader image. This example uses the OpenSSL with the Private Bootloader Key to simulate this process. The signature is in the bl_signature.der.

   openssl dgst -sha256 -binary -sign bl_cert_key.pem -out bl_signature.der bootloader-uart-xmodem.extsign

   Run the convert command with the Bootloader Certificate and bootloader image signature to overwrite the unsigned bootloader image file with the signed bootloader image file (bootloader-uart-xmodem.s37).

   commander convert bootloader-uart-xmodem.s37 --secureboot --certificate bl_cert.bin
   --signature bl_signature.der --outfile bootloader-uart-xmodem.s37

   Parsing file bootloader-uart-xmodem.s37...
   Writing certificate to location 0x00002cf0
   Parsing signature file bl_signature.der...
   R = 7AAA17E8F875F2572AF7692079ED2C48A1329D3AA2E616E7E13007CE68C32A21
   S = 6E5F1ACD929A1AC05DE9F4BC5CBDE0E076B32EDA353C5E571C7850AAB86BCCFB
   Found Application Properties at 0x00002d78
   Writing Application Properties signature pointer to point to 0x00002f64
   Setting signature type in Application Properties: 0x00000001
   Verifying signed image...
   Writing to bootloader-uart-xmodem.s37...
   Overwriting file: bootloader-uart-xmodem.s37...
   DONE

5. (Optional) Run the util verifysign command with Public Sign Key to verify that the Bootloader Certificate and image were correctly signed.

   commander util verifysign bootloader-uart-xmodem.s37 --verify sign_pubkey.pem

   Parsing file bootloader-uart-xmodem.s37...
   Found application properties at 0x00002d78
   Found certificate at 0x00002cf0
   Successfully verified certificate signature with verification key.
   Using certificate key to verify application signature.
   Successfully verified application signature.
   DONE

6. (Optional) Run the util appinfo command to check all available information about ApplicationProperties_t struct in a signed GBL image.

   commander util appinfo bootloader-uart-xmodem.s37

   Parsing file bootloader-uart-xmodem.s37...
   Found application properties in image.
   Application properties info:
   Application properties location : 0x00002d00
   Signature location              : 0x00002e14Signature type                  : ECDSA-P256
   Long token section address      : Not set (0x00000000)
   Application data info:
   For Series 2 devices: If rollback prevention is enabled in the OTP configuration, the device will not boot if the device has seen an application with a higher version number.
   App type                        : Bootloader (APPLICATION_TYPE_BOOTLOADER)App version                     : 0x02000000
   Product ID                      : Not set (0x00000000000000000000000000000000)
   Found certificate at 0x00002c78
   Application certificate info:
   Certificate located at          : 0x00002c78
   Certificate version             : 0x00000001
   Certificate key                 : 0xb1bc6f6fa56640ed522b2ee0f5b3cf7e5d48f60be8148f0dc08440f0a4e1dca4
                                     7c04119ed6a1be31b7707e5f9d001a659a051003e95e1b936f05c37ea793ad63
   Certificate signature           : 0xef3b53368d4cd7821eb30a96140bbde8840378cfea30687a8c10642e1c7728fd
                                     309f976adf46e4eac62a2233f0c1f08f4e58344bdec61775b5282ceb351bb3d0
   DONE

7. The signed bootloader image file (.s37) can be used for production programming or for generating a GBL upgrade image file for bootloader upgrade.

8. Run the flash command to program the signed bootloader image (bootloader-uart-xmodem.s37) to the device if the device does not have a bootloader.

   commander flash bootloader-uart-xmodem.s37 --device EFR32MG21A010F1024 --serialno 440048205

   Parsing file bootloader-uart-xmodem.s37...
   Writing 16384 bytes starting at address 0x00000000
   Comparing range 0x00000000 - 0x00003FFF (16 KiB)
   Programming range 0x00000000 - 0x00001FFF (8 KiB)
   Programming range 0x00002000 - 0x00003FFF (8 KiB)
   DONE

Application Image File (Standard Certificate-Based)

1. Follow the procedures in Generate an Unsigned Application Image to generate an unsigned application image for the bootloader.

2. (Using Simplicity Commander) Run the convert command with Private Bootloader Key to overwrite the unsigned application image file with the signed application image file (blink_baremetal.s37).

   commander convert blink_baremetal.s37 --secureboot --keyfile bl_cert_key.pem --verify bl_cert_pubkey.pem
   --outfile blink_baremetal.s37

   Parsing file blink_baremetal.s37...
   Found Application Properties at 0x000061bc
   Writing Application Properties signature pointer to point to 0x000064d8
   Setting signature type in Application Properties: 0x00000001
   Image SHA256: 8b58ec567126aa1f6baa88afc916581477745aca6f47697ec093512fc30dcc6f
   R = 994739A26AB520A88A5550F1643AE263D88A952F185F96EE7021FA43DEA6138C
   S = 65B7112715E2F999A6B216C32D3331AB63B2D31A0A1311DF36EEE62269F8D6AA
   Verifying signed image...
   Writing to blink_baremetal.s37...
   Overwriting file: blink_baremetal.s37...
   DONE

3. (Using an HSM and Simplicity Commander) Run the convert command with --extsign option to generate an external signing application image file (blink_baremetal.extsign).

     commander convert blink_baremetal.s37 --secureboot --extsign --outfile blink_baremetal

     Parsing file blink_baremetal.s37...
     Found Application Properties at 0x000061bc
     Writing Application Properties signature pointer to point to 0x000064d8
     Setting signature type in Application Properties: 0x00000001
     Writing to blink_baremetal.extsign...
     DONE

   Use an HSM containing the Private Bootloader Key to generate the signature for the external signing application image. This example uses the OpenSSL with the Private Bootloader Key to simulate this process. The signature is in the app_signature.der.

     openssl dgst -sha256 -binary -sign bl_cert_key.pem -out app_signature.der blink_baremetal.extsign

   Run the convert command with the application image signature to overwrite the unsigned application image file with the signed application image file. (blink_baremetal.s37).

     commander convert blink_baremetal.s37 --secureboot --signature app_signature.der
     --verify bl_cert_pubkey.pem --outfile blink_baremetal.s37

     Parsing file blink_baremetal.s37...
     Parsing signature file app_signature.der...
     R = 8DA79B020E954D24C23423D80627E046E44052736F6546902F016D64464E82DE
     S = 9D5A1CC424E97A5AD0352A4EEA6BBF565FED5FC61FF99E63AA73DFFEAD9EE399
     Found Application Properties at 0x000061bc
     Writing Application Properties signature pointer to point to 0x000064d8
     Setting signature type in Application Properties: 0x00000001
     Verifying signed image...
     Writing to blink_baremetal.s37...
     Overwriting file: blink_baremetal.s37...
     DONE

4. (Optional) Run the util verifysign command with Public Bootloader Key to verify that the application image file was correctly signed.

   commander util verifysign blink_baremetal.s37 --verify bl_cert_pubkey.pem

   Parsing file blink_baremetal.s37...
   Found application properties at 0x000061bc
   Did not find application certificate in file
   If the configuration flag SECURE_BOOT_VERIFY_CERTIFICATE is set or a device has previously seen certificate based signing, it will not accept direct signing.
   Successfully verified application signature.
   DONE

5. (Optional) Run the util appinfo command to check all available information about ApplicationProperties_t struct in a signed application image.

   commander util appinfo blink_baremetal.s37

   Parsing file blink_baremetal.s37...
   Found application properties in image.
   Application properties info:
   Application properties location : 0x000061bc
   Signature location              : 0x000064d8Signature type                  : ECDSA-P256
   Long token section address      : Not set (0x00000000)
   Application data info:
   For Series 2 devices: If rollback prevention is enabled in the OTP configuration, the device will not boot if the device has seen an application with a higher version number.
   App type                        : MCU application (APPLICATION_TYPE_MCU)App version                     : 0x00000001
   Product ID                      : Not set (0x00000000000000000000000000000000)
   No certificate found in image.
   For Series 2 devices: If the configuration flag SECURE_BOOT_VERIFY_CERTIFICATE is set or a device has previously seen certificate based signing, it will not accept direct signing.
   DONE

6. The signed application image file (.s37) can be used for production programming or for generating a GBL upgrade image file for application upgrade.

Application Image File (Advanced Certificate-Based)

1. Follow the procedures in Generate an Unsigned Application Image to generate an unsigned application image for the bootloader.

2. (Using Simplicity Commander) Run the util gencert command with Public Application Key and Private Bootloader Key to generate the application certificate (app_cert.bin). Refer to Certificates and Key Pairs for Certificate-Based Secure Boot Examples for details about the --cert-version for application certificate.

   commander util gencert --cert-type secureboot --cert-version 1 --cert-pubkey app_cert_pubkey.pem
   --sign bl_cert_key.pem --outfile app_cert.bin

   Successfully signed certificate
   DONE

   Run the convert command with Application Certificate and Private Application Key to overwrite the unsigned application image file with the signed application image file. (blink_baremetal.s37). This command will inject the application certificate into the application image before signing.

   commander convert blink_baremetal.s37 --secureboot --certificate app_cert.bin --keyfile app_cert_key.pem
   --outfile blink_baremetal.s37

   Parsing file blink_baremetal.s37...
   Writing certificate to location 0x000064d8
   Private key matches public key in certificate.
   Found Application Properties at 0x000061bc
   Writing Application Properties signature pointer to point to 0x00006560
   Setting signature type in Application Properties: 0x00000001
   Image SHA256: 38fd11214c36abf3bb4c4eeda8cfdd2ca2ac2ff1e07072d555a06c74700a23f5
   R = 6B4E3BB454513CAA4569415AE8F79453973AAC7FD1FC4914284B65010F3790A6
   S = 1657CAAABED579880187261038358C83B1780A67CC41475370D94ED4445A5557
   Verifying signed image...
   Writing to blink_baremetal.s37...
   Overwriting file: blink_baremetal.s37...
   DONE

3. (Using an HSM and Simplicity Commander) Run the util gencert command with Public Application Key and --extsign option to generate an external signing application certificate (app_cert.extsign). Refer to Certificates and Key Pairs for Certificate-Based Secure Boot Examples for details about the --cert-version for application certificate.

   commander util gencert --cert-type secureboot --cert-version 1 --cert-pubkey app_cert_pubkey.pem--extsign --outfile app_cert

   DONE

   Use an HSM containing the Private Bootloader Key to generate the signature for the external signing application certificate. This example uses the OpenSSL with the Private Bootloader Key to simulate this process. The signature is in the app_cert_signature.der.

   openssl dgst -sha256 -binary -sign bl_cert_key.pem -out app_cert_signature.der app_cert.extsign

   Run the util signcert command with the application certificate signature to generate the application certificate (app_cert.bin).

   commander util signcert app_cert.extsign --cert-type secureboot --signature app_cert_signature.der
   --verify bl_cert_pubkey.pem --outfile app_cert.bin

   R = 279D4FA1B801D108F82E30B0CF1164BF597549287290BD3883C5847B91095CCE
   S = 567F0E219D2089EF4D79C3D94E43D2FADFE1899B71492ED358E6A1B46AE8162F
   Successfully verified signature
   Successfully signed certificate
   DONE

   Run the convert command with the Application Certificate and --extsign option to generate an external signing application image file (blink_baremetal.extsign).

   commander convert blink_baremetal.s37 --secureboot --certificate app_cert.bin--extsign --outfile blink_baremetal

   Parsing file blink_baremetal.s37...
   Writing certificate to location 0x000064d8
   Found Application Properties at 0x000061bc
   Writing Application Properties signature pointer to point to 0x00006560
   Setting signature type in Application Properties: 0x00000001
   Writing to blink_baremetal.extsign...
   DONE

   Use an HSM containing the Private Application Key to generate the signature for the external signing application image. This example uses the OpenSSL with the Private Application Key to simulate this process. The signature is in the app_signature.der.

   openssl dgst -sha256 -binary -sign app_cert_key.pem -out app_signature.der blink_baremetal.extsign

   Run the convert command with the Application Certificate and application image signature to overwrite the unsigned application image file with the signed application image file. (blink_baremetal.s37). This command will inject the application certificate into the application image before signing.

   commander convert blink_baremetal.s37 --secureboot --certificate app_cert.bin --signature app_signature.der
   --verify app_cert_pubkey.pem --outfile blink_baremetal.s37

   Parsing file blink_baremetal.s37...
   Writing certificate to location 0x000064d8
   Parsing signature file app_signature.der...
   R = ADC2BAB959EC76CB2806C4649277669CF6E62A92ABFBBF20E551971449A8FCE0
   S = B6B80130F95F62671372D1B2E471C82ADB08946C1F8938EED11F9822CE763A54
   Found Application Properties at 0x000061bc
   Writing Application Properties signature pointer to point to 0x00006560
   Setting signature type in Application Properties: 0x00000001
   Verifying signed image...
   Verifying signed image...
   Writing to blink_baremetal.s37...
   Overwriting file: blink_baremetal.s37...
   DONE

4. (Optional) Run the util verifysign command with Public Bootloader Key to verify that the Application Certificate and image were correctly signed.

   commander util verifysign blink_baremetal.s37 --verify bl_cert_pubkey.pem

   Parsing file blink_baremetal.s37...
   Found application properties at 0x000061bc
   Found certificate at 0x000064d8
   Successfully verified certificate signature with verification key.
   Using certificate key to verify application signature.
   Successfully verified application signature.
   DONE

5. (Optional) Run the util appinfo command to check all available information about ApplicationProperties_t struct in a signed application image.

   commander util appinfo blink_baremetal.s37

   Parsing file blink_baremetal.s37...
   Found application properties in image.
   Application properties info:
   Application properties location : 0x000061bc
   Signature location              : 0x00006560Signature type                  : ECDSA-P256
   Long token section address      : Not set (0x00000000)
   Application data info:
   For Series 2 devices: If rollback prevention is enabled in the OTP configuration, the device will not boot if the device has seen an application with a higher version number.
   App type                        : MCU application (APPLICATION_TYPE_MCU)
   App version                     : 0x00000001
   Product ID                      : Not set (0x00000000000000000000000000000000)
   Found certificate at 0x000064d8
   Application certificate info:
   Certificate located at          : 0x000064d8
   Certificate version             : 0x00000001
   Certificate key                 : 0xe562003cd86e225decfd35712e431a19ecd5031a079b06c1d473620a6be9f57a
                                     879820100fee074f28b5885fd6759f480b62aaa0717f96e245aab6635cfb1e11
   Certificate signature           : 0x039aaba62b5258e68d16e167c3a611c719c542bb3483f5d4b522472b06adf30f
                                     8cfcc484bf8551a208256e3d2d8c9194a7d2ac551e2cac659a99822308a40aa6
   DONE

6. The signed application image file (.s37) can be used for production programming or for generating a GBL upgrade image file for application upgrade.

Generate a GBL Upgrade Image File#

This section describes how to generate the GBL upgrade image files for updating the bootloader, Secure Engine, and application firmware.

Note:

1. Following the procedures in AppBuilder or Bootloader-core Software Component to avoid overwriting the existing application image (if necessary) when upgrading the bootloader or SE.

2. For a standalone bootloader with communication interface, you can only generate three separate GBL upgrade image files containing bootloader, SE, and application images.

3. For an application bootloader with storage, you can generate a single GBL upgrade image file (see example below) with a combination of bootloader, SE, and application images.

   commander gbl create all.gbl --app app.s37 --bootloader bl.s37 --seupgrade se.seu

4. A signed GBL upgrade image file is required if the user enables the Require signed firmware upgrade files option in AppBuilder or Bootloader-core Software Component. The following table shows which private key(s) can be used to sign the GBL upgrade image file (bootloader, SE, or application) on HSE and VSE devices. The VSE devices store a Public Sign Key copy on the top page of the main flash to verify the GBL upgrade image file for ECDSA-P256-SHA256 Secure Boot.

   | Secure Boot |HSE |VSE | |-|-|-| | ECDSA-P256-SHA256 |Private Sign Key |Private Sign Key (Public Sign Key in main flash) | | Certificate-Based |Private Sign Key or Private Bootloader Key |Private Bootloader Key |

5. An encrypted GBL upgrade image file is required if the user enables the Require encrypted firmware upgrade files option in AppBuilder or Bootloader-core Software Component. Refer to Provision GBL Decryption Key on how to provision the GBL Decryption Key for this option.

6. For an application bootloader with storage, the user can enable the Upgrade SE without using the staging area option in GSDK v4.1.1 or higher to directly fetch the SE image from the GBL upgrade image file in storage instead of copying the image to the pre-configured upgrade location.

   

To use the above option, the SE image cannot be in the encrypted part of the GBL upgrade image file if the Require encrypted firmware upgrade files option is enabled. Use the --seunencrypted option in Simplicity Commander v1.13.0 or higher (see example below) to generate an encrypted GBL upgrade image file with a SE image outside the encrypted part of the file.

commander gbl create se-upgrade.gbl --seupgrade secure-element.seu --seunencrypted --app myapp.s37
--encrypt aes_key.txt

The following sections provide two methods to sign the bootloader, Secure Engine, and application upgrade image files if the Require signed firmware upgrade files option is enabled.

1. Using Simplicity Commander

2. Using an HSM and Simplicity Commander

The sections also include encryption examples with an AES-128 key (like aes_key.txt) for the Require encrypted firmware upgrade files option. All procedures assume the required files are in the same folder.

Bootloader Upgrade#

1. (Unsigned) Run the gbl create command with --bootloader option to generate the bootloader GBL upgrade image file (bootloader-uart-xmodem.gbl) with the signed bootloader image file (bootloader-uart-xmodem.s37) from Signing for ECDSA-P256-SHA256 Secure Boot or Signing for Certificate-Based Secure Boot.

   Without encryption:

   commander gbl create bootloader-uart-xmodem.gbl --bootloader bootloader-uart-xmodem.s37

   Initializing GBL file...
   Adding bootloader to GBL...
   Writing GBL file bootloader-uart-xmodem.gbl...
   DONE

   With encryption:

   commander gbl create bootloader-uart-xmodem.gbl --bootloader bootloader-uart-xmodem.s37
   --encrypt aes_key.txt

   Initializing GBL file...
   Adding bootloader to GBL...
   Encrypting GBL...
   Writing GBL file bootloader-uart-xmodem.gbl...
   DONE

2. (Signed - Using Simplicity Commander) Run the gbl create command with --bootloader option to generate the signed bootloader GBL upgrade image file (bootloader-uart-xmodem.gbl) with Private Sign Key or Private Bootloader Key and the signed bootloader image file (bootloader-uart-xmodem.s37) from Signing for ECDSA-P256-SHA256 Secure Boot or Signing for Certificate-Based Secure Boot.

   Without encryption:

   commander gbl create bootloader-uart-xmodem.gbl --bootloader bootloader-uart-xmodem.s37 --sign sign_key.pem

   commander gbl create bootloader-uart-xmodem.gbl --bootloader bootloader-uart-xmodem.s37
   --sign bl_cert_key.pem

   Initializing GBL file...
   Adding bootloader to GBL...
   Signing GBL...
   Image SHA256: 3eb09993ffca5f9b34df3f38b65ab9d2f6619b828b014a186516016d4bbd80f7
   R = C21E0C19254AC4F62374BBCA65DEBB42C7349384F5527330CD030A51DC2170F7
   S = E1680C3670DE68D731086845E2726EF3BF07B96EB54AA2DB2F390F60BDB6DAB2
   Writing GBL file bootloader-uart-xmodem.gbl...
   DONE

   With encryption:

   commander gbl create bootloader-uart-xmodem.gbl --bootloader bootloader-uart-xmodem.s37 --sign sign_key.pem--encrypt aes_key.txt

   commander gbl create bootloader-uart-xmodem.gbl --bootloader bootloader-uart-xmodem.s37
   --sign bl_cert_key.pem--encrypt aes_key.txt

   Initializing GBL file...
   Adding bootloader to GBL...
   Encrypting GBL...
   Signing GBL...
   Image SHA256: a2ef5e19e6b2ec327010af9fcb7de861c6a311987b7d2c39ef6439ca8b9999c4
   R = B74972171109A05A9B1B45E1C8A2BCD57EAB1EA8F8A7936BBDB14CF6FA36B28C
   S = 9B673083684B01C2D05BD702A4D29A6EDCF88C471C3FA8B71DDE00AE85861930
   Writing GBL file bootloader-uart-xmodem.gbl...
   DONE

3. (Signed - Using an HSM and Simplicity Commander) Run the gbl create command with --bootloader and --extsign options to generate an external signing bootloader GBL upgrade image file (bootloader-uart-xmodem.extsign) with the signed bootloader image file (bootloader-uart-xmodem.s37) from Signing for ECDSA-P256-SHA256 Secure Boot or Signing for Certificate-Based Secure Boot.

   Without encryption:

   commander gbl create bootloader-uart-xmodem --bootloader bootloader-uart-xmodem.s37 --extsign

   Initializing GBL file...
   Adding bootloader to GBL...
   Preparing GBL for external signing...
   Writing GBL file bootloader-uart-xmodem.extsign...
   DONE

   With encryption:

   commander gbl create bootloader-uart-xmodem --bootloader bootloader-uart-xmodem.s37 --extsign--encrypt aes_key.txt

   Initializing GBL file...
   Adding bootloader to GBL...
   Encrypting GBL...
   Preparing GBL for external signing...
   Writing GBL file bootloader-uart-xmodem.extsign...
   DONE

   Use an HSM containing the Private Sign Key or Private Bootloader Key to generate the signature for the external signing bootloader GBL upgrade image file. This example uses the OpenSSL with the Private Sign Key or Private Bootloader Key to simulate this process. The signature is in the gbl_signature.der.

   openssl dgst -sha256 -binary -sign sign_key.pem -out gbl_signature.der bootloader-uart-xmodem.extsign

   openssl dgst -sha256 -binary -sign bl_cert_key.pem -out gbl_signature.der bootloader-uart-xmodem.extsign

   Run the gbl sign command with the signature above to generate a signed bootloader GBL upgrade image file (bootloader-uart-xmodem.gbl).

   commander gbl sign bootloader-uart-xmodem.extsign --signature gbl_signature.der --verify sign_pubkey.pem
   --outfile bootloader-uart-xmodem.gbl

   commander gbl sign bootloader-uart-xmodem.extsign --signature gbl_signature.der
   --verify bl_cert_pubkey.pem --outfile bootloader-uart-xmodem.gbl

   Reading GBL data from bootloader-uart-xmodem.extsign...
   Parsing signature file gbl_signature.der...
   R = 90F0A3C0D5D9ED2DC10EB3F55595FF21AB31307DC6283E3F3B7494A30FB741D4
   S = 2765041F515A960F048CA250BFAB92031D4D1E569FB3F917C9329E7362C17B51
   Writing signature to GBL...
   Verifying GBL...
   Successfully verified GBL signatureWriting GBL file bootloader-uart-xmodem.gbl...
   DONE

4. Follow the procedures in Upload a GBL Upgrade Image File to upgrade the bootloader with the bootloader GBL upgrade image file.

Secure Engine Upgrade#

1. (Unsigned) Run the gbl create command with --seupgrade option to generate the SE GBL upgrade image file (s2c1_se_fw_upgrade_1v2p9.gbl) with the SE image file (s2c1_se_fw_upgrade_1v2p9.seu).

   Without encryption:

   commander gbl create s2c1_se_fw_upgrade_1v2p9.gbl --seupgrade s2c1_se_fw_upgrade_1v2p9.seu

   Initializing GBL file...
   Adding Secure Element upgrade image to GBL...
   Writing GBL file s2c1_se_fw_upgrade_1v2p9.gbl...
   DONE

   With encryption:

   commander gbl create s2c1_se_fw_upgrade_1v2p9.gbl --seupgrade s2c1_se_fw_upgrade_1v2p9.seu
   --encrypt aes_key.txt

   Initializing GBL file...
   Adding Secure Element upgrade image to GBL...
   Encrypting GBL...
   Writing GBL file s2c1_se_fw_upgrade_1v2p9.gbl...
   DONE

2. (Signed - Using Simplicity Commander) Run the gbl create command with --seupgrade option to generate the signed SE GBL upgrade image file (s2c1_se_fw_upgrade_1v2p9.gbl) with Private Sign Key or Private Bootloader Key and the SE image file (s2c1_se_fw_upgrade_1v2p9.seu).

   Without encryption:

   commander gbl create s2c1_se_fw_upgrade_1v2p9.gbl --seupgrade s2c1_se_fw_upgrade_1v2p9.seu
   --sign sign_key.pem

   commander gbl create s2c1_se_fw_upgrade_1v2p9.gbl --seupgrade s2c1_se_fw_upgrade_1v2p9.seu
   --sign bl_cert_key.pem

   Initializing GBL file...
   Adding Secure Element upgrade image to GBL...
   Signing GBL...
   Image SHA256: 599d7fc35996b4715441b642709ed262525d09d811d4726e423c0d605ec0f0bf
   R = EF8EC2DDEDDF44DF88FEAD4ED0A9FDC6351B4D745D5A05BFB87204791871A525
   S = FCB26EF005D97E8C5341153A210AE9927E1CF646A3E473FFB90DA8C857E6421F
   Writing GBL file s2c1_se_fw_upgrade_1v2p9.gbl...
   DONE

   With encryption:

   commander gbl create s2c1_se_fw_upgrade_1v2p9.gbl --seupgrade s2c1_se_fw_upgrade_1v2p9.seu
   --sign sign_key.pem--encrypt aes_key.txt

   commander gbl create s2c1_se_fw_upgrade_1v2p9.gbl --seupgrade s2c1_se_fw_upgrade_1v2p9.seu
   --sign bl_cert_key.pem--encrypt aes_key.txt

   Initializing GBL file...
   Adding Secure Element upgrade image to GBL...
   Encrypting GBL...
   Signing GBL...
   Image SHA256: a5ab368c99c49503a7dfb6aef1724dc3f883eabddcac7b089148035483e24322
   R = 289F05910A8E0735648260FA7A1C67731CA86FB2DFCB9B405EC8D297892915A7
   S = F21D18351442D0E5F49CFBEDA2C0EFA8B7F0911B4B6216EB48250CB5889ECAFD
   Writing GBL file s2c1_se_fw_upgrade_1v2p9.gbl...
   DONE

3. (Signed - Using an HSM and Simplicity Commander) Run the gbl create command with --seupgrade and --extsign options to generate an external signing SE GBL upgrade image file (s2c1_se_fw_upgrade_1v2p9.extsign) with the SE image file (s2c1_se_fw_upgrade_1v2p9.seu).

   Without encryption:

   commander gbl create s2c1_se_fw_upgrade_1v2p9 --seupgrade s2c1_se_fw_upgrade_1v2p9.seu --extsign

   Initializing GBL file...
   Adding Secure Element upgrade image to GBL...
   Preparing GBL for external signing...
   Writing GBL file s2c1_se_fw_upgrade_1v2p9.extsign...
   DONE

   With encryption:

   commander gbl create s2c1_se_fw_upgrade_1v2p9 --seupgrade s2c1_se_fw_upgrade_1v2p9.seu --extsign--encrypt aes_key.txt

   Initializing GBL file...
   Adding Secure Element upgrade image to GBL...
   Encrypting GBL...
   Preparing GBL for external signing...
   Writing GBL file s2c1_se_fw_upgrade_1v2p9.extsign...
   DONE

   Use an HSM containing the Private Sign Key or Private Bootloader Key to generate the signature for the external signing SE GBL upgrade image file. This example uses the OpenSSL with the Private Sign Key or Private Bootloader Key to simulate this process. The signature is in the gbl_signature.der.

   openssl dgst -sha256 -binary -sign sign_key.pem -out gbl_signature.der s2c1_se_fw_upgrade_1v2p9.extsign

   openssl dgst -sha256 -binary -sign bl_cert_key.pem -out gbl_signature.der s2c1_se_fw_upgrade_1v2p9.extsign

   Run the gbl sign command with the signature above to generate a signed SE GBL upgrade image file (s2c1_se_fw_upgrade_1v2p9.gbl).

   commander gbl sign s2c1_se_fw_upgrade_1v2p9.extsign --signature gbl_signature.der --verify sign_pubkey.pem
   --outfile s2c1_se_fw_upgrade_1v2p9.gbl

   commander gbl sign s2c1_se_fw_upgrade_1v2p9.extsign --signature gbl_signature.der
   --verify bl_cert_pubkey.pem --outfile s2c1_se_fw_upgrade_1v2p9.gbl

   Reading GBL data from s2c1_se_fw_upgrade_1v2p9.extsign...
   Parsing signature file gbl_signature.der...
   R = 2798B98194EE02717C738B5866ABD8D234D0F0E096E90495D371D2507D8E1C67
   S = 19F2586E2C6177D6B4EEC708E006F67334C989D0398D4233C686C98ECB6992FB
   Writing signature to GBL...
   Verifying GBL...
   Successfully verified GBL signatureWriting GBL file s2c1_se_fw_upgrade_1v2p9.gbl...
   DONE

4. Follow the procedures in Upload a GBL Upgrade Image File to upgrade the SE with the SE GBL upgrade image file.

Note:

• The sign_key.pem/sign_pubkey.pem key pair is for Signing for ECDSA-P256-SHA256 Secure Boot, and the bl_cert_key.pem/bl_cert_pubkey.pem key pair is for Signing for Certificate-Based Secure Boot.

• Trying to apply a lower version of the SE image file (.seu) to the device will be ignored.

Application Upgrade#

1. (Unsigned) Run the gbl create command with --app option to generate the application GBL upgrade image file (blink_baremetal.gbl) with the signed application image file (blink_baremetal.s37) from Signing for ECDSA-P256-SHA256 Secure Boot or Signing for Certificate-Based Secure Boot.

   Without encryption:

   commander gbl create blink_baremetal.gbl --app blink_baremetal.s37

   Parsing file blink_baremetal.s37...
   Initializing GBL file...
   Adding application to GBL...
   Writing GBL file blink_baremetal.gbl...
   DONE

   With encryption:

   commander gbl create blink_baremetal.gbl --app blink_baremetal.s37 --encrypt aes_key.txt

   Parsing file blink_baremetal.s37...
   Initializing GBL file...
   Adding application to GBL...
   Encrypting GBL...
   Writing GBL file blink_baremetal.gbl...
   DONE

2. (Signed - Using Simplicity Commander) Run the gbl create command with --app option to generate the signed application GBL upgrade image file (blink_baremetal.gbl) with Private Sign Key or Private Bootloader Key and the signed application image file (blink_baremetal.s37) from Signing for ECDSA-P256-SHA256 Secure Boot or Signing for Certificate-Based Secure Boot.

   Without encryption:

   commander gbl create blink_baremetal.gbl --app blink_baremetal.s37 --sign sign_key.pem

   commander gbl create blink_baremetal.gbl --app blink_baremetal.s37 --sign bl_cert_key.pem

   Parsing file blink_baremetal.s37...
   Initializing GBL file...
   Adding application to GBL...
   Signing GBL...
   Image SHA256: 116c1be47d799ab75afc7b3f4c9a8023e5cd031103b1d28c578eebfaf1ad73d2
   R = CE4D85C058301A2437440E00385D97E496F1D8B5CAFFB8C184F8A88B5266E3E9
   S = 90BBF754EBC0AB343CC32AA06ADED85F9D12D1A67CA6608F9085137142000A40
   Writing GBL file blink_baremetal.gbl...
   DONE

   With encryption:

   commander gbl create blink_baremetal.gbl --app blink_baremetal.s37 --sign sign_key.pem--encrypt aes_key.txt

   commander gbl create blink_baremetal.gbl --app blink_baremetal.s37 --sign bl_cert_key.pem--encrypt aes_key.txt

   Parsing file blink_baremetal.s37...
   Initializing GBL file...
   Adding application to GBL...
   Encrypting GBL...
   Signing GBL...
   Image SHA256: 24092ed828e6fffc41e7ed40c046b80789ef2337da0d7373a15e59d27e07e0fc
   R = 6143F307119402DC55C63220D54542B84EBEFB324963C63796A37B9845482B35
   S = AE3644D59DF3A27F45B335CB4F79D2347364958E0F152AF745FB7042537D1B6A
   Writing GBL file blink_baremetal.gbl...
   DONE

3. (Signed - Using an HSM and Simplicity Commander) Run the gbl create command with --app and --extsign options to generate an external signing application GBL upgrade image file (blink_baremetal.extsign) with the signed application image file (blink_baremetal.s37) from Signing for ECDSA-P256-SHA256 Secure Boot or Signing for Certificate-Based Secure Boot.

   Without encryption:

   commander gbl create blink_baremetal --app blink_baremetal.s37 --extsign

   Parsing file blink_baremetal.s37...
   Initializing GBL file...
   Adding application to GBL...
   Preparing GBL for external signing...
   Writing GBL file blink_baremetal.extsign...
   DONE

   With encryption:

   commander gbl create blink_baremetal --app blink_baremetal.s37 --extsign--encrypt aes_key.txt

   Parsing file blink_baremetal.s37...
   Initializing GBL file...
   Adding application to GBL...
   Encrypting GBL...
   Preparing GBL for external signing...
   Writing GBL file blink_baremetal.extsign...
   DONE

   Use an HSM containing the Private Sign Key or Private Bootloader Key to generate the signature for the external signing application GBL upgrade image file. This example uses the OpenSSL with the Private Sign Key or Private Bootloader Key to simulate this process. The signature is in the gbl_signature.der.

   openssl dgst -sha256 -binary -sign sign_key.pem -out gbl_signature.der blink_baremetal.extsign

   openssl dgst -sha256 -binary -sign bl_cert_key.pem -out gbl_signature.der blink_baremetal.extsign

   Run the gbl sign command with the signature above to generate a signed application GBL upgrade image file (blink_baremetal.gbl).

   commander gbl sign blink_baremetal.extsign --signature gbl_signature.der --verify sign_pubkey.pem
   --outfile blink_baremetal.gbl

   commander gbl sign blink_baremetal.extsign --signature gbl_signature.der --verify bl_cert_pubkey.pem
   --outfile blink_baremetal.gbl

   Reading GBL data from blink_baremetal.extsign...
   Parsing signature file gbl_signature.der...
   R = 533499660E24F1620EF25D862FB607F46E9E4ECC41CBDECBE77C64EF1970D96A
   S = FA8901878218F5F1DB0FAF8B074CE98A27C63FFDE63730CD49EE47E847B9811D
   Writing signature to GBL...
   Verifying GBL...
   Successfully verified GBL signature
   Writing GBL file blink_baremetal.gbl...
   DONE

4. Follow the procedures in Upload a GBL Upgrade Image File to upgrade the application with the application GBL upgrade image file.

Note:

• The Simplicity Commander v1.11.0 or above supports GBL upgrade image file in util verifysign command.

commander util verifysign blink_baremetal.gbl --verify sign_pubkey.pem

Successfully verified GBL signature
DONE

• The Simplicity Commander v1.12.0 or above fixes a bug introduced in v1.11.0 when using the --extsign option on the GBL upgrade image file.

Upload a GBL Upgrade Image File#

This section describes how to use UART XMODEM Bootloader v2.0.0 in GSDK v4.0 to upload a GBL upgrade image file (.gbl) to the device. The procedures and pictures may be different for the other versions of this example.

The GBL upgrade image file uses a proprietary format to store the upgrade image for a firmware upgrade. Use the gbl create command to generate the GBL upgrade image file for bootloader, application, and Secure Engine. Refer to UG266/Silicon Labs Gecko Bootloader User's Guide for GSDK 4.0 and Higher and Generate a GBL Upgrade Image File for more information about GBL upgrade image file creation.

The user can use any terminal software that supports the XMODEM-CRC protocol for file transfer. This application note uses Tera Term as terminal software. The default serial port setting is 115200 bps 8-N-1.

1. Assume the UART XMODEM Bootloader and application firmware had already flashed to the radio board on WSTK.

2. Press the RESET and PB0 push buttons on the WSTK.

3. Release the RESET push button to run the UART XMODEM Bootloader.

   

4. Release the PB0 push button. Press 1 (upload gbl) in Tera Term to upload a GBL upgrade image file.

   

5. Transfer a file through XMODEM-CRC in Tera Term, navigate to File → Transfer → XMODEM → Send....

   

6. Select the target GBL upgrade image file. Click [Open] to upload.

   

7. If no error occurs, press 2 (run) to start a firmware upgrade.

   

Upgrade to Certificate-Based Secure Boot#

The user can upgrade the Series 2 devices deployed in the field from ECDSA-P256-SHA256 Secure Boot to certificate-based Secure Boot even the SECURE_BOOT_VERIFY_CERTIFICATE option in SE OTP is disabled.

commander security readconfig --serialno 440048205

MCU Flags
Secure Boot                    : Enabled
Secure Boot Verify Certificate : Disabled
Secure Boot Anti Rollback      : Enabled
Secure Boot Page Lock Narrow   : Disabled
Secure Boot Page Lock Full     : Disabled

The following procedures for the upgrade to certificate-based Secure Boot is an IRREVERSIBLE process.

1. Follow the procedures in Generate Key and Signing to generate an ECDSA-P256 bootloader certificate key pair.

2. Follow the procedures in Signing for Certificate-Based Secure Boot to generate the signed GBL image file with the bootloader certificate key pair in step 1. The bootloader certificate version (--cert-version in the util gencert command) in this signed GBL image file must be equal to or higher than one (≥ 1).

3. Follow the procedures in Generate a GBL Upgrade Image File to upgrade the bootloader to certificate-based Secure Boot. Use the Private Sign Key for ECDSA-P256-SHA256 Secure Boot to sign the bootloader GBL upgrade image file if required.

   SE will use the Public Bootloader Key to validate the bootloader image once SE identifies a bootloader certificate in the bootloader image. If the bootloader certificate version from step 2 is higher than zero (> 0) and gets verified once, SE will never again accept the ECDSA-P256-SHA256 Secure Boot signed bootloader image. Refer to the "Secure Boot Procedure" section in UG266/Silicon Labs Gecko Bootloader User's Guide for GSDK 4.0 and Higher for more information.

   commander security status --device EFR32MG21A010F1024 --serialno 440048205

   SE Firmware version : 1.2.9
   Serial number       : 000000000000000014b457fffe045a2d
   Debug lock          : Disabled
   Device erase        : Enabled
   Secure debug unlock : Disabled
   Tamper status       : Not OK
   Secure boot         : Enabled
   Boot status         : 0x18 - Failed: Secure Boot requires cert, but none found
   DONE

4. (Standard Certificate-Based) Follow the procedures in Signing for Certificate-Based Secure Boot to generate the signed application image file with the Private Bootloader Key in step 1.

5. (Advanced Certificate-Based) Follow the procedures in Generate Key and Signing to generate an ECDSA-P256 application certificate key pair.

   Follow the procedures in Signing for Certificate-Based Secure Boot to generate the signed application image file with the application certificate key pair in this step and the Private Bootloader Key in step 1. The application certificate version (--cert-version in the util gencert command) in this signed application image file must be equal to or higher than the bootloader certificate version in step 2 (Certificates and Key Pairs for Certificate-Based Secure Boot Examples).

6. Follow the procedures in Generate a GBL Upgrade Image File to upgrade application with the signed image from step 4 or 5 for certificate-based Secure Boot. Use the Private Sign Key or Private Bootloader key in step 1 for certificate-based Secure Boot to sign the application GBL upgrade image file if required.

Certificate Revocation#

The certificate revocation is the act of invalidating a certificate when its private key shows signs of being compromised. The following procedures describe how to revoke the Series 2 devices' bootloader certificates deployed in the field.

1. Follow the procedures in Generate Key and Signing to generate a new ECDSA-P256 bootloader certificate key pair.

2. Follow the procedures in Signing for Certificate-Based Secure Boot to generate the signed GBL image file with the bootloader certificate key pair in step 1. The bootloader certificate version (--cert-version in the util gencert command) in this signed GBL image file must be higher than the certificate version in SE flash (Certificates and Key Pairs for Certificate-Based Secure Boot Examples).

3. Follow the procedures in Generate a GBL Upgrade Image File to upgrade the bootloader with the signed image from step 2. Use the Private Sign Key or existingPrivate Bootloader Key for certificate-based Secure Boot to sign the bootloader GBL upgrade image file if required.

4. (Standard Certificate-Based) Follow the procedures in Signing for Certificate-Based Secure Boot to generate the signed application image file with the Private Bootloader Key in step 1.

5. (Advanced Certificate-Based) Follow the procedures in Signing for Certificate-Based Secure Boot to generate the signed application image file with the Private Bootloader Key in step 1. The application certificate version (--cert-version in the util gencert command) in this signed application image file must be equal to or higher than the bootloader certificate version in step 2 (Certificates and Key Pairs for Certificate-Based Secure Boot Examples).

   The user should generate a new ECDSA-P256 application certificate key pair if the Private Application Key for the application certificate is compromised.

6. Follow the procedures in Generate a GBL Upgrade Image File to upgrade the application with the signed image from step 4 or 5. Use the Private Sign Key or Private Bootloader key in step 1 for certificate-based Secure Boot to sign the application GBL upgrade image file if required.

Upgrade to Secure Boot with RTSL#

The following procedures describe upgrading Series 2 devices deployed in the field without Secure Boot to Secure Boot with RTSL.

1. (Recommended) Upgrade SE firmware to the latest version if available. See the Gecko Bootloader Operation - Secure Engine Upgrade section in UG266/Silicon Labs Gecko Bootloader User's Guide for GSDK 4.0 and Higher.

2. Follow the procedures in AppBuilder or Bootloader-core Software Component to prepare an unsigned GBL image with the required Secure Bootconfiguration for the application firmware.

3. Follow the procedures in Generate Key and Signing to generate the ECDSA-P256 Sign Key pair for Secure Boot. The key pairs for the bootloader certificate and application certificate (advanced) are required if using Signing for Certificate-Based Secure Boot.

4. Follow steps 1 to 2 in SE Manager Key Provisioning Platform Example if this HSEGBL Decryption Key option is selected. Use the Public Sign Key in step 3 and follow steps 1 to 3 in SE Manager Key Provisioning Platform Example to generate an unsigned image. Use this image to create an application GBL upgrade image file.

5. The original GBL (application Secure Boot is disabled) boots into the unsigned SE Manager Key Provisioning Platform Example after upgrading the application with the image file in step 4.

6. Follow steps 5 to 8 in SE Manager Key Provisioning Platform Example to install the Public Sign Key to SE OTP and GBL Decryption Key (optional) to HSE OTP. Press SPACE instead of ENTER in step 9 to BYPASS the programming of the Secure Boot configuration in SE OTP.

     . Press ENTER to initialize SE OTP for secure boot configuration or press SPACE to skip.
     . SE manager deinitialization... SL_STATUS_OK (cycles: 5 time: 0 us)

   Note:

   • Programming the Public Sign Key to the top page of the main flash (not included in this example) is required for the VSE device ECDSA-P256-SHA256 Secure Boot.

   • Programming the GBL Decryption Key to the top page of the main flash (not included in this example) is required if the default storage option for GBL Decryption Key is selected and the Require encrypted firmware upgrade files option is enabled in step 2.

7. Follow the signing procedures in Signing for ECDSA-P256-SHA256 Secure Boot or Signing for Certificate-Based Secure Boot (Bootloader Image File section, skip the Secure Boot configuration for the bootloader) with the required key(s) generated in step 3 to sign the unsigned GBL image generated from step 2. Use this signed image to create a bootloader GBL upgrade image file.

8. Follow the signing procedures in Generate a GBL Upgrade Image File (Application Image File section) with the required key(s) generated in step 3 to sign the unsigned application image generated from step 4. Use this signed image to create an application GBL upgrade image file.

   Note: For the application bootloader with storage, the user can generate a single GBL upgrade image file for signed images from steps 7 and 8.

9. The Secure Boot in SE OTP is not yet enabled, so FSB does not verify the signature when upgrading to the signed GBL in step 7. The updated GBL (application Secure Boot enabled) verifies the signature when upgrading or booting to the signed SE Manager Key Provisioning Platform Example in step 8.

10. Follow steps 9 to 10 (use SPACE to skip previous steps for OTP key programming) in SE Manager Key Provisioning Platform Example to program the required Secure Boot configuration in SE OTP for signed GBL.

11. Update a signed custom application firmware to replace the signed SE Manager Key Provisioning Platform Example used for Secure Boot with RTSL upgrade.

Note:

• Refer to the "Enabling Secure Boot RTSL on Series 2 Devices" section (either Standalone Bootloaders or Application Bootloaders with Storage) in UG266/Silicon Labs Gecko Bootloader User's Guide for GSDK 4.0 and Higher for details.

• The SE Manager Key Provisioning Platform Example used here is just for reference. The user can modify or write a new application to automate the processes for the Secure Boot with RTSL upgrade.

• If the Require signed firmware upgrade files option is enabled in step 2, the GBL upgrade image files from steps 8 and 11 must be signed.

• If the Require encrypted firmware upgrade files option is enabled in step 2, the GBL upgrade image files from steps 8 and 11 must be encrypted. And the GBL Decryption Key for the corresponding option in GBL must be in place.

Recover Devices when Secure Boot Fails#

If a Secure Boot process fails (meaning firmware image at device starting address validation fails), the only way to recover is to flash a correctly signed image.

The following table describes the different debug lock scenarios on recovering the Secure Boot failure device.

Note: The error code in the Boot status of examples below depends on boot failure caused by the host image (GBL).

The following procedures describe how to recover the Secure Boot failure device from the lock states below.

• Unlocked

• Standard debug locked

• Secure debug locked

1. Follow the procedure in Signing for ECDSA-P256-SHA256 Secure Boot or Signing for Certificate-Based Secure Boot to generate a correctly signed GBL.

2. (Unlocked) Run the security status command to get the boot status.

   commander security status --device EFR32MG21A010F1024 --serialno 440048205

   SE Firmware version : 1.2.9
   Serial number       : 000000000000000014b457fffe045afd
   Debug lock          : Disabled
   Device erase        : Enabled
   Secure debug unlock : Disabled
   Tamper status       : Not OK
   Secure boot         : Enabled
   Boot status         : 0x12 - Failed: Error while checking signature of host firmware
   DONE

   Run the flash command to flash the correctly signed image (like bootloader-uart-xmodem.s37). If a failed Secure Boot is detected, the device will be erased before flashing the new image.

   commander flash bootloader-uart-xmodem.s37 --device EFR32MG21A010F1024 --serialno 440048205

   WARNING: Failed secure boot detected. Issuing a mass erase before flashing to recover the device...
   Parsing file bootloader-uart-xmodem.s37...
   Writing 16384 bytes starting at address 0x00000000
   Comparing range 0x00000000 - 0x00003FFF (16 KiB)
   Programming range 0x00000000 - 0x00001FFF (8 KiB)
   Programming range 0x00002000 - 0x00003FFF (8 KiB)
   DONE

3. (Standard debug locked) Run the security status command to get the boot status.

   commander security status --device EFR32MG21A010F1024 --serialno 440048205

   SE Firmware version : 1.2.9
   Serial number       : 000000000000000014b457fffe045afd
   Debug lock          : Enabled
   Device erase        : Enabled
   Secure debug unlock : Disabled
   Tamper status       : Not OK
   Secure boot         : Enabled
   Boot status         : 0x12 - Failed: Error while checking signature of host firmware
   DONE

   Run the security erasedevice command to unlock the device.

   commander security erasedevice --device EFR32MG21A010F1024 --serialno 440048205

   Successfully erased device
   DONE

   Note: Issue a power-on or pin reset to complete the unlock process.

   Run the flash command to flash the correctly signed image (like bootloader-uart-xmodem.s37). If a failed Secure Boot is detected, the device will be erased before flashing the new image.

   commander `flash` bootloader-uart-xmodem.s37 --device EFR32MG21A010F1024 --serialno 440048205

   WARNING: Failed secure boot detected. Issuing a mass erase before flashing to recover the device...
   Parsing file bootloader-uart-xmodem.s37...
   Writing 16384 bytes starting at address 0x00000000
   Comparing range 0x00000000 - 0x00003FFF (16 KiB)
   Programming range 0x00000000 - 0x00001FFF (8 KiB)
   Programming range 0x00002000 - 0x00003FFF (8 KiB)
   DONE

4. (Secure debug locked) Run the security status command to get the boot status.

   commander security status --device EFR32MG21A010F1024 --serialno 440048205

   SE Firmware version : 1.2.9
   Serial number       : 0000000000000000000d6ffffe0a3a5f
   Debug lock          : Enabled
   Device erase        : Disabled
   Secure debug unlock : Enabled
   Tamper status       : Not OK
   Secure boot         : Enabled
   Boot status         : 0x12 - Failed: Error while checking signature of host firmware
   DONE

   Run the security unlock command to unlock the device with the debug unlock token.

   commander security unlock --device EFR32MG21A010F1024 --serialno 440048205

   Unlocking with unlock payload:
   C:/Users/<username>/AppData/Local/SiliconLabs/commander/SecurityStore/device_0000000000000000000d6ffffe0a3a5f/challenge_020fc3cc9e492088d06d75d71b7aabfe/unlock_payload_0000000000111110.bin
   Secure debug successfully unlocked
   DONE

   Run the flash command with the --noreset option to flash the correctly signed image (like bootloader-uart-xmodem.s37).

   commander flash --noreset bootloader-uart-xmodem.s37 --device EFR32MG21A010F1024 --serialno 440048205

   Parsing file bootloader-uart-xmodem.s37...
   Writing 16384 bytes starting at address 0x00000000
   Comparing range 0x00000000 - 0x00003FFF (16 KiB)
   Erasing range 0x00000000 - 0x00003FFF (2 sectors, 16 KiB)
   Programming range 0x00000000 - 0x00001FFF (8 KiB)
   Programming range 0x00002000 - 0x00003FFF (8 KiB)
   DONE

   Note: The --noreset option prevents the device from returning to the secure debug lock state before flashing.

5. Run the security status command to check the boot status. The example below is an unlocked device.

   commander security status --device EFR32MG21A010F1024 --serialno 440048205

   SE Firmware version : 1.2.9
   Serial number       : 000000000000000014b457fffe045afd
   Debug lock          : Disabled
   Device erase        : Enabled
   Secure debug unlock : Disabled
   Tamper status       : OK
   Secure boot         : Enabled
   Boot status         : 0x20 - OK
   DONE