KW45xx and K32W1xx Load NBU image#

The KW45 product family is a low-power, highly secure, single-chip wireless MCU.

It is a three-core platform, with one core for each specific domain: application, security (EdgeLock), and radio. The radio domain features a Cortex-M3, Bluetooth LE Unit with dedicated flash. The memories integrated in radio consist of Bluetooth LE controller stack and radio drivers. KW45 boot ROM supports remote firmware update for the main flash (CM-33) and radio flash (CM-3).

This application note focuses on the secure update of KW45 radio firmware by loading Narrow Band Unit (NBU) image to KW45xx/K32W1xx device.

1. Prerequisites#

SPSDK is needed with examples extension. pip install spsdk[examples] (Please refer to the installation documentation.)

Let’s prepare also workspace and variables.

# Initialization cell
from spsdk.utils.jupyter_utils import YamlDiffWidget

# This env variable sets colored logger output to STDOUT
%env JUPYTER_SPSDK=1
# Set a magic for command execution and echo
%alias execute echo %l && %l
%alias_magic ! execute

env: JUPYTER_SPSDK=1
Created `%!` as an alias for `%execute`.

2. Root of Trust Keys Preparation#

To perform secure update, you need to establish a Root of Trust (RoT) at the beginning, which will be used later to perform update.

The EVK board (KW45xx-EVK/K32W1xx) comes with pre-burned fuses containing the Root Key Table Hash (RKTH) in a fuse called CUST_PROD_OEMFW_AUTH_PUK, provided by NXP. The corresponding keys are stored in the EVK_keys folder.
Generally, you can generate Root of Trust Keys (RoTKs)/Super Root Keys (SRKs) and optionally an Image Signing Key (ISK). To generate these keys, use the nxpcrypto application (refer to How-to-get-keys-using-nxpcrypto). By default, the script creates 4 RoTKs and 1 ISK. At least one RoTK is mandatory.
Based on the loaded keys, a Root Key Table Hash (RKTH) value is calculated. This RKTH should be loaded into the device fuses, which is why the keys cannot be changed for the device once set.

3. Meaning of Container Key Blob Encryption Key#

On EVK boards Container Key Blob EncryptionKey (SB3KDK) is already burnt into fuse called CUST_PROD_OEMFW_ENC_SK, you can find these values in evk_keys folder.

4. Prepare SB3.1 configuration file#

In order to generate SB3.1 file, npximage tool is used. The nxpimage tool generates the SB3.1 file according to the configuration file. Let’s create a template for SB3.1. Modify examples according your needs.

4.1 Preparing Certificate Block v2.1#

In order to create signed MBI the certification block that keeps the RoT info must be prepared.

In our case we have already prepared certification block to simplify the example (see Certification block configuration v2.1)
To learn how to create a certificate blok check the whole example is presented in dedicated notebook (see How-to-get-cert-block).

In our case, we modified items in the SB3.1 configuration template. The ready and working template you can find in inputs folder (see inputs-folder).

# Get difference of template and user YAML configuration
YamlDiffWidget("inputs/kw45xx_sb31.diffc").html

nxpimage sb31 get-template -f kw45b41z8 -o workspace/sb31_template.yaml --force 
Creating workspace/sb31_template.yaml template file.

Configuration Differences

# =============================  Secure Binary v3.1 Configuration template for kw45b41z8.  =============================

