Name	Name	Last commit message	Last commit date
parent directory ..
include	include
memory_map	memory_map
pic	pic
samples	samples
scripts	scripts
README.md	README.md
info2header	info2header
info2sample	info2sample
info2schema	info2schema
otp_schema.json	otp_schema.json
otptool	otptool
socsec	socsec

Tools - How to

[TOC]

OTP Tool

OTP info generation

Generate the initial structures into a new file:

$ python3 scripts/otp_info_gen.py \
        {workbook} \
        {output_file}

Example:

$ python3 scripts/otp_info_gen.py memory_map/AST2700A2_OTP_memory_map.xlsx a2_otp_info.h

OTP info json file generation

$ python3 scripts/e2j.py \
        --input {otp_memory_map_file} \
        --strap {otp_strap_file}

OTP full sample jsonc generation

AST2700

$ python3 -m pip install pandas
$ python3 -m pip install openpyxl

$ python3 scripts/excel_to_json.py \
        {otp_memory_map_file} \
        {output JSONC}

$ python3 scripts/excel_to_jsonc.py memory_map/AST2700A2_OTP_memory_map.xlsx samples/sample_2700_A2.jsonc
Successfully converted 'memory_map/AST2700A2_OTP_memory_map.xlsx' to 'samples/sample_2700_A2.jsonc'
Successfully generated OTP user configuration to '2700a2_usr.json'

Output file: samples/sample_2700_A2.jsonc

Dump OTP memory binary

$ python3 scripts/visualize_bin.py otp-all.bin

OTP memory compare

one is generated by otptool (otp-all.bin)
one is generated by chip otp utility (otp-ast2700.bin)

$ python3 scripts/visualize_bin.py -d otp-all.bin otp-ast2700.bin

Caliptra tool

Caliptra keys sample json file generation

$ python3 scripts/cal_info_gen.py gen_sample

Caliptra key hash generation

$ python3 scripts/cal_info_gen.py gen_keyhash \
        --key_folder {key_folder} \
        --output_folder {output_folder} \
        config

Example
- config: samples/sample_cptra_vdrkey.json
- config: samples/sample_cptra_ownkey.json

Extract Caliptra Firmware Image data to be signed

Vendor TBS

$ dd if={cptra_fw_file} of=vendor_data_tbs.bin skip=5520 bs=1 count=116

Owner TBS

$ dd if={cptra_fw_file} of=owner_data_tbs.bin skip=5520 bs=1 count=156

Signing with ECC

$ openssl dgst -sha384 -sign {prvKey} -out {signature_ecc} {data}

Signing with LMS

This tool is used to sign data with an LMS private key, and use the corresponding public key for verification. The output is an LMS signature.

Example

python3 scripts/lms_signing_tool.py --data vendor_data_tbs.bin --key {prvKey} --public_key {pubKey} --output {signature_lms}
python3 scripts/lms_signing_tool.py --data owner_data_tbs.bin --key {prvKey} --public_key {pubKey} --output {signature_lms}

Usage

$ python3 scripts/lms_signing_tool.py -h
usage: lms_signing_tool.py [-h] --data DATA --key KEY [--public_key PUBLIC_KEY] --output OUTPUT

LMS Signing Tool

options:
  -h, --help            show this help message and exit
  --data DATA           Path to the data file to be signed
  --key KEY             Path to the private key file
  --public_key PUBLIC_KEY
                        Path to the public key file for verification (optional)
  --output OUTPUT       Path to the output file for the signature

Insert Vendor keys and signatures

This tool is used to insert 32 vendor ECC public keys, 4 vendor LMS public keys, a vendor ECC signature, and a vendor LMS signature into the Caliptra runtime firmware bundle.

Example

$ python3 scripts/cptra_vdr_key_ins.py {cptra_fw_file} {key_dir} {signature_ecc} {signature_lms}

Usage

