Secure Binary 4.0#

SB 4.0 is an evolution/combination of the SB 3.1 and AHAB v2 format. Most notable change is the inclusion of PQC authentication mechanism.

Example of use nxpimage: nxpimage sb40 export "sb40_config.yaml

Supported commands#

List of SB 4.0 supported commands#

Command	Command Description	mcxn556s	mcxn557s
erase	Performs a flash erase of the given address range. The erase will be rounded up to the sector size.	YES	YES
load	If set, then the data to write immediately follows the range header. The length field contains the actual data length	YES	YES
execute	Address is the jump-to address. No further processing of SB after jump, ROM do not expect to return.	YES	YES
call	Address is address to jump. However, the state machine should expect a return to the next statement to continue processing the SB file	NO	NO
programFuses	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.	YES	YES
programIFR	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	YES	YES
writeIFR	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	NO	NO
loadCMAC	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.	YES	YES
copy	Used for copying data from one place to another. 32 bytes fixed size.	YES	YES
loadHashLocking	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.	YES	YES
loadKeyBlob	Wrapped key blob immediately follows the range key blob header. The length field contains the actual data length.	YES	YES
configureMemory	Configure memory.	YES	YES
fillMemory	Used for filling of the memory range by same repeated int32 pattern.	YES	YES
checkFwVersion	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	YES	YES
reset	Resets the target	YES	YES
checkLifecycle	Checks if the device is in the expected lifecycle state. The command will fail if the device is not in the specified state.	NO	NO

Supported configuration options#

SecureBinary4 for mcxn556s, Revision: a0#

SecureBinary4 for mcxn556s, Revision: a0 JSON schema

Open it in full page

SecureBinary4 for mcxn556s, Revision: a0 YAML configuration template

# =============================  sb40 Configuration template for mcxn556s, Revision: a0.  ==============================

# ======================================================================================================================
#                                                 == General Options ==
# ======================================================================================================================
# -------------------------------------===== The chip family name [Required] =====--------------------------------------
# Description: NXP chip family identifier.
family: mcxn556s
# -----------------------------------------===== MCU revision [Optional] =====------------------------------------------
# Description: Revision of silicon. The 'latest' name, means most current revision.
# Possible options: <a0, latest>
revision: a0
# ======================================================================================================================
#                                           == Secure Binary v4.0 Settings ==
# ======================================================================================================================
# ---------------------------------===== Part Common Key [Conditionally required] =====---------------------------------
# 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
# ---------------------------------------===== 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
# ------------------------------------------===== Description [Optional] =====------------------------------------------
# Description: Description up to 16 characters, longer will be truncated. Stored in SB4.0 manifest.
description: My SB file
# ======================================================================================================================
#                                                  == Basic Settings ==
# ======================================================================================================================
# -----------------------------------------===== SB4 filename [Required] =====------------------------------------------
# Description: Generated SB4 container filename.
containerOutputFile: my_new.sb4
# ======================================================================================================================
#                                 == AHAB Container format to add to ECC + PQC sign. ==
# ======================================================================================================================
# ----------------------------------------===== Image version. [Optional] =====-----------------------------------------
# Description: Image version used for rollback protection in SB4 format. While primarily designed for dual boot
# scenarios in MBI (Master Boot Image), this field provides security through firmware version validation.

# **Rollback Protection Mechanism:**
# The image version must be equal to or greater than the version stored in fuses or PFR (Protected Flash Region) to
# ensure proper rollback protection.

# **Version Calculation (e.g., MCXN556s series):**
# The firmware version is calculated by combining the image version with the fuse version:

# fw_version = (imageVersion << 8) | fuse_version


# **Validation Process:**
# During rollback protection, the calculated firmware version is checked against the 'SECURE_FW_VERSION' value stored in
# the CFPA (Customer Field Programmable Area) page. Only firmware with versions equal to or higher than the stored value
# will be allowed to execute.
imageVersion: 0
# -----------------------------------===== Super Root Key (SRK) set [Required] =====------------------------------------
# Description: Defines which set is used to authenticate the container.
# Possible options: <oem, nxp>
srk_set: oem
# -------------------------------------------===== Used SRK [Required] =====--------------------------------------------
# Description: Which key from SRK set is being used.
used_srk_id: 0
# -----------------------------------------===== Fuse version [Optional] =====------------------------------------------
# Description: The value must be equal or greater than the version stored in fuses or PFR to provide proper rollback
# protection. For example, on the MCXN556s series, the fuse version is used for rollback protection, where it is joined
# with the image version to create a firmware version 'fw_version = (imageVersion << 8) | (fuse_version)'. During
# rollback protection, the firmware version is checked against 'SECURE_FW_VERSION' in the CFPA page.
fuse_version: 0
# -------------------------------------===== AHAB container signer [Optional] =====-------------------------------------
# Description: Signature provider configuration in format 'type=<identifier>;<key1>=<value1>;<key2>=<value2>' or a
# private key used for sign the container header. Header can be signed by SRK. The referenced SRK must not have been
# revoked.
signer: type=file;file_path=my_prv_key.pem
# ---------------------===== AHAB container signer for second signature (PQC only) [Optional] =====---------------------
# Description: Signature provider configuration in format 'type=<identifier>;<key1>=<value1>;<key2>=<value2>' or a
# private key used for second sign (PQC only) of the container header. Header can be signed by SRK. The referenced SRK
# must not have been revoked.
signer_#2: type=file;file_path=my_prv_key.pem