# ======================================================================================================================
#                                                 == General Options ==                                                 
# ======================================================================================================================
# -------------------------------------===== The chip family name [Required] =====--------------------------------------
# Description: NXP chip family identifier.
# Possible options: 
# mcxw716a, mcxw716c, mimxrt798s, rw610, rw612>
family: kw45b41z8
# -----------------------------------------===== MCU revision [Optional] =====------------------------------------------
# Description: Revision of silicon. The 'latest' name, means most current revision.
# Possible options: 
revision: latest
# ======================================================================================================================
#                                                  == Basic Settings ==                                                 
# ======================================================================================================================
# ---------------------------------------===== Firmware version. [Optional] =====---------------------------------------
# Description: Value compared with Secure_FW_Version monotonic counter value stored in protected memory (MCU specific).
# If value is lower than value in protected memory, then is image rejected (rollback protection).
firmwareVersion: 0
# -----------------------------------------===== SB3 filename [Required] =====------------------------------------------
# Description: Generated SB3 container filename.
containerOutputFile: my_new.sb3 Add path to our generated SB3 container
containerOutputFile: ../workspace/sb3.sb3
# ======================================================================================================================
#                                              == Image Signing Settings ==                                             
# ======================================================================================================================
# --------------------------===== Main Certificate private key [Conditionally required] =====---------------------------
# Description: Main Certificate private key used to sign certificate. It can be replaced by signProvider key.
signPrivateKey: main_prv_key.pem Add path to your private key file for signing
signPrivateKey: ../../_data/keys/evk_keys/RoT_key0_secp384r1_kw45xx.pem
# -------------------------------===== Signature Provider [Conditionally required] =====--------------------------------
# Description: Signature provider configuration in format 'type=;=;='.
signProvider: type=file;file_path=my_prv_key.pem This is removed, because we are using private key in this example
# ======================================================================================================================
#                                              == Certificate Block V2.1 ==                                             
# ======================================================================================================================
# -----------------------------===== Certificate Block binary/config file [Required] =====------------------------------
# Description: Path to certificate block binary or config file.
certBlock: cert_block.yaml Add path to the configuration file containing certificates or path to binary block
certBlock: cert_block_kw45_secure.yaml
# ======================================================================================================================
#                                           == Secure Binary v3.1 Settings ==                                           
# ======================================================================================================================
# ----------------------------------------===== Part Common Key [Optional] =====----------------------------------------
# Description: Path to PCK/NPK 256 or 128 bit key in plain hex string format or path to binary file or hex string.
containerKeyBlobEncryptionKey: my_pck.txt Add path to Part Common Key
containerKeyBlobEncryptionKey: ../../_data/keys/evk_keys/sb3kdk.txt
# ----------------------------------===== Enable NXP Container format [Optional] =====----------------------------------
# Description: Internal usage only, used for generating SB files with NXP content e.g. provisioning firmware, etc...
isNxpContainer: false
# ---------------------------------------===== KDK access rights [Optional] =====---------------------------------------
# Description: Accepted values are 0, 1, 2 and 3. Value used as key properties for key derivation process, more details
# can be found in CSSv2 manual.
# Possible options: <0, 1, 2, 3>
kdkAccessRights: 0 Set KDK access rights
kdkAccessRights: 3
# ---------------------------------===== Container configuration word [Optional] =====----------------------------------
# Description: Flag value in SB3.1 manifest, not used by silicons with LPC55S3x ROM. Value can be kept 0, or it can be
# removed from the configuration file.
containerConfigurationWord: 0
# ------------------------------------------===== Description [Optional] =====------------------------------------------
# Description: Description up to 16 characters, longer will be truncated. Stored in SB3.1 manifest.
description: This is description of generated SB file. Add description, which will be stored in Stored in SB3.1 manifest
description: 384_none_nbu_only
# ======================================================================================================================
#                                       == Secure Binary v3.1 Commands Settings ==                                      
# ======================================================================================================================
# ----------------------------------------===== SB3.1 Commands [Required] =====-----------------------------------------
# Description: Secure Binary v3.1 commands block, list of all possible options - Modify it according to your application
commands:
  -

  # ====================================================================================================================
  #                                          == List of possible 9 options. ==                                          
  #   Options [erase, load, execute, programFuses, programIFR, loadCMAC, loadHashLocking, fillMemory, checkFwVersion]   
  # ====================================================================================================================

  #  =========================== [Example of possible configuration: #0 , erase if not used] ============================
    # -------------------------------------------===== Erase [Required] =====-------------------------------------------
    # Description: Performs a flash erase of the given address range. The erase will be rounded up to the sector size.
    erase: Erase the flash before programming
  - erase:
      # -----------------------------------------===== Address [Required] =====-----------------------------------------
      # Description: Address of memory block to be erased.
      address: 0
      address: 0x48800000
      # ------------------------------------------===== Size [Required] =====-------------------------------------------
      # Description: Size of memory block to be erased.
      size: 4096
      size: 0x30000
      # ----------------------------------------===== Memory ID [Optional] =====----------------------------------------
      # Description: ID of memory block to be erased.
      memoryId: 0

  #  =========================== [Example of possible configuration: #1 , erase if not used] ============================
    # -------------------------------------------===== Load [Required] =====--------------------------------------------
    # Description: If set, then the data to write immediately follows the range header. The length field contains the
    # actual data length
    load: Load
