nRF Secure Immutable Bootloader

Requirements
Overview
Configuration
- FEM support
Building and running
- Building and running using Visual Studio Code
- Testing
Dependencies

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.

Requirements 

The sample supports the following development kits:

Hardware platforms	PCA	Board name	Build target
nRF9160 DK	PCA10090	nrf9160dk_nrf9160	`nrf9160dk_nrf9160`
nRF5340 DK	PCA10095	nrf5340dk_nrf5340	`nrf5340dk_nrf5340_cpuapp`
nRF52 DK	PCA10040	nrf52dk_nrf52832	`nrf52dk_nrf52832`
nRF52840 DK	PCA10056	nrf52840dk_nrf52840	`nrf52840dk_nrf52840`
nRF52833 DK	PCA10100	nrf52833dk_nrf52833	`nrf52833dk_nrf52833`
nRF21540 DK	PCA10112	nrf21540dk_nrf52840	`nrf21540dk_nrf52840`

Overview 

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

Locks 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.
Selects 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.
Verifies 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.
Boots 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.
Shares 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:

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, regenerate it or use another public key.
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

Using the Actions View in nRF Connect for VS Code extension:

Go to the Actions View.

Move the cursor over the Flash action.

Click Erase And Flash To Board on the right side of the Flash action.

Using the Visual Studio Code Command Palette:

Open the Visual Studio Code Command Palette.

Type Erase and Flash to Board and select the highlighted option.

Flash memory layout 

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

B0 - Contains the bootloader sample.
Provision - Stores the provisioned data.
S0 - Defines one of the two potential storage areas for the second stage bootloader.
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:

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:

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 ECDSA-p256 key type for validating the next image in the boot chain.

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.

To set the counter value of an application, build it 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.

Configuration 

See Configuring your application for information about how to permanently or temporarily change the configuration.

FEM support 

You can add support for the nRF21540 front-end module to this sample by using one of the following options, depending on your hardware:

Build the sample for one board that contains the nRF21540 FEM, such as nrf21540dk_nrf52840.
Manually create a devicetree overlay file that describes how FEM is connected to the nRF5 SoC in your device. See Set devicetree overlays for different ways of adding the overlay file.
Provide nRF21540 FEM capabilities by using a shield, for example the nRF21540 EK shield that is available in the nRF Connect SDK. In this case, build the project for a board connected to the shield you are using with an appropriate variable included in the build command. This variable instructs the build system to append the appropriate devicetree overlay file. For example, to build the sample from the command line for an nRF52833 DK with the nRF21540 EK attached, use the following command within the sample directory:
```
west build -b nrf52833dk_nrf52833 -- -DSHIELD=nrf21540_ek
```
This command builds the application firmware. See Programming nRF21540 EK for information about how to program when you are using a board with a network core, for example nRF5340 DK.

Each of these options adds the description of the nRF21540 FEM to the devicetree. See Working with RF front-end modules for more information about FEM in the nRF Connect SDK.

To add support for other front-end modules, add the respective devicetree file entries to the board devicetree file or the devicetree overlay file.

Building and running 

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

To build the sample with Visual Studio Code, follow the steps listed on the Building nRF Connect SDK application quick guide page in the nRF Connect for VS Code extension documentation. See Building and programming an application for other building and programming scenarios and Testing and debugging an application for general information about testing and debugging in the nRF Connect SDK.

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 the development time and potential issues with this route, 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 Visual Studio Code 

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, complete the following steps:

Create a private key in PEM format.
Enable the nRF Secure Immutable Bootloader through Kconfig as follows:
1. Select Kconfig in the Actions View to open the nRF Kconfig tab.
2. Expand Modules > nrf > Nordic nRF Connect > Bootloader and set Use Secure Bootloader to enable CONFIG_SECURE_BOOT.
3. Expand Use Secure Bootloader. Under Private key PEM file (CONFIG_SB_SIGNING_KEY_FILE), enter the path to the private key that you created.
  
  You can also modify other additional configuration options, but that is not recommended. 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. You can use the Search modules bar in nRF Kconfig to find these options. These options allow you to define the signing command.
4. Click Save.
Select Build in the Actions View to start the build process. The build process creates two images, one for the bootloader and one for the application, and merges them.
Select Flash in the Actions View 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.

Dependencies 

This sample uses the following nRF Connect SDK libraries:

It uses the following sdk-nrfxlib libraries: