BLE Secure DFU Bootloader

This example requires one of the following SoftDevices: S112, S113, S132, S140

Important: Before you run this example, make sure to program the SoftDevice.

The BLE Secure DFU Bootloader example uses the Bootloader and DFU modules to implement a bootloader with secure Device Firmware Update (DFU) functionality.

The example bootloader accepts images that contain a new bootloader, SoftDevice, application, or any combination of these. To protect the target device against malicious attackers trying to impersonate the rightful sender of the firmware update, the init packet of the firmware package must be signed.

Configuration parameters

There are certain configuration parameters available in the sdk_config file through which you can configure the Secure DFU Bootloader. For details on editing the SDK configurations, see SDK configuration header file.

• NRF_BL_DFU_INACTIVITY_TIMEOUT_MS
• NRF_BL_DFU_CONTINUATION_TIMEOUT_MS
• NRF_BL_APP_CRC_CHECK_SKIPPED_ON_GPREGRET2
• NRF_BL_APP_CRC_CHECK_SKIPPED_ON_SYSTEMOFF_RESET
• NRF_BL_DFU_ENTER_METHOD_BUTTON
• NRF_BL_DFU_ENTER_METHOD_BUTTON_PIN
• NRF_BL_DFU_ENTER_METHOD_PINRESET
• NRF_BL_DFU_ENTER_METHOD_GPREGRET
• NRF_BL_DFU_ENTER_METHOD_BUTTONLESS
• NRF_BL_WDT_MAX_SCHEDULER_LATENCY_MS
• NRF_BL_FW_COPY_PROGRESS_STORE_STEP
• NRF_BL_DFU_ALLOW_UPDATE_FROM_APP
• NRF_DFU_TRANSPORT_ANT
• NRF_DFU_ANT_RF_FREQ (only for ANT transport)
• NRF_DFU_ANT_DEV_TYPE (only for ANT transport)
• NRF_DFU_ANT_CHANNEL_PERIOD (only for ANT transport)
• NRF_DFU_ANT_MTU (only for ANT transport)
• NRF_DFU_ANT_EVT_HANDLER_PRIO (only for ANT transport)
• NRF_DFU_ANT_BUFFERS_OVERRIDE (only for ANT transport)
• NRF_DFU_ANT_BUFFERS (only for ANT transport)
• NRF_DFU_TRANSPORT_BLE
• NRF_DFU_BLE_ADV_NAME (only for BLE transport)
• NRF_DFU_BLE_ADV_INTERVAL (only for BLE transport)
• NRF_DFU_BLE_MIN_CONN_INTERVAL (only for BLE transport)
• NRF_DFU_BLE_MAX_CONN_INTERVAL (only for BLE transport)
• NRF_DFU_BLE_CONN_SUP_TIMEOUT_MS (only for BLE transport)
• NRF_DFU_BLE_BUFFERS_OVERRIDE (only for BLE transport)
• NRF_DFU_BLE_BUFFERS (only for BLE transport)
• NRF_DFU_PROTOCOL_FW_VERSION_MSG
• NRF_DFU_PROTOCOL_VERSION_MSG
• NRF_DFU_APP_DOWNGRADE_PREVENTION
• NRF_DFU_HW_VERSION
• NRF_DFU_REQUIRE_SIGNED_APP_UPDATE
• NRF_DFU_SINGLE_BANK_APP_UPDATES
• NRF_DFU_APP_DATA_AREA_SIZE
• NRF_DFU_SAVE_PROGRESS_IN_FLASH
• NRF_DFU_IN_APP
• NRF_DFU_SERIAL_USB_RX_BUFFERS (only for USB transport)
• NRF_DFU_SERIAL_UART_USES_HWFC (only for UART transport)
• NRF_DFU_SERIAL_UART_RX_BUFFERS (only for UART transport)

Setup

Depending on the target board and SoftDevice, you can find the source code and the project file of the example in one of the following folders:

• <InstallFolder>\examples\dfu\secure_bootloader\pca10040_s132_ble
• <InstallFolder>\examples\dfu\secure_bootloader\pca10040e_s112_ble
• <InstallFolder>\examples\dfu\secure_bootloader\pca10056_s140_ble
• <InstallFolder>\examples\dfu\secure_bootloader\pca10056e_s112_ble
• <InstallFolder>\examples\dfu\secure_bootloader\pca10100_s113_ble
• <InstallFolder>\examples\dfu\secure_bootloader\pca10100_s140_ble

Button assignments - in addition to those defined in BSP BLE Button Assignments:

• Button 4: Holding this button during startup makes the device enter DFU mode.

Testing