the binary file to the flash
  - load:
      # -----------------------------------------===== Address [Required] =====-----------------------------------------
      # Description: Address of memory block to be loaded.
      address: 0
      address: 0x48800000
      # ----------------------------------------===== Memory ID [Optional] =====----------------------------------------
      # Description: ID of memory block to be loaded.
      memoryId: 0
      # --------------------------------------===== Binary file. [Optional] =====---------------------------------------
      # Description: Binary file to be loaded.
      file: my_binary.bin
      file: kw45b41_nbu_ble_1_9_14_1.xip
      # -------------------------------------===== Binary values. [Optional] =====--------------------------------------
      # Description: 32-bit binary values delimited by comma to be loaded.
      values: 0x1234, 0x5678, 0, 12345678
      # --------------------------------------===== Binary value [Optional] =====---------------------------------------
      # Description: Binary value to be loaded. Value will be converted to binary little endian format.
      value: '0xB38AA899'
      # -------------------------------------===== Authentication [Optional] =====--------------------------------------
      # Description: If authentication is not used, just omit this option or set 'none'.
      # Possible options: 
      authentication: cmac

  #  =========================== [Example of possible configuration: #2 , erase if not used] ============================
    # ------------------------------------------===== Execute [Required] =====------------------------------------------
    # Description: Address is the jump-to address. No further processing of SB after jump, ROM do not expect to return.
    execute: We