$ python3 scripts/cptra_vdr_key_ins.py -h
usage: cptra_vdr_key_ins.py [-h] file_path key_directory vendor_ecc_sig_file vendor_lms_sig_file

Process ECC and LMS signatures and public keys.

positional arguments:
  file_path            Path to the file to be modified (Caliptra firmware image)
  key_directory        Directory containing the pem/pub files
  vendor_ecc_sig_file  Path to the ECC signature file in DER format
  vendor_lms_sig_file  Path to the LMS signature file in binary format

options:
  -h, --help           show this help message and exit

Insert Owner keys and signatures

This tool is used to insert an owner ECC public key, an owner LMS public key, an owner ECC signature, and an owner LMS signature into the Caliptra runtime firmware bundle.

Example

$ python3 scripts/cptra_own_key_ins.py {cptra_fw_file} --ecc_key {pubKey} --lms_key {pubKey} --ecc_sig {signature_ecc} --lms_sig {signature_lms}

Usage

$ python3 scripts/cptra_own_key_ins.py -h
usage: cptra_own_key_ins.py [-h] --ecc_key ECC_KEY --lms_key LMS_KEY --ecc_sig ECC_SIG --lms_sig LMS_SIG file_path

Insert ECC and LMS keys and signatures into a firmware image.

positional arguments:
  file_path          Path to the firmware image file

options:
  -h, --help         show this help message and exit
  --ecc_key ECC_KEY  Path to the ECC public key file in PEM format
  --lms_key LMS_KEY  Path to the LMS public key file in .pub format
  --ecc_sig ECC_SIG  Path to the ECC signature file in DER format
  --lms_sig LMS_SIG  Path to the LMS signature file in binary format

Caliptra Firmware Image Signature Verification

This tool is used for Caliptra runtime firmware signature verification, including:

Vendor ECDSA384 signature verification
Owner ECDSA384 signature verification
Vendor LMS signature verification
Owner LMS signature verification
Example

$ python3 scripts/cptra_img_sig_ver.py {cptra_fw_file}

Output

Caliptra Vendor ECDSA384 signature verification succeeded.
Caliptra Owner ECDSA384 signature verification succeeded.
Caliptra Vendor LMS signature verification succeeded.
Caliptra Owner LMS signature verification succeeded.

Usage

$ python3 scripts/cptra_img_sig_ver.py -h
usage: cptra_img_sig_ver.py [-h] cptra_fw

Verify ECC and LMS signatures in a Caliptra firmware file.

positional arguments:
  cptra_fw    Path to the source file to verify

options:
  -h, --help  show this help message and exit

How to compare key hash

Vendor key hash

Generate vendor key hash from key source

$ python3 scripts/cal_info_gen.py gen_keyhash \
        --key_folder {key_folder} \
        --output_folder {output_folder} \
        samples/sample_cptra_vdrkey.json

Output: vendor_key.bin, vendor_key_hash.bin

Generate vendor key hash from cptra fw

$ dd if={cptra_fw} of={output_file} bs=1 skip=8 count=$((0x788 - 0x8))
$ sha384sum {output_file} | tee >(awk '{print $1}' | xxd -r -p > vendor_key_digest.bin)

Compare two of them

$ diff vendor_key_hash.bin vendor_key_digest.bin

Owner key hash

Generate owner key hash from key source

$ python3 scripts/cal_info_gen.py gen_keyhash \
        --key_folder {key_folder} \
        --output_folder {output_folder} \
        samples/sample_cptra_ownkey.json

Output: owner_key.bin, owner_key_hash.bin

Generate owner key hash from cptra fw

$ dd if={cptra_fw} of={output_file} bs=1 skip=3652 count=$((0x90))
$ sha384sum {output_file} | tee >(awk '{print $1}' | xxd -r -p > owner_key_digest.bin)

Compare two of them

$ diff owner_key_hash.bin owner_key_digest.bin

Extract SoC Manifest and tbs data

This tool is used to extract SoC Manifest and manifest vendor/owner data tbs from input file.

Example