You can either create your own firmware package for testing or use one of the provided packages that are located in subfolders of <InstallFolder>\examples\dfu\secure_dfu_test_images. The provided packages have been generated using a private key that corresponds to the default public key in the project. This public key must not be used in production.

The following is the naming convention for the hex and zip files that you can use in this example:

• Application update:
  • ble\nrf528xx\ble_app_buttonless_dfu_with_bonds_s1xx.zip
  • ble\nrf528xx\ble_app_buttonless_dfu_without_bonds_s1xx.zip
  • ble\nrf528xx\ble_app_buttonless_dfu_with_bonds_s1xx_with_setting_page.hex
  • ble\nrf528xx\ble_app_buttonless_dfu_without_bonds_s1xx_with_setting_page.hex
  • ble\nrf528xx\hrs_application_s1xx.hex
  • ble\nrf528xx\hrs_application_s1xx.zip
• SoftDevice:
  • ble\nrf528xx\softdevice_s1xx.hex
  • ble\nrf528xx\softdevice_s1xx.zip
• Bootloader:
  • ble\nrf528xx\bootloader_secure_ble_debug_with_bonds_s1xx.hex
  • ble\nrf528xx\bootloader_secure_ble_debug_with_bonds_s1xx.zip
  • ble\nrf528xx\bootloader_secure_ble_debug_without_bonds_s1xx.hex
  • ble\nrf528xx\bootloader_secure_ble_debug_without_bonds_s1xx.zip
• SoftDevice + Bootloader + Application:
  • ble\nrf528xx\sd_s1xx_bootloader_buttonless_with_setting_page_dfu_secure_ble_debug_with_bonds.hex
  • ble\nrf528xx\sd_s1xx_bootloader_buttonless_with_setting_page_dfu_secure_ble_debug_without_bonds.hex

Test the BLE Secure DFU Bootloader application by performing the following steps:

1. If you want to create your own firmware package for testing:
   1. Create a private key for the example. See Working with keys for instructions, and Signature verification for more information about signatures.

      Note

      The private key should be kept with very limited distribution, because it can be used to create valid firmware images to update your device. It must never be lost, because without the key, there is no way to create new DFU images.

   2. Create a public key in code format and store it in a file named dfu_public_key.c. See Working with keys for instructions.
   3. Copy the dfu_public_key.c file to the project folder, replacing the existing file.
   4. Prepare a firmware package (in zip format) that you want to use. See Creating a firmware package with nrfutil for instructions.
   5. Generate a HEX file that contains the Bootloader Settings page. See the nrfutil documentation for instructions.
2. Install micro-ecc. This library is required for the Cryptography library - nrf_crypto, which is used in the BLE Secure DFU Bootloader example.
3. Compile the bootloader.
4. If you generated a bootloader settings HEX file, use mergehex (part of the nRF5x Command Line Tools) to merge the bootloader HEX file and the bootloader settings HEX file.
5. Program the HEX file. See Programming the bootloader.
6. Make sure that the device enters DFU mode. DFU mode is indicated by LED 3 being lit. If a valid application is installed on the device, hold Button 4 during startup to prevent the bootloader from starting the application and force it to enter DFU mode instead.
7. Use either nrfutil or a mobile app to perform the DFU:
   • With nrfutil:
     1. Connect a Development Kit board to your computer. This board serves as connectivity IC to do the DFU on the device that contains the DFU bootloader.
     2. Enter the following command to start the DFU process over BLE, where package.zip is the name of the firmware package that you want to upload: nrfutil dfu ble -ic NRF52 -f -pkg package.zip
     3. nrfutil will ask you to choose a serial port. The port you specify must correspond to the port of the development kit that you connected.
     4. To choose a specific target device, use nrfutil's -n or -a options. For more information, enter nrfutil dfu ble --help.
   • With the nRF Toolbox app (Android: 1.17 or later, iOS: 4 or later) or the nRF Connect app (4.4 or later, Android only at this time):
     1. Transfer the zip firmware package that you want to upload to the mobile device:
        • On iOS: Connect the mobile device to your computer and open iTunes. Select the mobile device and then Apps > nRF Toolbox (or nRF Connect). Then you can drag and drop a file directly into the application's internal storage. Alternatively, send an email attachment to the app from the mobile device itself. See the app's documentation for more information.
        • On Android: Connect the mobile device to your computer. Enable file transfer between the computer and the device and copy the zip file into a folder of your choice.
     2. Use the nRF Toolbox or nRF Connect app to select a target device and a zip package and to start the process.
8. Observe that the device resets and runs the new application, bootloader, or SoftDevice.