Secure OTA DFU#

Introduction#

The following article shows how to securely upgrade Bluetooth application OTA (over-the-air) using signed+encrypted upgrade files. The process is tested with Bluetooth SDK v2.13.0.0.

Gecko Bootloader#

The Gecko Bootloader is a common bootloader for all Silicon Labs protocol stacks. It can load applications from different sources (internal flash, external flash, UART, SPI, over-the-air) using different protocols (XMODEM, BGAPI, EZSP SPI, Bluetooth, and so on.). It can be configured in a number of ways and its capabilities depend on the current configuration. This document shows how you can use it for loading a new application into the device sent over a Bluetooth connection.

Security Features#

The Gecko Bootloader has three security features:

  • Authenticated (signed) upgrade file

  • Encrypted upgrade file

  • Secure Boot

Upgrade files are in a custom GBL (Gecko Bootloader) format. An authenticated upgrade file means that an electronic signature is attached to the GBL file. The signature is produced with a public-private key pair. The public key is stored in the device, while the private key is kept secret by the manufacturer. The signature ensures that the upgrade file is from a trusted source.

An encrypted upgrade file means that the content of the GBL file is encrypted to protect against eavesdroppers.

Secure Boot means that a signature is attached to the firmware image (.s37) before it is packed into upgrade file formal (.gbl). Note that this differs from an authenticated upgrade file, as authenticated upgrade file means that a signature is attached to the upgrade file after the image was packed into GBL format. A signed image file (secure boot) ensures that the image was not modified since last boot and that it is from a trusted source. This is checked at every boot. Upgrade file authentication is only checked while upgrading.

The following content shows how to use these security features.

OTA DFU#

Over-The-Air Device Firmware Upgrade (OTA DFU) means that the device firmware can be updated via a Bluetooth connection.

To enable Bluetooth OTA update, the target device must be programmed with an appropriate Gecko Bootloader configuration and additionally with any Bluetooth application that supports OTA.

A Bluetooth application developed with Silicon Labs Bluetooth SDK comprises two parts.

Before Bluetooth SDK v2.7 the two parts are

  • The Bluetooth stack + Supervisor (provided as precompiled binary code), referred to as Stack from now on

  • The user application, referred to as App from now on

Since Bluetooth SDK v2.7 the two parts are

  • The Apploader (provided as precompiled binary code), referred to as Apploader from now on

  • The Bluetooth stack (provided as precompiled library) + user application, referred to as Application from now on

The OTA functionality is built into the Supervisor and into the Apploader code. If the device is restarted in DFU mode, the Supervisor/Apploader is started instead of the user application. This makes it possible to perform OTA update without any involvement from the user application.

For the sake of simplicity in the following sections, the new DFU process will be discussed involving Apploader, but the old process is very similar. For older SDK versions, find the OTA DFU documentation in Simplicity Studio after installing the SDK.

The only requirement for the user application is for a way to trigger a reboot into DFU mode. Reboot into DFU mode can be triggered in a variety of ways. It is up to the application developer to decide which is most applicable. Most of the example applications provided in the Bluetooth SDK already have OTA support built into the code. In these examples, the DFU mode is triggered through the Silicon Labs OTA service that is included as part of the application’s GATT database. In the end to restart the device in OTA mode, use the following API: gecko_cmd_system_reset(2).

The following processes are OTA DFU:

  • Partial OTA: In this case only the user application is upgraded. In this case,

  1. The device is restarted in OTA mode, and the Apploader is started.11

  2. The Apploader overwrites the old Application code with the new one. (Note: Slot0 is used temporarily to store the GBL headers during this upload process.)22

  • Full OTA: In this case the Apploader code is upgraded as well. Because the running code cannot overwrite itself, this process is done in 3 steps:

    1. The device is restarted in OTA mode and the Apploader is started.33

    2. The new Apploader code is uploaded into Slot0. This process is handled by the Apploader itself. Note: on 256kB devices Slot0 is in the user application area, which means that the Application is overwritten.44

    3. Upon reset the bootloader copies the new Apploader code over the old one (extracting the binary from the stored GBL files).55

    4. The new Apploader overwrites the old Application code with the new one. (Note: Slot0 is used temporarily to store the GBL headers during this upload process.)66