$ python3 scripts/extract_soc_manifest.py <input_image.bin> soc_manifest.bin manifest_vendor_data_tbs.bin manifest_owner_data_tbs.bin manifest2_owner_data_tbs.bin

Usage

$ python3 scripts/extract_soc_manifest.py -h
usage: extract_soc_manifest.py [-h]
                               input_file output_manifest_file output_vendor_data_file output_owner_data_file
                               output_manifest2_owner_data_file

Extract SoC Manifest and manifest vendor data tbs from input file.

positional arguments:
  input_file            Path to the input file containing the header and images.
  output_manifest_file  Path to write the extracted SoC Manifest.
  output_vendor_data_file
                        Path to write the extracted manifest vendor data tbs.
  output_owner_data_file
                        Path to write the extracted manifest owner data tbs.
  output_manifest2_owner_data_file
                        Path to write the extracted manifest2 owner data tbs.

options:
  -h, --help            show this help message and exit

Insert Manifest Vendor keys and signatures

This tool is used to insert manifest vendor ECC & LMS keys and signatures into a SoC manifest file.

Example

python3 scripts/mfst_vdr_sig_ins.py soc_manifest.bin manifest_vendor_ecc_sig.der manifest_vendor_lms_sig soc_manifest.bin

Usage

$ python3 scripts/mfst_vdr_sig_ins.py -h
usage: mfst_vdr_sig_ins.py [-h] input_manifest_file ecc_sig_file lms_sig_file output_manifest_file

Insert manifest vendor ECC & LMS keys and signatures into a SoC manifest file.

positional arguments:
  input_manifest_file   Path to the input SoC manifest file.
  ecc_sig_file          Path to the ECC signature file (96 bytes).
  lms_sig_file          Path to the LMS signature file (1620 bytes).
  output_manifest_file  Path to write the updated SoC manifest file.

options:
  -h, --help            show this help message and exit

Insert Manifest Owner keys and signatures

This tool is used to insert manifest owner ECC & LMS keys and signatures into a SoC manifest file.

Example

$ python3 scripts/mfst_own_sig_ins.py soc_manifest.bin manifest_owner_ecc_sig.bin manifest_owner_lms_sig soc_manifest.bin

Usage

$ python3 scripts/mfst_own_sig_ins.py -h
usage: mfst_own_sig_ins.py [-h] input_manifest_file ecc_sig_file lms_sig_file output_manifest_file

Insert manifest owner ECC & LMS keys and signatures into a SoC manifest file.

positional arguments:
  input_manifest_file   Path to the input SoC manifest file.
  ecc_sig_file          Path to the ECC signature file.
  lms_sig_file          Path to the LMS signature file.
  output_manifest_file  Path to write the updated SoC manifest file.

options:
  -h, --help            show this help message and exit

Insert Manifest2 Owner keys and signatures

This tool is used to insert manifest2 owner ECC & LMS keys and signatures into a SoC manifest file.

Example

$ python3 scripts/mfst2_own_sig_ins.py soc_manifest.bin manifest2_owner_data_sig.bin manifest2_owner_lms_sig soc_manifest.bin

Usage

$ python3 scripts/mfst2_own_sig_ins.py -h
usage: mfst2_own_sig_ins.py [-h] input_manifest_file ecc_sig_file lms_sig_file output_manifest_file

Insert manifest2 owner ECC & LMS signatures into a SoC manifest file.

positional arguments:
  input_manifest_file   Path to the input SoC manifest file.
  ecc_sig_file          Path to the ECC signature file.
  lms_sig_file          Path to the LMS signature file.
  output_manifest_file  Path to write the updated SoC manifest file.

options:
  -h, --help            show this help message and exit

Verify SoC Manifest Signatures

This tool is used to verify SoC manifest signatures.

Example

$ python3 scripts/soc_manifest_ver.py soc_manifest.bin {vendor_ecc_key} {owner_ecc_key} --vendor_lms_key {vendor_lms_key} --owner_lms_key {owner_lms_key}

