nRF Secure Immutable Bootloader

The nRF Secure Immutable Bootloader (NSIB), previously also known as B0 or b0, is a secure bootloader built and maintained by Nordic Semiconductor. It is specifically tailored for the immutable bootloader architecture of a secure boot chain. It can verify and boot a second-stage bootloader or application while providing a persistent and reliable Root of Trust (RoT).

See Secure bootloader chain for more information about the full bootloader chain.

Note

Currently, this immutable bootloader does not support firmware updates over the SMP transport for either an upgradable bootloader or an application. If the application using this bootloader requires SMP-based firmware updates, such as Bluetooth LE DFU, include MCUboot as a second-stage bootloader.

Overview

The sample accomplishes a simple and reliable Root of Trust (RoT) for a secure boot chain as follows:

  1. Locking the flash memory.

    To enable the RoT, the bootloader sample locks the flash memory that contains both the sample bootloader and its configuration. Locking is done using the hardware that is available on the given architecture.

    For additional details on locking, see the Hardware flash write protection driver.

  2. Selecting the next stage in the boot chain.

    The next stage in the boot chain can either be another bootloader or an application.

    When you enable the nRF Secure Immutable Bootloader and use MCUboot as the second stage bootloader, there are two slots in which the second stage bootloader can reside. The second stage bootloader in each slot has a version number associated with it, and the bootloader sample selects the second stage bootloader with the highest version number.

    For information about creating a second stage bootloader, see Adding an upgradable bootloader.

  3. Verify the next stage in the boot chain.

    After selecting the image to boot next, the bootloader sample verifies the image validity using one of the provisioned public key hashes.

    The image for the next boot stage has a set of metadata associated with it. This metadata contains the full public key corresponding to the private key used to sign the firmware. The bootloader sample checks the public key against a set of provisioned keys.

    Note

    To save space, only the hashes of the provisioned keys are stored and only the hashes of the keys are compared. See Provisioning for more details.

    If the public key in the metadata matches one of the valid provisioned public key hashes, the image is considered valid.

    All public key hashes at lower indices than the matching hash are permanently invalidated at this point. This means that images can no longer be validated with those public keys. For example, if an image is successfully validated with the public key at index 2, public keys 0 and 1 are invalidated. You can use this mechanism to decommission broken keys.

    If the public key does not match any remaining valid provisioned hashes, the validation process fails.

  4. Booting the next stage in the boot chain.

    After verifying the next boot stage, the bootloader sample uninitializes all peripherals that it used and boots the next boot stage.

  5. Sharing the cryptographic library through an external API.

    The bootloader sample shares some of its functionality through an external API (EXT_API).

    For more information on the process, see the bl_crypto.h file. For more information on EXT_API, see External APIs.

Provisioning

The public key hashes are not compiled with the source code of the bootloader sample. Instead, they must be stored in a separate memory region through a process called provisioning.

By default, the bootloader sample automatically generates and provisions public key hashes directly into the bootloader HEX file, based on the specified private key and the additional public keys.

Alternatively, to facilitate the manufacturing process of a device using the bootloader sample, it is possible to decouple this process and program the sample HEX file and the HEX file containing the public key hashes separately. If you choose to do so, use the Python scripts located in the scripts/bootloader folder to create and provision the keys manually.

In both cases, the bootloader access the provisioned data using the Bootloader storage library.

OTP Regions

On some SoCs/SiPs, such as the nRF9160 or nRF5340, the provisioned data is held in the one-time programmable (OTP) region in the User Information Configuration Registers (UICR). OTP regions are special regions of the flash memory that only allow flash memory writes in half-word lengths, and only when the target half-word is the value 0xFFFF.

Because of these design constraints, the following limitations apply:

  1. The public key hash cannot contain half-words with the value 0xFFFF, as such hashes cannot be guaranteed to be immutable when placed in the OTP region. Therefore, the bootloader refuses to boot if any hash contains a half-word with the value 0xFFFF. If your public key hash is found to contain this value, please regenerate it or use another public key.

  2. Writing data to an OTP region means that provisioned data cannot be written more than once to the target device. When programming images that contain flash memory content for this region, such as the bootloader or images containing the bootloader, the UICR must first be erased.

Note

On the nRF9160 and nRF5340, the UICR can only be erased by erasing the entire flash memory.

To perform a full erase, do the following:

Using west:

west flash -d *build_directory* --erase

Using nrfjprog:

nrfjprog -f NRF91 --eraseall

Flash memory layout

The flash memory layout is defined by the samples/bootloader/pm.yml file, which establishes four main partitions:

  1. B0 - Contains the bootloader sample.

  2. Provision - Stores the provisioned data.

  3. S0 - Defines one of the two potential storage areas for the second stage bootloader.

  4. S1 - Defines the other one of the two potential storage areas for the second stage bootloader.

