ASPEED CPTRA_IMGTOOL

The ASPEED Caliptra image tool packages SoC images into the Caliptra flash image layout.

AST27xxA2 Platform

For the AST27xxA2 platform, the generated manifest bundle binary includes:

• caliptra-runtime image
• mcu-runtime (fmc) image
• Caliptra SoC manifest
• Prebuilt binaries
• Bootloaders

AST27xxA1 Platform

For the AST27xxA1 platform, the generated manifest bundle binary includes:

• Caliptra SoC manifest
• Prebuilt binaries
• Bootloaders

Note: The AST27xxA1 manifest bundle binary does not include caliptra-runtime or mcu-runtime.

Reference Configurations

For more details, see:

• ast2700-default-manifest.toml
• ast2700a1-default-manifest.toml

Layout

This flash image layout is divided four parts, header, checksum, image infromation, and image binary. If you want to know more detail about soc manifest, please refer to Caliptra SoC Manifest

Header

Checksum

Image information

Image metadata list

Requirement

• Rustup for managing rust toolchain

  curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh

• Build caliptra-sw and caliptra-mcu-sw tool
  1. Aspeed's caliptra-sw
     • Including Aspeed's proprietary feature like SVN version insert and prebuilt signature insert.
  2. Official caliptra-mcu-sw
     • Including the official Caliptra flash tool.

     • IMPORTANT: If you are developing on the AST27XXA2 or AST27XXA1 platform, you must apply the fix from commit 2b7837402328ab611968d40243075082469df7ae.

  • Build command

    cd cptra_imgtool
    
    git clone https://github.com/AspeedTech-BMC/caliptra-sw.git
    cd caliptra-sw
    git submodule update --init --recursive
    cargo build -p caliptra-auth-manifest-app --target-dir ../target
    cd ..
    
    git clone https://github.com/chipsalliance/caliptra-mcu-sw.git
    cd caliptra-mcu-sw
    git reset --hard 2b7837402328ab611968d40243075082469df7ae
    cargo build -p xtask --target-dir ../target
    cd ..

  • Your folder structure will look like this:

    cptra_imgtool
    ├── caliptra-sw
    └── caliptra-mcu-sw

---

Build only the Caliptra SoC Manifest

Basic command with a specified config path:

# AST27xxA2 example
cargo run create-auth-man --cfg config/ast2700-default-ecc-manifest.toml
# Output: out/ast2700-default-auth-manifest.bin

# AST27xxA1 example
cargo run create-auth-man --cfg config/ast2700a1-default-ecc-manifest.toml
# Output: out/ast2700a1-default-auth-manifest.bin

Command Options

The create-auth-man command supports the following arguments:

Argument	Required	Description
--cfg <String>	Yes	Path to the configuration file used to generate the manifest.
--man <FILE>	No	Output path for the generated manifest file. If not provided, the default output path is used.
--key-dir <String>	No	Directory containing the keys needed for manifest generation.
--prebuilt-dir <String>	No	Directory containing prebuilt binaries required by the manifest.

Example with Optional Arguments

cargo run create-auth-man \
    --cfg config/ast2700-default-ecc-manifest.toml \
    --man out/soc-manifest.bin \
    --key-dir keys/ast2700-default/ \
    --prebuilt-dir prebuilt/ast2700-default/

---

Build the Caliptra Manifest Bundle Image (including the Caliptra SoC manifest)

Basic command with a specified config path:

# AST27xxA2 example
cargo run create-auth-flash --cfg config/ast2700-default-ecc-manifest.toml
# Output: out/ast2700-default-flash-image.bin

# AST27xxA1 example
cargo run create-auth-flash --cfg config/ast2700a1-default-ecc-manifest.toml
# Output: out/ast2700a1-default-flash-image.bin

Command Options

The create-auth-flash command supports the following arguments:

Argument	Required	Description
--cfg <String>	Yes	Path to the configuration file used to generate the flash image.
--man <FILE>	No	Input manifest file. If not provided, the tool automatically generates the manifest based on the specified config.
--flash <FILE>	No	Output path for the generated flash image file. If not provided, the tool outputs to the default path shown above.
--key-dir <String>	No	Directory containing the keys required for building the flash image.
--prebuilt-dir <String>	No	Directory containing prebuilt binaries used when assembling the flash image.

Example with Optional Arguments

cargo run create-auth-flash \
    --cfg config/ast2700-default-ecc-manifest.toml \
    --man out/ast2700-default-auth-manifest.bin \
    --flash out/custom-flash-image.bin \
    --key-dir keys/ast2700-default/ \
    --prebuilt-dir prebuilt/ast2700-default/

---

Build the AST27xxA1 Caliptra Flash Image (including the Caliptra runtime image, Caliptra SoC manifest, mcu-runtime image with ASPEED header)

Basic command with a specified config path:

