AHAB#
AHAB (Advanced High Assurance Boot) is a container format supported on some devices. A configuration file in YAML or JSON is used to instruct nxpimage how the output should look like.
Example of use for export
nxpimage ahab export -c "path\to\config\file.yaml"
Example of use for parse binary AHAB container
nxpimage ahab parse -b "my_ahab_container.bin" -o "path\to_parsed_data"
The full AHAB configuration template could be generated by nxpimage tool “get_template” sub-command for family that supports AHAB, example:
nxpimage ahab get-template -f rt118x -o ./my_config_templates
Supported configuration options#
AHABImage#
Properties#
family(string): Family identifier including the chip revision. If revision is not present, latest revision is used as default. Must be one of:["mx8ulp", "mx93", "mx95", "rt118x"].revision(string): Revision of silicon.image_type(string): The final use of image, this setting is changing the style of offsets in final container. Must be one of:["xip", "non_xip", "serial_downloader", "nand"].target_memory(string): Target memory for AHAB container. Must be one of:["nor", "serial_downloader", "nand_2k", "nand_4k"].output(string, format: file_name): Output AHAB file name.containers(array): The order of containers in the list defines the order in AHAB. Length must be at least 1.Items
One of
object
binary_container(object, required): Binary Container format to add to AHAB image, Typically it could be used to add ELE Firmware.path(string, required): The binary file that contains AHAB “my_binary_container.bin.
object
container(object, required): Configurable Container format to add to AHAB image. This allow to configure all aspects of the AHAB container.srk_set(string, required): Defines which set is used to authenticate the container. Must be one of:["none", "oem", "nxp"].used_srk_id([‘number’, ‘string’], format: number): Which key from SRK set is being used.srk_revoke_mask([‘number’, ‘string’], format: number): Bitmask to indicate which SRKs to revoke. Bit set to 1 means revoke key. Bit 0 = revoke SRK_0, bit 1 = revoke SRK_1 etc.fuse_version([‘number’, ‘string’], format: number, required): The value must be equal or greater than the version stored in fuses to allow loading this container.sw_version([‘number’, ‘string’], format: number, required): Number used by Privileged Host Boot Companion (PHBC) to select between multiple images with same Fuse version field.signing_key(string, format: file): Private key used for sign the container header. Header can be signed by SRK. The referenced SRK must not have been revoked.signature_provider(string): Signature provider configuration in format ‘type=<sp_type>;= ; = ”. The signature provider could be used instead of definition of ‘signing_key’. images(array, required): Array of image entries. Length must be between 1 and 8 (inclusive).Items (object)
image_path(string, format: file, required): Path to image binary (absolute/relative).image_offset([‘number’, ‘string’], format: number, required): Offset in bytes from start of container header to beginning of the image. In case of XiP type of AHAB image, the load_address and entry_point must correspond to this values. Example of setting of load_address - AHAB_IMAGE_ADDRESS+IMAGE_OFFSET=LOAD_ADDRESS. The Booting core images must be located after the other ones.load_address([‘number’, ‘string’], format: number, required): Address the image is written to in memory (absolute address in system memory).entry_point([‘number’, ‘string’], format: number, required): Image entry point (absolute address). Valid only for executable image types.image_type(string, required): Kind of image. Must be one of:["csf", "scd", "executable", "data", "dcd_image", "seco", "provisioning_image", "dek_validation_fcb_chk", "provisioning_data", "executable_fast_boot_image", "v2x_primary", "v2x_secondary", "v2x_rom_patch", "v2x_dummy"].core_id(string, required): Defines the core the image is dedicated for. Not all cores are supported for all families. Must be one of:["cortex-a55", "cortex-m33", "cortex-m7", "cortex-m4", "cortex-m4_1", "cortex-a53", "cortex-a35", "cortex-a72", "seco", "hdmi-tx", "hdmi-rx", "v2x-1", "v2x-2"].is_encrypted(boolean, required): Determines, whether image is encrypted or not.boot_flags([‘number’, ‘string’]): Boot flags controlling SCFW boot.meta_data_start_cpu_id([‘number’, ‘string’], format: number): Resource ID of CPU to be started.meta_data_mu_cpu_id([‘number’, ‘string’], format: number): Resource ID of the MU associated with the CPU.meta_data_start_partition_id([‘number’, ‘string’], format: number): Partition ID of the partition to start.hash_type(string): HASH type of image. All images in the container must have the same HASH type. Must be one of:["sha256", "sha384", "sha512", "sm3"].
srk_table(object): SRK (Super Root key) table definition.flag_ca(boolean): CA Flag is used by HAB to indicate if the SRK is allowed to sign other keys.srk_array(array, required): Table containing the used SRK records. All SRKs must be of the same type. Supported signing algorithms are: RSASSA-PSS, ECDSA or SM2. Supported hash algorithms: sha256, sha384, sha512, sm3. Supported key sizes/curves: prime256v1, sec384r1, sec512r1, rsa2048, rsa4096, sm2. Certificate may be of Certificate Authority. Length must be equal to 4.Items (string, format: file): Path to SRK Key file.
certificate(string, format: file): 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.blob(object): Encryption blob container definition.key_identifier([‘number’, ‘string’], format: number, required): The key identifier that has been used to generate DEK keyblob.dek_key_size([‘number’, ‘string’], format: number, required): Data Encryption key size. Used for AES CBC-MAC (128/192/256 size). Must be one of:[128, 192, 256].dek_key(string, required): Data Encryption key. Used for AES CBC-MAC (128/192/256 size). The HEX format is accepted.dek_keyblob(string, required): Wrapped Data Encryption key. Used for AES CBC-MAC (128/192/256 size). The HEX format is accepted.
# ============================================= AHAB template AHABImage ==============================================
# ======================================================================================================================
# == AHABImage ==
# ======================================================================================================================
# ------------------------------------------===== MCU family [Required] =====-------------------------------------------
# Description: Family identifier including the chip revision. If revision is not present, latest revision is used as
# default.
# Possible options: <mx8ulp, mx93, mx95, rt118x>
family: CHOOSE_FROM_TABLE
# -----------------------------------------===== MCU revision [Optional] =====------------------------------------------
# Description: Revision of silicon
revision: latest
# ----------------------------------===== Target memory [Conditionally required] =====----------------------------------
# Description: Target memory for AHAB container
# Possible options: <nor, serial_downloader, nand_2k, nand_4k>
target_memory: nor
# ---------------------------------------===== Output file name [Required] =====----------------------------------------
# Description: Output AHAB file name
output: generated_ahab.bin
# ------------------------------===== List of containers present in AHAB [Required] =====-------------------------------
# Description: The order of containers in the list defines the order in AHAB.
containers:
-
# ====================================================================================================================
# == List of possible 2 options. ==
# Options [binary_container, container]
# ====================================================================================================================
# ====================================== [Example of possible configuration #0] ======================================
# -----------------------------------===== Binary AHAB container [Required] =====-----------------------------------
# Description: Binary Container format to add to AHAB image, Typically it could be used to add ELE Firmware.
binary_container:
# -----------------------------===== The AHAB container binary file [Required] =====------------------------------
# Description: The binary file that contains AHAB "my_binary_container.bin
path: my_ahab_container.bin
# ====================================== [Example of possible configuration #1] ======================================
# --------------------------------------===== AHAB Container [Required] =====---------------------------------------
# Description: Configurable Container format to add to AHAB image. This allow to configure all aspects of the AHAB
# container.
container:
# --------------------------------===== Super Root Key (SRK) set [Required] =====---------------------------------
# Description: Defines which set is used to authenticate the container.
# Possible options: <none, oem, nxp>
srk_set: oem
# ---------------------------------===== Used SRK [Conditionally required] =====----------------------------------
# Description: Which key from SRK set is being used.
used_srk_id: 0
# -------------------------------------===== SRK revoke mask [Optional] =====-------------------------------------
# Description: Bitmask to indicate which SRKs to revoke. Bit set to 1 means revoke key. Bit 0 = revoke SRK_0, bit
# 1 = revoke SRK_1 etc.
srk_revoke_mask: 0
# --------------------------------------===== Fuse version [Required] =====---------------------------------------
# Description: The value must be equal or greater than the version stored in fuses to allow loading this
# container.
fuse_version: 0
# ------------------------------------===== Software version [Required] =====-------------------------------------
# Description: Number used by Privileged Host Boot Companion (PHBC) to select between multiple images with same
# Fuse version field.
sw_version: 0
# ------------------------===== AHAB container signing key [Conditionally required] =====-------------------------
# Description: Private key used for sign the container header. Header can be signed by SRK. The referenced SRK
# must not have been revoked.
signing_key: my_signing_key.pem
# ----------------------------===== Signature Provider [Conditionally required] =====-----------------------------
# Description: Signature provider configuration in format 'type=<sp_type>;<key1>=<value1>;<key2>=<value2>". The
# signature provider could be used instead of definition of 'signing_key'.
signature_provider: type=file;file_path=my_prv_key.pem
# ================================================================================================================
# == Configuration of AHAB Container images (array of multiple images) ==
# ================================================================================================================
# ---------------------------------------===== Image array [Required] =====---------------------------------------
# Description: Array of image entries.
images:
-
# -------------------------------------===== Image path [Required] =====--------------------------------------
# Description: Path to image binary (absolute/relative).
image_path: my_image.bin
# ---------------------------===== Image offset in AHAB container [Required] =====----------------------------
# Description: Offset in bytes from start of container header to beginning of the image. In case of XiP type
# of AHAB image, the load_address and entry_point must correspond to this values. Example of setting of
# load_address - AHAB_IMAGE_ADDRESS+IMAGE_OFFSET=LOAD_ADDRESS. The Booting core images must be located after
# the other ones
image_offset: '0x4000'
# ------------------------------===== Image destination address [Required] =====------------------------------
# Description: Address the image is written to in memory (absolute address in system memory).
load_address: '0x5000'
# ----------------------------------===== Image entry point [Required] =====----------------------------------
# Description: Image entry point (absolute address). Valid only for executable image types.
entry_point: '0x5000'
# -------------------------------------===== Image type [Required] =====--------------------------------------
# Description: Kind of image.
# Possible options: <csf, scd, executable, data, dcd_image, seco, provisioning_image, dek_validation_fcb_chk,
# provisioning_data, executable_fast_boot_image, v2x_primary, v2x_secondary, v2x_rom_patch, v2x_dummy>
image_type: executable
# ---------------------------------------===== Core ID [Required] =====---------------------------------------
# Description: Defines the core the image is dedicated for. Not all cores are supported for all families.
# Possible options: <cortex-a55, cortex-m33, cortex-m7, cortex-m4, cortex-m4_1, cortex-a53, cortex-a35,
# cortex-a72, seco, hdmi-tx, hdmi-rx, v2x-1, v2x-2>
core_id: cortex-m33
# ----------------------------------===== Image encryption [Required] =====-----------------------------------
# Description: Determines, whether image is encrypted or not.
is_encrypted: false
# -------------------------------------===== Boot flags [Optional] =====--------------------------------------
# Description: Boot flags controlling SCFW boot.
boot_flags: 0
# ------------------------------------===== Start CPU ID [Optional] =====-------------------------------------
# Description: Resource ID of CPU to be started
meta_data_start_cpu_id: 0
# ------------------------------===== CPU memory unit start ID [Optional] =====-------------------------------
# Description: Resource ID of the MU associated with the CPU
meta_data_mu_cpu_id: 0
# ---------------------------------===== Start partition ID [Optional] =====----------------------------------
# Description: Partition ID of the partition to start
meta_data_start_partition_id: 0
# ----------------------------------===== Images HASH type [Optional] =====-----------------------------------
# Description: HASH type of image. All images in the container must have the same HASH type.
# Possible options: <sha256, sha384, sha512, sm3>
hash_type: sha512
# ================================================================================================================
# == Configuration of AHAB SRK table ==
# ================================================================================================================
# ---------------------------------===== SRK Table [Conditionally 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: RSASSA-PSS, ECDSA or SM2. Supported hash algorithms: sha256, sha384, sha512, sm3. Supported
# key sizes/curves: prime256v1, sec384r1, sec512r1, rsa2048, rsa4096, sm2. 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
# ================================================================================================================
# == Optional configuration of AHAB Container Encryption blob (if not used, erase the section) ==
# ================================================================================================================
# -------------------------------------===== Encryption blob [Optional] =====-------------------------------------
# Description: Encryption blob container definition
blob:
# ------------------------------------===== Key identifier [Required] =====-------------------------------------
# Description: The key identifier that has been used to generate DEK keyblob.
key_identifier: 0
# -------------------------------------===== DEK key size [Required] =====--------------------------------------
# Description: Data Encryption key size. Used for AES CBC-MAC (128/192/256 size)
# Possible options: <128, 192, 256>
dek_key_size: 128
# ----------------------------------------===== DEK key [Required] =====----------------------------------------
# Description: Data Encryption key. Used for AES CBC-MAC (128/192/256 size). The HEX format is accepted
dek_key: my_dek_key.txt
# --------------------------------------===== DEK keyblob [Required] =====--------------------------------------
# Description: Wrapped Data Encryption key. Used for AES CBC-MAC (128/192/256 size). The HEX format is accepted
dek_keyblob: my_wrapped_key.txt