For more details regarding OTA DFU using the Apploader, seeAN1086: Using the Gecko Bootloader with the Silicon Labs Bluetooth® Applications.

For more details about the legacy OTA DFU process, see AN1045: Bluetooth ® Over-the-Air Device Firmware Update for EFR32xG1 and BGM11x Series Products.

Create and Build Bootloader#

Create Bootloader Project#

Since Gecko SDK Suite 1.0 / Bluetooth SDK 2.3.0, the Gecko Bootloader is included in the Bluetooth SDK. A number of predefined configurations are available to help customers easily create new Bootloader projects for different purposes. Different bootloader configurations are recommended for different devices:

  • For 256kB devices, use Bluetooth in-place OTA DFU Bootloader configuration.

  • For 512kB devices, use Bluetooth in-place OTA DFU Bootloader or Internal Storage Bootloader (single image on 512kB device).

  • For 1024kB devices, use Bluetooth in-place OTA DFU Bootloader or Internal Storage Bootloader (single image on 1MB device).

  • You can also use an SPI Flash Storage Bootloader (single image) if you have an SPI flash connected to the device. However, in this case it is better to implement an application uploader, see Implementing OTA firmware update in user application and Uploading images to internal/external flash using OTA DFU.

To create a new bootloader project:

  1. Open Simplicity Studio and select your device in the Devices or Debug Adapters tab.

  2. Check the Preferred SDK at the top of the main window.

  3. Click the New Project button.

  4. Select the appropriate Gecko Bootloader application type, click Next, (e.g., Internal Storage Bootloader), click Next.

  5. Check your device and choose a toolchain. Click Finish.

ss1ss1

Add Security Features#

After the bootloader project is created, the Application Builder automatically opens up. To add security features, do the following:

  1. Open the Plugins tab.

  2. Click on Bootloader Core.

  3. On the right side tick the checkboxes:

    • Require signed firmware upgrade files.

    • Require encrypted firmware upgrade files.

    • Enable secure boot.

  4. Click Generate in the upper right corner.

ss2ss2

Build Bootloader#

After the bootloader code was generated by the AppBuilder, build your project:

  1. Click on the build icon.

Generate Security Keys#

To use the security features of the Gecko Bootloader, generate the encryption and signing keys. These keys must be then written to the EFR32 device. The encryption key is used with the GBL file for secure firmware update. The signing keys are used both with the GBL file for secure firmware update and to sign the application image for Secure Boot.

You can create security keys with Simplicity Commander:

  1. For ease of use, add the Commander path (C:\SiliconLabs\SimplicityStudio\v4\developer\adapter_packs\commander) to the Path environment variable in your OS.

  2. Generate signing keys with the following command in command line: commander gbl keygen --type ecc-p256 --outfile app-sign-key.pem This creates three files: app-sign-key.pem, app-sign-key.pem.pub and app-sign-key.pem-token.txt. The first contains the private key (keep it secret), the other two contain the public key which has to be flashed to the device.

  3. Generate encryption key with the following command in command line: commander gbl keygen --type aes-ccm --outfile app-encrypt-key.txt This creates one file named app-encrypt-key.txt

Flash Security Keys#

Write the two token files containing the encryption key and public key as manufacturing tokens to the device.

  1. Issue the following command:

    commander flash --tokengroup znet --tokenfile app-encrypt-key.txt --tokenfile app-sign-key.pem-tokens.txt

Create and Build Basic Application#

Because OTA DFU is not fully implemented in the Bootloader, a minimal Bluetooth application has to be created and flashed to the device along with the Bootloader to support the upgrade.

Create Basic Application Project#

To create a basic application that supports OTA DFU, do the following:

  1. Open Simplicity Studio and select your device in the Devices or Debug Adapters tab.

  2. Check the Preferred SDK at the top of the main window.

  3. Click New Project button.

  4. Select SOC - Empty sample application, click Next.

  5. Name your project, click Next.

  6. Check your device and choose toolchain. Click Finish.