The default location for placing the next image in the boot chain is S0. This would result, for example, in a flash memory layout like the following, when using the nrf52840dk_nrf52840 board:

B0 flash memory layout

B0 flash memory layout

Pre-signed variants

When the application uses a second-stage upgradable bootloader, S1 can be programmed with the same image as S0 when compiled with the CONFIG_BUILD_S1_VARIANT option. This ensures that the upgradable bootloader can be executed from either slot chosen by the nRF Secure Immutable Bootloader.

When the upgradable bootloader is upgraded, the new image is placed into the slot not in use by the current version of the bootloader. At boot, the nRF Secure Immutable Bootloader checks the version information for the images in S0 and S1 and boots the one with the highest version. See Monotonic Counter for more information about versioning.

If this image is faulty and cannot be booted, the other partition will always hold a working image that is booted instead.

When using the nrf52840dk_nrf52840 board, this would produce a flash memory layout like the following:

B0 flash memory layout with MCUboot

B0 flash memory layout with MCUboot

Note

In devices that store provisioning data in an OTP region, the Provision area does not appear in the flash memory layout. See OTP Regions for more information.

Signature Keys

This bootloader supports the following key types for validating the next image in the boot chain:

  • ECDSA-p256

By default, when not explicitly defined, a private/public key pair is generated during the build. However, these key pairs should only be used during development. See Using development keys for more details.

For details on creating and using custom signature keys with this sample, refer to the Adding a custom signature key file documentation.

Monotonic Counter

Firmware versions using the nRF Secure Immutable Bootloader are kept in the form of a monotonic counter, a hardware-based version that prevents booting an image with a lower counter value. Counter values are kept as slots in the flash memory, with each new counter value occupying a new slot. See CONFIG_SB_MONOTONIC_COUNTER for more details.

An application’s counter value can be set by building using the CONFIG_FW_INFO_FIRMWARE_VERSION option:

CONFIG_FW_INFO_FIRMWARE_VERSION=<integer>

The number of slots available for counter values depends on the type of nRF devices being used. For default values and ranges, see CONFIG_SB_NUM_VER_COUNTER_SLOTS.

Requirements

The sample supports the following development kits:

Hardware platforms

PCA

Board name

Build target

nRF9160 DK

PCA10090

nrf9160dk_nrf9160

nrf9160dk_nrf9160ns

nRF5340 DK

PCA10095

nrf5340dk_nrf5340

nrf5340dk_nrf5340_cpuapp

nrf5340dk_nrf5340_cpuappns

nRF52840 DK

PCA10056

nrf52840dk_nrf52840

nrf52840dk_nrf52840

nRF52 DK

PCA10040

nrf52dk_nrf52832

nrf52dk_nrf52832

Building and running

This sample can be found under samples/bootloader in the nRF Connect SDK folder structure.

See Building and programming a sample application for information about how to build and program the application.

The bootloader sample should be included as a child image in a multi-image build, rather than being built stand-alone. While it is possible to build this sample by itself and merge it into other application images, this process is not officially supported by the nRF Connect SDK. To reduce development time and potential issues with this route, you should let the existing nRF Connect SDK infrastructure for multi-image builds handle the integration.

For building and running this sample with an application, see Adding an immutable bootloader.

Building and running using SEGGER Embedded Studio

This sample can be found under samples/bootloader in the nRF Connect SDK folder structure.

To add the bootloader sample as a child image to your application:

  1. Create a private key in PEM format.

  2. Enable the nRF Secure Immutable Bootloader by running menuconfig on your application:

    1. Select Project > Configure nRF Connect SDK project.

    2. Go to Modules > Nordic nRF Connect > Bootloader and set Use Secure Bootloader to enable CONFIG_SECURE_BOOT.

    3. Under Private key PEM file (CONFIG_SB_SIGNING_KEY_FILE), enter the path to the private key that you created. If you choose to run the sample with default debug keys, you can skip this step.

      There are additional configuration options that you can modify, but it is not recommended to do so. The default settings are suitable for most use cases.

      Note

      If you need more flexibility with signing, or if you do not want the build system to handle your private key, choose CONFIG_SB_SIGNING_CUSTOM, and also specify CONFIG_SB_SIGNING_COMMAND and CONFIG_SB_SIGNING_PUBLIC_KEY. These options allow you to define the signing command.

    4. Click Configure.

  3. Select Build -> Build Solution to compile your application. The build process creates two images, one for the bootloader and one for the application, and merges them.

  4. Select Build -> Build and Run to program the resulting image to your device.

Testing

See Testing the bootloader chain for testing the expected runtime behavior of this bootloader when built with an application.