do not use this command
      # -----------------------------------------===== Address [Required] =====-----------------------------------------
      # Description: Jump-to address to start execute code.
      address: 0

  #  =========================== [Example of possible configuration: #3 , erase if not used] ============================
    # ---------------------------------------===== Program Fuses [Required] =====---------------------------------------
    # Description: Address is OTP index of fuses to be programmed (Check the reference manual for more information).
    # Values is a comma separated list of 32bit values.
    programFuses: We do not use this command
      # -----------------------------------------===== Address [Required] =====-----------------------------------------
      # Description: OTP Index of fuses to be programmed. Depends on the chip ROM.
      address: 0
      # --------------------------------------===== Binary values [Required] =====--------------------------------------
      # Description: 32bit binary values delimited by comma or one 32 bit integer to be programmed.
      values: 0x1234, 0x5678, 0, 12345678

  #  =========================== [Example of possible configuration: #4 , erase if not used] ============================
    # ----------------------------------------===== Program IFR [Required] =====----------------------------------------
    # Description: The startAddress will be the address into the IFR region, length will be in number of bytes to write
    # to IFR region. The data to write to IFR region at the given address will immediately follow the header
    programIFR: We do not use this command
      # -----------------------------------------===== Address [Required] =====-----------------------------------------
      # Description: Address of IFR region to be programmed.
      address: 0
      # ---------------------------------------===== Binary file [Optional] =====---------------------------------------
      # Description: Binary file to be programmed.
      file: my_binary.bin
      # --------------------------------------===== Binary value [Optional] =====---------------------------------------
      # Description: Binary value to be programmed, at least 4 bytes. Value will be converted to binary little endian
      # format.
      value: '0xB38AA899'
      # -------------------------------------===== Binary values. [Optional] =====--------------------------------------
      # Description: 32-bit binary values delimited by comma to be programmed.
      values: 0x1234, 0x5678, 0, 12345678

  #  =========================== [Example of possible configuration: #5 , erase if not used] ============================
    # -----------------------------------------===== Load CMAC [Required] =====-----------------------------------------
    # Description: If set, then the data to write immediately follows the range header. The length field contains the
    # actual data length. ROM is calculating cmac from loaded data and storing on address known by ROM decided based on
    # startAddress.
    loadCMAC: Load the binary file to the flash
      # -----------------------------------------===== Address [Required] =====-----------------------------------------
      # Description: Address of memory block to be CMAC loaded.
      address: 0
      # ----------------------------------------===== Memory ID [Optional] =====----------------------------------------
      # Description: ID of memory block to be CMAC loaded.
      memoryId: 0
      # ---------------------------------------===== Binary file [Required] =====---------------------------------------
      # Description: Binary file to be loaded.
      file: my_cmac_binary.bin

  #  =========================== [Example of possible configuration: #6 , erase if not used] ============================
    # ----------------------------------===== Load with HASH locking [Required] =====-----------------------------------
    # Description: If set, then the data to write immediately follows the range header. The length field contains the
    # actual data length. ROM is calculating hash of the data and storing the value in the last 64 bytes of the loaded
    # data, which are reserved for it.
    loadHashLocking: Load the binary file to the flash
      # -----------------------------------------===== Address [Required] =====-----------------------------------------
      # Description: Address of memory block to be loaded.
      address: 0
      # ----------------------------------------===== Memory ID [Optional] =====----------------------------------------
      # Description: ID of memory block to be loaded.
      memoryId: 0
      # ---------------------------------------===== Binary file [Required] =====---------------------------------------
      # Description: Binary file to be loaded.
      file: my_hashlocking_binary.bin

  #  =========================== [Example of possible configuration: #7 , erase if not used] ============================
    # ----------------------------------------===== Fill memory [Required] =====----------------------------------------
    # Description: Used for filling of the memory range by same repeated int32 pattern.
    fillMemory: We do not use this command
      # -----------------------------------------===== Address [Required] =====-----------------------------------------
      # Description: Address of memory block to be filled.
      address: 0
      # ------------------------------------------===== Size [Required] =====-------------------------------------------
      # Description: Size of memory block to be filled.
      size: 4096
      # -----------------------------------------===== Pattern [Required] =====-----------------------------------------
      # Description: Pattern which will be used to fill memory.
      pattern: 2779096485

  #  =========================== [Example of possible configuration: #8 , erase if not used] ============================
    # ----------------------------------===== Check firmware version [Required] =====-----------------------------------
    # Description: Checks FW version value specified in command for specified counter ID. FW version value in command
    # must be greater than value programmed in OTP to be accepted, otherwise rollback is detected and receive SB fails
    checkFwVersion: We do not use this command
      # --------------------------------===== Value - Firmware version [Required] =====---------------------------------
      # Description: Firmware version to be compared.
      value: 1
      # ---------------------------------------===== Counter ID [Required] =====----------------------------------------
      # Description: ID of FW counter to be checked.
      # Possible options: 
      counterId: secure

# Copyright 2024 NXP
#
# SPDX-License-Identifier: BSD-3-Clause
# =============================  Secure Binary v3.1 Configuration template for kw45b41z8.  =============================