cargo run create-auth-flash --cfg config/ast2700a1-default-manifest-cptra-out-bundle.toml
# Output: out/ast2700a1-default-flash-image.bin

TOML Configuration Description

The configuration file defines parameters used during manifest generation and flash image construction.

manifest_config fields

Field	Description
version	Manifest format version. Keep unchanged unless the platform requires an update.
flags	Manifest flags. Keep unchanged unless explicitly specified by the platform.
security_version	Security version used for anti-rollback protection. Higher values represent newer firmware. Devices will reject firmware with a lower security_version than the stored value.
prj_name	Optional. If omitted, default directories and filenames are used. If set, it affects the default key directory, prebuilt directory, and output binary naming.

Secure Boot–Related Key Configuration

The following sections determine which keys are used for signing and are directly tied to the platform’s secure boot policy.

Section	Purpose
[vendor_fw_key_config]	Vendor firmware signing key settings.
[vendor_man_key_config]	Vendor manifest signing key settings.
[owner_fw_key_config]	Owner firmware signing key settings.
[owner_man_key_config]	Owner manifest signing key settings.

The cptra image tool locates keys using the key name defined in this configuration.
If you need to use a different key, replace the original key file at the specified location.

    ├── key
    │   ├── ast2700-default
    │   │   ├── own-fw-ecc-prvk.pem
    │   │   ├── own-fw-ecc-pubk.pem
    │   │   ├── own-fw-lms-prvk.pem
    │   │   ├── own-fw-lms-pubk.pem
                  :

Runtime Image List

Field	Description
caliptra_file	The Caliptra firmware image. Please specify the final caliptra-fw.bin.
mcu_file	The first mutable code executed during boot (e.g., zephyr-mcu-runtime.bin).
cptra_out_bundle	For the AST2700 A1 flash layout, when this option is enabled, caliptra_file and mcu_file may reside outside the manifest bundle: • caliptra_file offset: 0x0000_0000 • mcu_file offset: 0x0002_0000 • manifest bundle offset: 0x0010_0000
zero_caliptra_file_end	If caliptra_file is an empty string, we can set a zero-filled padding size to generate a caliptra_file of the specified length. This ensures the SoC manifest is placed at the desired flash offset.

Image Metadata List

The image_metadata_list defines the metadata entries included in the manifest or flash layout.

Field	Description
file	Target file name in the prebuilt folder
source	Defined in caliptra-sw. Fixed value of 1 for InRequest in Caliptra 1.x
fw_id	Unique ID used to identify the target image
ignore_auth_check	Defined in caliptra-sw. If set, the image digest is not compared for the specified firmware ID
load_stage	Flag used by FMC (BootMCU runtime) to determine how the image is loaded in the main boot flow: • 0: Used only by specific drivers (e.g., ddr_xx.bin) • 1: May be loaded by the main boot flow (e.g., atf.bin) • 2: Used for the next-stage booting (iRoT solution)

If you want to remove an image from manifest or flash layout, locate its corresponding metadata entriy
and set file = "" and load_stage = 0.

[[image_metadata_list]]
file = ""
source = 1
fw_id = 13
ignore_auth_check = false
load_stage = 0

Rules

1. The first entry must always describe the FMC (First Mutable Code).
   This is essential for establishing the boot chain.

2. Subsequent entries should follow the FMC boot sequence.
   These may vary depending on the platform’s boot flow, such as:

   • ddr_train.bin
   • atf.bin
   • optee.bin
   • uboot.bin

Image Update

If you want to package new firmware using cptra image tool, replace the image and run cptra image tool command.

The image file structure like this:

├── prebuilt
│   ├── ast2700-default
│   │   ├── atf.bin
│   │   ├── caliptra-fw.bin
│   │   ├── ddr4_2d_pmu_train_dmem.bin
│   │   ├── ddr4_2d_pmu_train_imem.bin
                   :

Example: Update atf.bin

# Suppose you have built a new atf binary named xxxx_atf.bin
cp xxxx_atf.bin prebuilt/ast2700-default/atf.bin
cargo run create-auth-flash \
    --cfg config/ast2700-default-manifest.toml

---

Secure Boot Configuration

When Secure Boot is enabled, the manifest must be generated using the appropriate key configuration.
Depending on the signing scheme you intend to use, please refer to the following predefined configurations:

• Secure boot disabe
  Use this configuration if the platform disable Secure Boot:
  config/ast2700-default-manifest.toml

• ECC Only
  Use this configuration if the platform enables Secure Boot with ECC-only signing:
  config/ast2700-default-ecc-manifest.toml

• ECC + LMS
  Use this configuration if the platform enables Secure Boot with a combination of ECC and LMS signing:
  config/ast2700-default-ecc-lms-manifest.toml

Select the configuration that matches your platform's secure boot policy before generating the manifest or flash image.

---