# ======================================================================================================================
#                                         == Configuration of AHAB SRK table ==
# ======================================================================================================================
# -------------------------------------------===== SRK Table [Required] =====-------------------------------------------
# Description: SRK (Super Root key) table definition.
srk_table:
  # -------------------------------------------===== CA Flag [Optional] =====-------------------------------------------
  # Description: CA Flag is used by HAB to indicate if the SRK is allowed to sign other keys
  flag_ca: false
  # ---------------------------------===== Super Root Key (SRK) table [Required] =====----------------------------------
  # Description: Table containing the used SRK records. All SRKs must be of the same type. Supported signing algorithms
  # are: RSA-PSS, ECDSA, Dilithium or SM2. Supported hash algorithms: sha256, sha384, sha512, sha3_256, sha3_384,
  # sha3_512, sm3. Supported key sizes/curves: prime256v1, sec384r1, sec512r1, rsa2048, rsa4096, dilithium3, sm2.
  # Certificate may be of Certificate Authority. Dilithium algorithms are supported just in new type of AHAB container
  srk_array:
    - my_srk_public_key0.pub
    - my_srk_public_key1.pub
    - my_srk_public_key2.pub
    - my_srk_public_key3.pub

  # ====================================================================================================================
  #                  == Configuration of AHAB SRK table in case that the double signing (ECC + PQC) ==
  # ====================================================================================================================
  # --------------------------------------===== Second SRK Table [Optional] =====---------------------------------------
  srk_table_#2:
    # ------------------------------------------===== CA Flag [Optional] =====------------------------------------------
    # Description: CA Flag is used by HAB to indicate if the SRK is allowed to sign other keys
    flag_ca: false
    # --------------------------------===== Super Root Key (SRK) table [Required] =====---------------------------------
    # Description: Table containing the used SRK Dilithium records. All SRKs must be of the same type. Supported signing
    # algorithms are: Dilithium level 3. Supported hash algorithms: sha3_256, sha3_384, sha3_512. Certificate may be of
    # Certificate Authority.
    srk_array:
      - my_srk_public_key0.pub
      - my_srk_public_key1.pub
      - my_srk_public_key2.pub
      - my_srk_public_key3.pub