# ======================================================================================================================
#                                                 == General Options ==                                                 
# ======================================================================================================================
# -------------------------------------===== The chip family name [Required] =====--------------------------------------
# Description: NXP chip family identifier.
# Possible options: 
# mcxw716a, mcxw716c, mimxrt798s, rw610, rw612>
family: kw45b41z8
# -----------------------------------------===== MCU revision [Optional] =====------------------------------------------
# Description: Revision of silicon. The 'latest' name, means most current revision.
# Possible options: 
revision: latest
# ======================================================================================================================
#                                                  == Basic Settings ==                                                 
# ======================================================================================================================
# ---------------------------------------===== Firmware version. [Optional] =====---------------------------------------
# Description: Value compared with Secure_FW_Version monotonic counter value stored in protected memory (MCU specific).
# If value is lower than value in protected memory, then is image rejected (rollback protection).
firmwareVersion: 0
# -----------------------------------------===== SB3 filename [Required] =====------------------------------------------
# Description: Generated SB3 container filename.
containerOutputFile: ../workspace/sb3.sb3 Add path to our generated SB3 container
# ======================================================================================================================
#                                              == Image Signing Settings ==                                             
# ======================================================================================================================
# --------------------------===== Main Certificate private key [Conditionally required] =====---------------------------
# Description: Main Certificate private key used to sign certificate. It can be replaced by signProvider key.
signPrivateKey: ../../_data/keys/evk_keys/RoT_key0_secp384r1_kw45xx.pem Add path to your private key file for signing
# -------------------------------===== Signature Provider [Conditionally required] =====--------------------------------
# Description: Signature provider configuration in format 'type=;=;='.
# signProvider: type=file;file_path=my_prv_key.pem
# ======================================================================================================================
#                                              == Certificate Block V2.1 ==                                             
# ======================================================================================================================
# -----------------------------===== Certificate Block binary/config file [Required] =====------------------------------
# Description: Path to certificate block binary or config file.
certBlock: cert_block_kw45_secure.yaml Add path to the configuration file containing certificates or path to binary block
# ======================================================================================================================
#                                           == Secure Binary v3.1 Settings ==                                           
# ======================================================================================================================
# ----------------------------------------===== Part Common Key [Optional] =====----------------------------------------
# Description: Path to PCK/NPK 256 or 128 bit key in plain hex string format or path to binary file or hex string.
containerKeyBlobEncryptionKey: ../../_data/keys/evk_keys/sb3kdk.txt Add path to Part Common Key
# ----------------------------------===== Enable NXP Container format [Optional] =====----------------------------------
# Description: Internal usage only, used for generating SB files with NXP content e.g. provisioning firmware, etc...
isNxpContainer: false
# ---------------------------------------===== KDK access rights [Optional] =====---------------------------------------
# Description: Accepted values are 0, 1, 2 and 3. Value used as key properties for key derivation process, more details
# can be found in CSSv2 manual.
# Possible options: <0, 1, 2, 3>
kdkAccessRights: 3 Set KDK access rights
# ---------------------------------===== Container configuration word [Optional] =====----------------------------------
# Description: Flag value in SB3.1 manifest, not used by silicons with LPC55S3x ROM. Value can be kept 0, or it can be
# removed from the configuration file.
containerConfigurationWord: 0
# ------------------------------------------===== Description [Optional] =====------------------------------------------
# Description: Description up to 16 characters, longer will be truncated. Stored in SB3.1 manifest.
description: 384_none_nbu_only Add description, which will be stored in Stored in SB3.1 manifest
# ======================================================================================================================
#                                       == Secure Binary v3.1 Commands Settings ==                                      
# ======================================================================================================================
# ----------------------------------------===== SB3.1 Commands [Required] =====-----------------------------------------
# Description: Secure Binary v3.1 commands block, list of all possible options - Modify it according to your application
commands:

  # ====================================================================================================================
  #                                          == List of possible 9 options. ==                                          
  #   Options [erase, load, execute, programFuses, programIFR, loadCMAC, loadHashLocking, fillMemory, checkFwVersion]   
  # ====================================================================================================================

  #  =========================== [Example of possible configuration: #0 , erase if not used] ============================
    # -------------------------------------------===== Erase [Required] =====-------------------------------------------
    # Description: Performs a flash erase of the given address range. The erase will be rounded up to the sector size.
  - erase: Erase the flash before programming
      # -----------------------------------------===== Address [Required] =====-----------------------------------------
      # Description: Address of memory block to be erased.
      address: 0x48800000
      # ------------------------------------------===== Size [Required] =====-------------------------------------------
      # Description: Size of memory block to be erased.
      size: 0x30000
      # ----------------------------------------===== Memory ID [Optional] =====----------------------------------------
      # Description: ID of memory block to be erased.
      memoryId: 0

  #  =========================== [Example of possible configuration: #1 , erase if not used] ============================
    # -------------------------------------------===== Load [Required] =====--------------------------------------------
    # Description: If set, then the data to write immediately follows the range header. The length field contains the
    # actual data length
  - load: Load
