The ASPEED Caliptra Image Tool packages SoC images into the Caliptra flash image layout.
Important
Prebuilt Binaries Notice
The prebuilt/ folder in this repository contains example test binaries only and may not reflect the latest firmware.
For the most up-to-date prebuilt binaries, please download them from: https://github.com/AspeedTech-BMC/bmc-pb
- What it does
- Upstream Source
- Output Manifest Bundle Image Example
- Manifest Bundle FLASH Layout
- Requirements and Environment Setup
- Run Image Generation
- TOML Configuration Description
- Soc Manifest Layout
- Secure Boot Configuration
- Signing Using a Sign Helper
- Building in an Offline Environment
This tool performs two primary tasks:
-
Generate SoC Manifest
Creates a SoC manifest using the binaries specified in the TOML configuration file. -
Assemble Flash Image
Packages all binaries together with the generated SoC manifest into a flash image that follows the layout described in the TOML configuration file.
In Caliptra, the SoC manifest is a metadata structure that describes the SoC-owned firmware/images to be loaded and verified.
In this version, the manifest focuses on identifying each image and providing integrity-related information (e.g., image ID, flags, and digests) so the SoC can validate the included contents before use.
If you want to know more detail about soc manifest, please refer to Caliptra SoC Manifest
In the following sections, we use the term manifest bundle image to refer to the output generated by this tool.
Note: The manifest bundle image produced by this tool does not include the kernel FIT image, ROFS, or RWFS.
This project contains code derived from:
- Project: chipsalliance/caliptra-sw
- Name: auth-manifest
- Path: tools/cptra_1x/auth-manifest
- Upstream License: Apache License 2.0
- Upstream Repository: https://github.com/chipsalliance/caliptra-sw
- Upstream Commit: <951209a31c4373658f89e4b1211f3a557731c7d9>
- Name: auth-manifest-2x
- Path: tools/cptra_2x/auth-manifest
- Upstream License: Apache License 2.0
- Upstream Repository: https://github.com/chipsalliance/caliptra-sw
- Upstream Commit: <879608b901cc60a68f4e52441e3c494605d08f35>
- 2026-04-16: Support generate anti-rollback signature
- 2026-04-16: Support load stage filed in manifest flags
- 2026-04-16: Make the auth manifest tool more flexible to support different signature combinations
- 2026-04-16: Support sign helper config input
- 2026-04-16: Ime flag support svn
- 2026-05-18: Rename the Rust dependency crate import for compatibility with two versions of the auth manifest generation tool, and remove unused dependencies: caliptra-drivers and caliptra-image-elf.
- 2026-03-05: Add load stage field support in manifest flags.
- 2026-04-15: Rename the Rust dependency crate import for compatibility with two versions of the auth manifest generation tool.
- 2026-05-18: Remove unused dependencies: caliptra-drivers and caliptra-image-elf.
This repository does not automatically track upstream updates. Security fixes and functional changes from upstream must be manually reviewed and ported if necessary.
For the AST27xxA2 platform, the generated manifest bundle binary includes:
caliptra-runtimeimagemcu-runtime(fmc) image- Caliptra SoC manifest
- Prebuilt binaries
- Bootloaders
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-runtimeormcu-runtime.
For more details, see:
This flash image layout is divided four parts, header, checksum, image infromation, and image binary.
Note: Caliptra’s flash layout may change over time. For AST2700 A1/A2, please refer to the following fixed version: flash_layout.md
This project requires the Rust toolchain (rustc , cargo ) to be installed and usable.
cargo --version
rustc --versionsudo apt update
sudo apt install -y build-essential curl pkg-config libssl-dev
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
# Choose: 1) Proceed with installation (default)
source "$HOME/.cargo/env"cargo --version
rustc --versionThis tool depends on caliptra-auth-manifest-app and xtask flash tool. Please build both dependencies before using the image tool.
- Tool to create an SoC manifest based on a TOML configuration
- Reference from upstream source auth-manifest
- Including Aspeed's proprietary feature like SVN version insert and prebuilt signature insert.
- Includes the official Caliptra xtask flash tool for certain versions.
IMPORTANT: If you are developing on the AST27XXA2 or AST27XXA1 platform, you must apply the fix from commit 2b7837402328ab611968d40243075082469df7ae.
cd cptra_imgtool
# Build caliptra-auth-manifest-app
cargo build -p caliptra-auth-manifest-app-1x
# Binary output:
# target/debug/caliptra-auth-manifest-app-1x
# Build the xtask flash tool
git clone https://github.com/chipsalliance/caliptra-mcu-sw.git tools/cptra_1x/caliptra-mcu-sw
cd tools/cptra_1x/caliptra-mcu-sw
git reset --hard 2b7837402328ab611968d40243075082469df7ae
cargo build -p xtask --target-dir ../../../target
# Binary output:
# target/debug/xtask
cd ../../..- Your folder structure will look like this:
cptra_imgtool
├── tools
│ ├── cptra_1x
│ | ├── auth-manifest
| | ├── caliptra-mcu-sw# 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.binThe 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 key/ast2700-default/ \
--prebuilt-dir prebuilt/ast2700-default/# 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.binThe 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 key/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)
cargo run create-auth-flash --cfg config/ast2700a1-default-manifest-cptra-out-bundle.toml
# Output: out/ast2700a1-default-flash-image.bin
The configuration file defines parameters used during manifest generation and flash image construction.
| 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. |
manifest_overrides_presigned_key_and_signature |
Optional. Default is true. When enabled, the public key and signature fields in the manifest are overwritten with an all-zero public key and the corresponding signature generated by the ASPEED HSM key. If set to false, the overwrite is skipped, and the manifest retains the input key and the signature generated from that key. |
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
| | | :
| | | :
| 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. |
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 entry
and set file = "" and load_stage = 0.
[[image_metadata_list]]
file = ""
source = 1
fw_id = 13
ignore_auth_check = false
load_stage = 0
-
The first entry must always describe the FMC (First Mutable Code).
This is essential for establishing the boot chain. -
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
If you want to package new firmware using cptra image tool, replace the image and run cptra image tool command.
Note
The prebuilt/ folder included in this repository is a test example only.
Always use the latest prebuilt binaries from https://github.com/AspeedTech-BMC/bmc-pb.
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.tomlThe tool can sign images using a key configured in the TOML file. Alternatively, you can provide an external signing helper executable (e.g., written in Rust or Python) to perform the signing operation. This approach keeps private keys out of the image tool and prevents key material from being stored or revealed by the tool.
| Field | Description |
|---|---|
| owner_ecc_fw_key_sign_helper | Command to perform signing using the owner ECC FW key. |
| owner_ecc_man_key_sign_helper | Command to perform signing using the owner ECC MAN key. |
| owner_lms_fw_key_sign_helper | Command to perform signing using the owner LMS FW key. |
| owner_lms_man_key_sign_helper | Command to perform signing using the owner LMS MAN key. |
| by_file | Controls how the tool communicates with the signing helper. When true, the tool passes the to-be-signed data and receives the resulting signature via files. When false, the tool uses stdin/stdout for data/signature transfer (ensure the helper does not print extra messages to stdout). |
For a sample configuration, refer to ast2700a1-default-ecc-lms-fw-man-sign-helper-byfile-manifest.toml.
Please refer to https://github.com/chipsalliance/caliptra-sw/tree/rt-1.2.0/auth-manifest
To support anti-rollback, our layout adds an SVN field and an owner signature that covers the SVN value.
The trust chain for the AST2700 A1/A2 SoC manifest and IMC is as follows:
- Vendor chain:
Fuse/OTP vendor PK hash → Caliptra FW vendor key → SoC manifest vendor key → IMC - Owner chain:
Fuse/OTP owner PK hash → Caliptra FW owner key → SoC manifest owner key → IMC
As described in the trust chain above, the SoC manifest vendor key must be endorsed (signed) by the vendor key in Caliptra RT FW.
However, the ASPEED FW vendor key is protected by an HSM and cannot be released for each vendor to perform signing. Therefore, the Manifest Vendor Signature is currently pre-generated and stored as a binary blob (stored in src/vnd_sig/).
In the current flow, regardless of what value is provided as the vendor FW key (or what signature is produced during the tool run), the generated Manifest Vendor Signature will always be overwritten by the prebuilt signature. As a result, the Manifest Vendor Public Key and Manifest Vendor Signature are fixed to constant values.
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.
The tool supports two signing modes. By default, it can sign using keys provided in the TOML configuration.
Alternatively, you can use an external sign helper executable (e.g., implemented in Rust or Python) to perform the signing step. This allows the signing keys to remain outside the image tool and avoids storing or exposing key material within the tool.
For parameter configuration, please refer to: Sign Helper
For a sample configuration, refer to ast2700a1-default-ecc-lms-fw-man-sign-helper-byfile-manifest.toml.
We provide both Python and Rust sign helper examples in the sign_helper_example directory.
Please refer to sign_helper_example/ecc_sign_helper.py and sign_helper_example/rust_sign_helper.
Compile the rust_sign_helper example (ensure caliptra-sw has been cloned).
cd sign_helper_example/rust_sign_helper/
cargo buildThe tool supports two methods to pass the to-be-signed data to the sign helper and receive the resulting signature:
- By file: the tool writes the input to a file and reads the signature back from a file.
- By stdin/stdout: the tool sends the input via
stdinand reads the signature fromstdout.
The transfer method is configurable in the TOML file via by_file.
- By file
- By stdin/stdout
There are two ways to use the sign helper:
-
Use the sign helper for both FW owner private key and Manifest owner private key
The TOML file does not contain the FW owner private key or the Manifest owner private key. Both signing operations are performed by the sign helper.
In this mode, the TOML file includes only the Manifest owner public key.
Please refer to: ast2700a1-default-ecc-lms-fw-man-sign-helper-byfile-manifest.toml. -
Use the sign helper for FW owner private key only
The TOML file does not contain the FW owner private key, and FW signing is performed by the sign helper.
The TOML file stores the Manifest owner key pair (public/private), which is used for manifest signing.
Please refer to: ast2700a1-default-ecc-lms-fw-sign-helper-stdin-manifest.toml.
This section describes how to build cptra_imgtool in an environment without internet access.
The strategy is to perform a full build on an online machine first to populate a local Cargo cache, then transfer everything to the offline machine.
Set a custom CARGO_HOME pointing to a directory inside the project so it can be copied along with the source tree. Then run all build commands normally to fetch and cache all dependencies.
cd cptra_imgtool
# Use a project-local directory as CARGO_HOME so it can be easily transferred
export CARGO_HOME=$(pwd)/offline_cargo_home
# Build caliptra-auth-manifest-app
cargo build -p caliptra-auth-manifest-app-1x
# Binary output:
# target/debug/caliptra-auth-manifest-app-1x
# Build the xtask flash tool
git clone https://github.com/chipsalliance/caliptra-mcu-sw.git tools/cptra_1x/caliptra-mcu-sw
cd tools/cptra_1x/caliptra-mcu-sw
git reset --hard 2b7837402328ab611968d40243075082469df7ae
cargo build -p xtask --target-dir ../../../target
# Binary output:
# target/debug/xtask
cd ../../..
# Run once to download and cache the main binary's dependencies,
# and to verify that the tools compile and run correctly
cargo run -- create-auth-man --cfg config/ast2700-default-ecc-manifest.toml
cargo run -- create-auth-flash --cfg config/ast2700-default-ecc-manifest.tomlAfter these commands complete, offline_cargo_home/ will contain the full Cargo registry cache and all git-sourced dependencies required to build the project.
Copy the entire cptra_imgtool directory (including offline_cargo_home/ and tools/cptra_1x/caliptra-mcu-sw/) to the offline machine.
# On the online machine — create a transferable archive
tar -czf cptra_imgtool_offline.tar.gz cptra_imgtool/Then transfer cptra_imgtool_offline.tar.gz to the offline machine and extract it.
# On the offline machine
tar -xzf cptra_imgtool_offline.tar.gzNote: Make sure the Rust toolchain (
cargo,rustc) is also installed on the offline machine with the same version used during the online build. You can check the required toolchain version inrust-toolchain.toml.
Point CARGO_HOME to the transferred cache directory and add --offline to all cargo commands to prevent any network access.
cd cptra_imgtool
export CARGO_HOME=$(pwd)/offline_cargo_home
# Build caliptra-auth-manifest-app
cargo build -p caliptra-auth-manifest-app-1x --offline
# Binary output:
# target/debug/caliptra-auth-manifest-app-1x
# Build the xtask flash tool
cd tools/cptra_1x/caliptra-mcu-sw
cargo build -p xtask --target-dir ../../../target --offline
# Binary output:
# target/debug/xtask
cd ../../..For image generation commands, add --offline after run:
# Build only the Caliptra SoC Manifest
cargo run --offline -- create-auth-man --cfg config/ast2700-default-ecc-manifest.toml
# Build the Caliptra Manifest Bundle Image
cargo run --offline -- create-auth-flash --cfg config/ast2700-default-ecc-manifest.toml| Step | Machine | Action |
|---|---|---|
| 1 | Online | Set CARGO_HOME, run all cargo build commands to populate the cache |
| 2 | Online → Offline | Copy entire cptra_imgtool/ directory (including offline_cargo_home/) |
| 3 | Offline | Set CARGO_HOME to the same path, add --offline to all cargo commands |