Usage

$ python3 scripts/soc_manifest_ver.py -h
usage: soc_manifest_ver.py [-h] [--vendor_lms_key VENDOR_LMS_KEY] [--owner_lms_key OWNER_LMS_KEY] manifest vendor_ecc_key owner_ecc_key

Verify signatures in soc_manifest.bin.

positional arguments:
  manifest              Path to the soc_manifest.bin file
  vendor_ecc_key        Path to the vendor ECC public key
  owner_ecc_key         Path to the owner ECC public key

options:
  -h, --help            show this help message and exit
  --vendor_lms_key VENDOR_LMS_KEY
                        Path to the vendor LMS public key (optional)
  --owner_lms_key OWNER_LMS_KEY
                        Path to the owner LMS public key (optional)

Caliptra Hash Extraction

This tool is used to extract FMC and Runtime SHA-384 hashes from a Caliptra firmware bundle and compare them against official GitHub releases.

Features

Automatic Hash Extraction: Parses the CMAN manifest and TOC entries to extract image measurement hashes.
Endianness Correction: Automatically detects and corrects word-swapped hashes to match standard Big-Endian format.
Online Comparison: Fetches the latest official release table from chipsalliance/caliptra-sw for automated verification.
Default Firmware Support: Automatically downloads the latest caliptra-fw.bin from AspeedTech-BMC/bmc-pb if no input file is provided.

Usage

1. Extract and Verify a Specific Firmware Image

python3 scripts/hash_extract.py path/to/your/caliptra-fw.bin

2. Run with Default Firmware

If no arguments are provided, the tool downloads and processes the default firmware from the Aspeed GitHub repository:

python3 scripts/hash_extract.py

URLs Used

Default FW: https://raw.githubusercontent.com/AspeedTech-BMC/bmc-pb/refs/heads/master/ast2700a2/caliptra-fw.bin
Official FW: https://raw.githubusercontent.com/chipsalliance/caliptra-sw/main/README.md

Example Output

$ python3 scripts/hash_extract.py
[*] Default FW URL: https://raw.githubusercontent.com/AspeedTech-BMC/bmc-pb/refs/heads/master/ast2700a2/caliptra-fw.bin
[*] Processing firmware: caliptra-fw.bin
[*] Official README URL: https://raw.githubusercontent.com/chipsalliance/caliptra-sw/main/README.md
[*] Fetching official release info for rt-1.2.1...
----------------------------------------
Results for target version: rt-1.2.1
----------------------------------------
FMC (Extracted): cefdc6454ee254661d35f2ecc7a973aadc1c1c8a4e702376171ef10385d624360df5f79779d2ab30edc82805784c3dd5
FMC (Official):  cefdc6454ee254661d35f2ecc7a973aadc1c1c8a4e702376171ef10385d624360df5f79779d2ab30edc82805784c3dd5
FMC Match?       [ OK ]

RT  (Extracted): d48f83b629378d32ac2547b31799794e353e1460ae773048f902723ab95efffb142cc7e51c7f4580a7ec89f22ea531c1
RT  (Official):  d48f83b629378d32ac2547b31799794e353e1460ae773048f902723ab95efffb142cc7e51c7f4580a7ec89f22ea531c1
RT  Match?       [ OK ]
----------------------------------------
[+] Success: All hashes match the official release.

Calculate Reference Measurements

This tool pre-computes the SHA-384 measurements that the ROM/ROM-patch stashes into Caliptra PCR31 via the STASH_MEASUREMENT flow. Use it to generate a reference JSON that can be compared against the values reported by the device at runtime.

Inputs

Argument	Required	Description
`--efuse`	yes	eFuse JSON file containing `SCU0_810` and `SCU1_804` register values
`--hwstrap`	yes	HW Strap JSON file containing `SCU0_010`, `SCU1_010`, and `SCU1_030` register values
`--otp`	yes	OTP binary image dumped from the device (e.g. via the OTP dump command)
`--output`	yes	Path for the output reference measurements JSON
`--fw`	no	FW JSON file mapping component names to image filenames (secure boot only)
`--image-dir`	no	Directory containing FW images; defaults to `../image`