the binary file to the flash
      # -----------------------------------------===== Address [Required] =====-----------------------------------------
      # Description: Address of memory block to be loaded.
      address: 0x48800000
      # ----------------------------------------===== Memory ID [Optional] =====----------------------------------------
      # Description: ID of memory block to be loaded.
      # memoryId: 0
      # --------------------------------------===== Binary file. [Optional] =====---------------------------------------
      # Description: Binary file to be loaded.
      file: kw45b41_nbu_ble_1_9_14_1.xip
      # -------------------------------------===== Binary values. [Optional] =====--------------------------------------
      # Description: 32-bit binary values delimited by comma to be loaded.
      # values: 0x1234, 0x5678, 0, 12345678
      # --------------------------------------===== Binary value [Optional] =====---------------------------------------
      # Description: Binary value to be loaded. Value will be converted to binary little endian format.
      # value: '0xB38AA899'
      # -------------------------------------===== Authentication [Optional] =====--------------------------------------
      # Description: If authentication is not used, just omit this option or set 'none'.
      # Possible options: 
      # authentication: cmac

4.2 SB3.1 generation#

We have created certificates and keys required for the creation of SB3.1 file. Let’s create a SB3.1.

%! nxpimage sb31 export -c inputs/sb31_config.yaml

nxpimage sb31 export -c inputs/sb31_config.yaml 
RKTH: 650d8097079ff27a3e8a2da14781b922fd8295b6c00bfa067f00e87f1a16b8b304bf710d45cbd591e2e24be83183922c
Success. (Secure binary 3.1: workspace/sb3.sb3 created.)

5. Device preparation#

Now it’s time to prepare the device. In this example we will use KW45xx-EVK/K32W1xx board.

Board preparation#

First step is to enter In System Programming (ISP) mode, this could be achieved by 3 scenarios:

Force ISP mode by HW pin
1. Put JP25 to (1-2)
2. Reset the board with SW4 pressed
Force ISP mode by debug mailbox command
- Connect debug probe and use nxpdebugmbox ispmode -m 1 command
Native fall-down in case that no valid application is in chip
- In case that chip has no valid application to boot, the ISP mode is activated natively

Use app nxpdevscan to check if the device is connected to the PC in ISP mode.

In our case, we already have burnt some fuses on EVK. Those KW45xx/K32Wxx EVK boards are distributed from NXP by already burned RoTKH and SB3KDK information as has been already mentioned earlier.

# check if the device is connected and detected by PC
%! nxpdevscan

nxpdevscan 
-------- Connected NXP USB Devices --------

-------- Connected NXP UART Devices --------

Port: COM10
Type: mboot device

-------- Connected NXP SIO Devices --------

-------- Connected NXP UUU Devices --------

# choose com port
UART_CONNECTION = "-p com10"

Send SB3.1 file to device#

Last step is to upload SB3.1 file with NBU image to device. Command blhost receive-sb-file is used to update the image on CM33 flash or radio (CM3) flash via ISP. With this command, a KW45 device receives a secure binary (SB) file, decrypts, authenticates, and programs the image to the target memory.

# uploads SB3.1
%! blhost $UART_CONNECTION receive-sb-file workspace/sb3.sb3

blhost -p com10 receive-sb-file workspace/sb3.sb3 
Sending SB file
Response status = 0 (0x0) Success.

KW45xx and K32W1xx Load NBU image

Contents