# ======================================================================================================================
#              == Optional configuration of AHAB Container Certificate (if not used, erase the section) ==
# ======================================================================================================================
# -------------------------------------===== The AHAB certificate [Optional] =====--------------------------------------
# Description: The file that contains AHAB certificate. It could be used already prepared binary form signed by SRK, or
# it is possible to use configuration YAML file of certificate and the AHAB export process it will export it itself.
certificate: my_ahab_certificate.bin
# ======================================================================================================================
#                                   == Secure Binary v3.1 / v4.0 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 13 options. ==
  #        Options [erase, load, execute, programFuses, programIFR, loadCMAC, copy, loadHashLocking, loadKeyBlob,
  #                                 configureMemory, fillMemory, checkFwVersion, reset]
  # ====================================================================================================================

  #  =========================== [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:
      # -----------------------------------------===== Address [Required] =====-----------------------------------------
      # Description: Address of memory block to be erased.
      address: 0
      # ------------------------------------------===== Size [Required] =====-------------------------------------------
      # Description: Size of memory block to be erased.
      size: 4096
      # ----------------------------------------===== 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:
      # -----------------------------------------===== 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
      # -----------------------------===== Data to be loaded [Conditionally required] =====-----------------------------
      # Description: The data to be loaded, it could be defined in following formats:
      #   - 32-bit value. Value will be converted to binary in little endian format. Example: '0xB38AA899' or '0b111000'
      #   - Array of 32-bit binary values delimited by comma to be loaded. Individual 32-bit values will be stored in
      # little endian format. Example: 0x1234, 0x5678, 0, 12345678
      #   - List of integers passed as an array.
      #   - Path to binary file. Example: my_binary.bin
      data: my_binary.bin
      # ------------------------------------===== Data compression [Optional] =====-------------------------------------
      # Description: Use LZMA compression of date before loading onto the target
      compress: false
      # ----------------------------===== Memory sector size [Conditionally required] =====-----------------------------
      # Description: Size of memory sector where data should be loaded.
      sectorSize: 8192

  #  =========================== [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:
      # -----------------------------------------===== 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:
      # -----------------------------------------===== 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:
      # -----------------------------------------===== Address [Required] =====-----------------------------------------
      # Description: Address of IFR region to be programmed.
      address: 0
      # ------------------------------------===== Data to be loaded [Optional] =====------------------------------------
      # Description: The data to be loaded, it could be defined in following formats:
      #   - 32-bit value. Value will be converted to binary in little endian format. Example: '0xB38AA899' or '0b111000'
      #   - Array of 32-bit binary values delimited by comma to be loaded. Individual 32-bit values will be stored in
      # little endian format. Example: 0x1234, 0x5678, 0, 12345678
      #   - List of integers passed as an array.
      #   - Path to binary file. Example: my_binary.bin
      data: my_binary.bin

  #  =========================== [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:
      # -----------------------------------------===== 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] ============================
    # -------------------------------------------===== Copy [Required] =====--------------------------------------------
    # Description: Used for copying data from one place to another. 32 bytes fixed size.
    copy:
      # --------------------------------------===== Address From [Required] =====---------------------------------------
      # Description: Address of memory block to be copied.
      addressFrom: 0
      # -------------------------------------===== Memory ID From [Optional] =====--------------------------------------
      # Description: ID of memory block to be copied.
      memoryIdFrom: 0
      # ------------------------------------------===== Size [Required] =====-------------------------------------------
      # Description: Size of memory block to be copied.
      size: 4096
      # ---------------------------------------===== Address To [Required] =====----------------------------------------
      # Description: Address of memory where block to be copied.
      addressTo: 536870912
      # --------------------------------------===== Memory ID To [Optional] =====---------------------------------------
      # Description: ID of memory block where to be copied.
      memoryIdTo: 0

  #  =========================== [Example of possible configuration: #7 , 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:
      # -----------------------------------------===== 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: #8 , erase if not used] ============================
    # ---------------------------------------===== Load Key Blob [Required] =====---------------------------------------
    # Description: Wrapped key blob immediately follows the range key blob header. The length field contains the actual
    # data length.
    loadKeyBlob:
      # -----------------------------------------===== Offset [Required] =====------------------------------------------
      # Description: Offset of the key blob.
      offset: 0
      # -------------------------------------===== Wrapping key ID [Required] =====-------------------------------------
      # Description: Wrapping ID of key blob.
      # Possible options: <NXP_CUST_KEK_INT_SK, NXP_CUST_KEK_EXT_SK>
      wrappingKeyId: 0
      # ---------------------------------------===== Binary file [Required] =====---------------------------------------
      # Description: Binary file to be loaded.
      file: my_keyblob.bin
      # ---------------------------------===== Key Blob as plain text [Optional] =====----------------------------------
      # Description: Indicates whether key is provided as plaintext or not. If it's in plaintext this option also
      # indicates whether it's as binary or hex
      # Possible options: <no, bin, hex>
      plainInput: no

  #  =========================== [Example of possible configuration: #9 , erase if not used] ============================
    # -------------------------------------===== Configure memory [Required] =====--------------------------------------
    # Description: Configure memory.
    configureMemory:
      # -----------------------------------------===== Address [Required] =====-----------------------------------------
      # Description: Configuration address.
      configAddress: 0
      # ----------------------------------------===== Memory ID [Optional] =====----------------------------------------
      # Description: ID of memory block to be configured.
      memoryId: 0

  #  =========================== [Example of possible configuration: #10 , erase if not used] ===========================
    # ----------------------------------------===== Fill memory [Required] =====----------------------------------------
    # Description: Used for filling of the memory range by same repeated int32 pattern.
    fillMemory:
      # -----------------------------------------===== 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: #11 , 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:
      # --------------------------------===== 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: <none, nonsecure, secure, radio, snt, bootloader, radio_lp>
      counterId: secure

  #  =========================== [Example of possible configuration: #12 , erase if not used] ===========================
    # -------------------------------------------===== Reset [Required] =====-------------------------------------------
    # Description: Resets the target
    reset: {}

SecureBinary4 for mcxn557s, Revision: a0#

SecureBinary4 for mcxn557s, Revision: a0 JSON schema