emptyempty

Build Application#

The application code is automatically generated after the project was created. The SoC – Empty sample application contains everything needed for OTA support (OTA service and characteristics + code to support to restart the device in DFU mode + Apploader image). To build the application, do the following:

  1. Click on the build icon.

Sign the Application Image#

Because Secure Boot was enabled in the bootloader, only signed application images can be booted.

To use OTA DFU, sign the Apploader and the Application parts of the image separately because they will be updated separately.

To add a signature to the Apploader and to the Application image, do the following:

  1. Copy app-sign-key.pem (from the folder in which you ran the commander gbl keygen command) into your project.

  2. Run the create_bl_files.bat batch file found in your project, which will create the signed GBL files into the output_gbl folder.

Upload Bootloader and Basic Application#

After both Bootloader image and Application image are ready, upload them to the device:

  1. Copy the ...-combined.s37 file from the output folder (named after the compiler) of the bootloader project to the output_gbl folder of the Bluetooth application project. Note: The ...-combined.s37 file contains the full bootloader – while other output files in the bootloader project contain only the second stage of the bootloader.

  2. Merge the Bootloader image with the Apploader and the Application images.

    • commander convert bootloader-storage-internal-single-combined.s37 apploader-signed.gbl application-signed.gbl --outfile bootloader+stack+app.s37

  3. Open Simplicity Commander GUI by starting commander.exe.

  4. Connect to the Adapter.

  5. Connect to the Target Device.

  6. Select Flash tab.

  7. Flash bootloader+stack+app.s37 to the device.1010

Create and Build Upgrade Application#

Create Application Project#

Create the application to upgrade the device to, for example the Thermometer sample application. Similarly to the creation of the Basic Application, do the following:

  1. Open Simplicity Studio and select your device in the Devices or Debug Adapters tab.

  2. Check the Preferred SDK at the top of the main window.

  3. Click New Project button.

  4. Select Bluetooth SDK, click Next.

  5. Select the latest installed SDK, click Next.

  6. Select SOC - Thermometer sample application, click Next.

  7. Name your project, click Next.

  8. Check your device and choose toolchain. Click Finish.

Build Application#

The application code is automatically generated after the project was created. To build the application, do the following:

  1. Click on the build icon.

Create Signed and Encrypted Upgrade Files from the Image#

The bootloader accepts upgrade images in .gbl format. To create .gbl files from the image and sign/encrypt it, do the following:

  1. Copy app-sign-key.pem and app-encrypt-key.txt into your project.

  2. Run create_bl_files.bat.

  3. Check upgrade files in output_gbl folder within your project.

Upgrade your Device#

Now your device can be upgraded OTA from the basic application to the upgrade application. For this you need another device which will send the new firmware to the target device via Bluetooth. In this example, a smartphone will be used for this purpose.

  1. Download and install EFR Connect app to your smartphone.

  2. Create a new folder under /SiliconLabs_BGApp/OTAFiles/ on your smartphone. E.g. call it my_app.

  3. Open the output_gbl folder in your project.

  4. Copy the upgrade files from your computer to your smartphone. If you use Android, copy the upgrade files into /SiliconLabs_BGApp/OTAFiles/my_app folder. If you use iOS, upload the upgrade files to iCloud.

    • Copy apploader-signed-encrypted.gbl and application-signed-encrypted.gbl

  5. Open the EFR Connect app.

  6. Select the Bluetooth Browser.

  7. Find your device. The basic app advertises itself as Empty Example. Because there might be other devices advertising around you with the same name, place your smartphone close to your device and find the one with the highest RSSI.

  8. Click on your device to connect to it.

  9. Open the context menu in the upper right corner and select OTA.

  10. Choose Full OTA.

  11. Select my_app folder, then select stack-signed-encrypted.gbl OR apploader-signed-encrypted.gbl as “stack” and app-signed-encrypted.gbl OR application-signed-encrypted.gbl as “app”.

  12. Click OTA.

  13. After the upload is finished, you should see your device advertising itself as Thermometer Example in the Bluetooth Browser.

1111 1212