Measurement order

Normal boot (no FMC):

PCR31 = extend(extend(extend(0, OTP), STRA), EFUS)

Secure boot (FMC present):

PCR31 = extend(FMC, OTP, STRA, EFUS, DP, DDR0, DDR1, UEFI0,
               UEFI1, ATF, OPTEE, UBOOT, SSP, TSP,
               KERNEL-FIT (linux, dtb, initramfs))

KERNEL-FIT is extended 3 times (linux image, dtb, initramfs regions).

Usage

Normal boot (OTP + HW strap + eFuse only):

python3 scripts/calculate_measurements.py \
    --efuse=samples/ast27x0_efuse.json \
    --hwstrap=samples/ast27x0_hwstrap.json \
    --otp=samples/otp-all.bin \
    --output=samples/reference_measurements.json

Secure boot (with full FW image set):

python3 scripts/calculate_measurements.py \
    --efuse=ast27x0_efuse.json \
    --hwstrap=ast27x0_hwstrap.json \
    --otp=otp-all.bin \
    --fw=ast27x0_fw.json \
    --output=reference_measurements.json \
    --image-dir=../image

Input file formats

eFuse JSON (ast27x0_efuse.json):

{
    "SCU0_810": "0x00200000",
    "SCU1_804": "0x00000000"
}

HW Strap JSON (ast27x0_hwstrap.json):

{
    "SCU0_010": "0x00000000",
    "SCU1_010": "0x00000300",
    "SCU1_030": "0x00000000"
}

FW JSON (ast27x0_fw.json) — maps Caliptra component names to image filenames:

{
    "FMC":    "ast2700-mcu-runtime.bin",
    "DP":     "dp_fw.bin",
    "DDR0":   "ddr5_pmu_train_imem.bin",
    "DDR1":   "ddr5_pmu_train_dmem.bin",
    "ATF":    "bl31.bin",
    "OPTEE":  "tee-raw.bin",
    "UBOOT":  "u-boot.bin",
    "SSP":    "zephyr-aspeed-ssp.bin",
    "TSP":    "zephyr-aspeed-tsp.bin",
    "KERNEL": "fitImage-obmc-phosphor-initramfs-ast2700-default"
}

Output

The output JSON contains the individual component hashes and the final PCR31 value:

{
    "OTP_FULL": "<sha384hex>",
    "STRA":     "<sha384hex>",
    "EFUS":     "<sha384hex>",
    "PCR31":    "<sha384hex>"
}

With --fw, additional per-component entries (e.g. FMC, ATF, KERNEL) are included.

FilesExpand file tree

tools

Directory actions

More options

Directory actions

More options

Latest commit

History

tools

Folders and files

parent directory

README.md

Tools - How to

OTP Tool

OTP info generation

OTP info json file generation

OTP full sample jsonc generation

AST2700

Dump OTP memory binary

OTP memory compare

Caliptra tool

Caliptra keys sample json file generation

Caliptra key hash generation

Extract Caliptra Firmware Image data to be signed

Vendor TBS

Owner TBS

Signing with ECC

Signing with LMS

Insert Vendor keys and signatures

Insert Owner keys and signatures

Caliptra Firmware Image Signature Verification

How to compare key hash

Vendor key hash

Owner key hash

Extract SoC Manifest and tbs data

Insert Manifest Vendor keys and signatures

Insert Manifest Owner keys and signatures

Insert Manifest2 Owner keys and signatures

Verify SoC Manifest Signatures

Caliptra Hash Extraction

Features

Usage

1. Extract and Verify a Specific Firmware Image

2. Run with Default Firmware

URLs Used

Example Output

Calculate Reference Measurements

Inputs

Measurement order

Usage

Input file formats

Output