Secure Boot

Overview

Secure Boot is a key technology for ensuring the security of IoT devices. Its core purpose is to ensure that devices only run authorized firmware, preventing malicious code injection or illegal firmware tampering. The core method utilizes asymmetric encryption private key signing and public key verification technology: developers use private keys to sign firmware; chips use public keys during startup to verify signatures, thereby ensuring firmware integrity and authenticity.

When the device powers on, the Boot ROM code internally solidified in the chip automatically checks whether the firmware about to run has a legitimate digital signature: If verification passes, the firmware source is confirmed as trusted, and the system continues executing the subsequent startup process; if verification fails, the firmware is considered untrusted, sensitive states are cleared, and startup is terminated.

This process is implemented through the “Chain of Trust” mechanism - the trust relationship starts from tamper-proof hardware (ROM) and extends to the final application firmware through step-by-step signature verification. This ensures that all firmware is trusted throughout the entire operational lifecycle.

Ameba series ICs support different signature algorithms:

RTL8721DxRTL8720ERTL8710ERTL8726ERTL8713ERTL8730ERTL8721F

RTL8721Dx:

Algorithm Type	Algorithm Parameters
EdDSA	ed25519

After understanding the signature algorithms supported by Ameba series ICs, the following section introduces the principles and complete process of Secure Boot.

Secure Boot Principles and Process

Secure Boot starts from the ROT composed of Boot ROM + OTP and is passed level by level. The figure below shows the complete Secure Boot usage process:

Secure Boot involves three stages: development, mass production, and runtime, completed by different participants at different times:

• Development Stage (completed by developers):

  • Generate asymmetric key pairs: private keys must be strictly kept confidential, and public key hash values are calculated.

  • Generate signed firmware: use private keys to digitally sign the original firmware, generating a Manifest containing metadata such as public keys, signatures, and original firmware hashes. The Manifest and original firmware are combined to generate signed firmware.

• Mass Production Stage (completed by production line):

  • Burn public key hash values and enable bits: burn the public key hash values generated during the development stage to fixed addresses in the chip OTP. Also burn the Secure Boot enable bit to enable the Secure Boot function.

  • Burn signed firmware: burn the signed firmware generated during the development stage to the chip’s Flash storage.

• Runtime Stage (executed by chip): after the device powers on, Boot ROM verifies the signatures and integrity of firmware at all levels level by level based on the public key hash in OTP. If verification passes, startup continues; if verification fails, sensitive information is cleared and startup is terminated.

Secure Boot Solution

Ameba SDK provides a complete out-of-the-box Secure Boot solution. All complex signature verification mechanisms have been implemented in the SDK, and developers do not need to write code themselves, only needing to configure the SDK according to the user guide. The figure below shows the signature verification process in the chip’s multi-level startup:

Ameba series ICs adopt a multi-level startup process, sequentially executing the following three independent firmware:

• First Stage - Boot ROM: the first code executed after the device powers on is the chip’s internal ROM, which is physically tamper-proof. Boot ROM reads the Bootloader and its Manifest from Flash, uses the OTP public key hash to verify the public key and signature in the Manifest. Then it verifies the Bootloader firmware hash stored in the Manifest. After verification passes, it jumps to execute the Bootloader; if it fails, it clears sensitive states and terminates startup.

• Second Stage - Bootloader: a bootloader loaded from Flash, responsible for loading and security verification of subsequent firmware. Bootloader first verifies the signature of the Key Certificate. The certificate contains the application firmware’s public key hash and also allows adding multiple sets of custom public key hash values. After verification passes, Bootloader extracts the public key hash used to verify application firmware from the certificate, then uses that public key hash to verify the application firmware’s Manifest, and finally calculates and compares the application firmware’s hash value.

• Third Stage - Application: a user application that runs directly, not responsible for firmware verification.

The first two startup stages both execute in the ARM Secure world. Compared with single-level verification, the three-level verification architecture adopted by Ameba has the following advantages:

• Key Isolation: Bootloader and application firmware use different key pairs. Even if the application firmware key is leaked, Bootloader remains secure.

• Flexible Updates: application firmware keys are stored in certificates, allowing application key updates without modifying OTP.

• Permission Separation: developers can maintain application keys, while OEM manufacturers control Bootloader keys, achieving permission separation.

Verification Process

Manifest Composition and Purpose

In the Secure Boot verification process, the chip needs to read various information from the firmware to complete verification: version number, algorithm, public key, signature, etc. All this information is organized in the Manifest. The Manifest can be understood as the firmware’s “identity description file”: it is a binary format metadata block attached to the header of the executable firmware. The following three parts each have independent Manifests:

• Image1 (Bootloader): bootloader, responsible for verifying key certificates and application firmware;

• Cert (Key Certificate): key certificate, used to pass the application firmware’s public key hash value;

• Image2 (Application): application firmware, user’s application.

Verification Process Details

Secure Boot is built upon the “Chain of Trust” mechanism, where the chain of trust starts from tamper-proof hardware ROM and OTP, and extends to the final application firmware through step-by-step verification. The figure below shows the complete three-level verification process:

Standard Verification ProcessPQC Hybrid Mode Verification Process

Standard Verification Process:

The chip startup verification process varies slightly depending on the mode: Standard ECC mode only verifies ECC signatures, while PQC hybrid mode requires verifying both ECC and PQC signatures. However, in either mode, each level of verification contains three core steps:

1. Verify public key trustworthiness: calculate the hash value of the public key in the Manifest and compare it with the public key hash value burned in OTP;

2. Verify Manifest reliability: use the public key to verify the Manifest signature;

3. Verify firmware reliability: calculate the actual firmware’s hash value and compare it with the firmware hash value generated during the post-build processing stage in the Manifest.

If any step fails, the chip will terminate startup. The specific process is as follows:

First Level : Boot ROM -> Bootloader (image1)

Boot ROM reads the public key hash value from OTP, calculates the hash value of the public key in the Bootloader Manifest and compares them. After they match, use the public key to verify the Manifest signature (the signed content is all Manifest fields except Signature). After signature verification succeeds, read the firmware hash from the Manifest, calculate the actual firmware hash and compare it. After verification passes, jump to execute Bootloader.

Second Level : Bootloader -> Key Certificate (cert)

Bootloader uses the public key in OTP to verify the key certificate. After confirming the certificate’s public key matches the OTP, verify the certificate signature. After signature verification passes, extract the application firmware’s public key hash value from the certificate to establish the trust anchor for subsequent verification. The certificate does not contain executable firmware, so firmware reliability verification is not required.

Third Level : Bootloader -> Application Firmware (image2)

Bootloader uses the public key hash in the certificate to verify the application firmware public key. The subsequent process is the same as the first-level verification.

After clarifying the verification process, the following section introduces the public key hash and algorithm configuration methods.

Parameter Configuration

Parameter Configuration Overview

Secure Boot involves multiple key parameters, covering signature keys, hash algorithms, and storage locations. The table below summarizes the main parameters:

Parameter Name	Function	manifest.json5 Configuration Field	IC Storage Location
Private Key	Digitally sign firmware	sboot_private_key	Not stored on IC side
Public Key	Verify firmware signature during IC boot	sboot_public_key	Manifest Data Block
Public Key Hash	Root of trust anchor, verify public key legitimacy	sboot_public_key_hash	OTP PK1 or PK2 Area
RMA Public Key Hash	Backup public key hash in RMA mode	sboot_public_key_hash	OTP RMA_PK Area
HMAC Key	Firmware hash calculation key (HMAC mode only)	sboot_hmac_key	OTP S_IPSEC_Key2 Area
Signature Algorithm	Specify signature type (e.g., ed25519)	sboot_algorithm	OTP SECURE_BOOT_AUTH_ALG Bit
Hash Algorithm	Specify firmware digest algorithm (e.g., sha256)	sboot_hash_alg	OTP SECURE_BOOT_HASH_ALG Bit
Secure Boot Enable	Enable secure boot function	sboot_enable	OTP SECURE_BOOT_EN Bit

After understanding the overall parameter configuration, the following section details the storage locations and configuration methods for each parameter:

Public Key Hash Storage Details

Secure Boot stores public key hash values through OTP to form a tamper-proof hardware Root of Trust. When the chip starts up, Boot ROM calculates the hash value of the public key in the Manifest and compares it with the public key hash value stored in OTP. After verification passes, the startup process continues to execute. The public key hash values used in the three-level verification process are stored in different locations:

• Image1 (Bootloader): public key hash is stored by default in the PK1 area of OTP (physical address 0x320~0x33F)

• Cert (Key Certificate):

  • Under SDK default configuration, the key certificate uses the same PK1 key pair as Bootloader.

  • When Bootloader and application firmware are developed by different teams, use PK2 to achieve key isolation, ensuring that certificate key leakage does not affect Bootloader security. When using PK2, the public key hash needs to be stored in the PK2 area of OTP (physical address 0x340~0x35F), and modify the chip-specific ameba_bootcfg.c file:

    RTL8721DxRTL8720ERTL8710ERTL8726ERTL8713ERTL8730ERTL8721F

    RTL8721Dx:

    github source code

    • ameba_bootcfg.c

  /* Default uses PK1. If using PK2 independent key, change to SEC_PKKEY_PK2_0 */
  u32 Cert_PKHash_OTP_ADDR = SEC_PKKEY_PK1_0;
  

• Image2 (Application): public key hash is stored in the key certificate and does not need to be burned to OTP. In addition to the default key hash, you can modify the manifest.json5 file to add custom key hashes to the certificate.

OTP configurations for different chips are as follows:

RTL8721DxRTL8720ERTL8710ERTL8726ERTL8713ERTL8730ERTL8721F

RTL8721Dx:

Mode	Name	OTP Address	Size (bits)	Description
Normal	PK1	Physical 0x320~0x33F	256	To support different algorithms and curves, public key hash (SHA256) is stored in OTP
	PK2	Physical 0x340~0x35F	256	To support different algorithms and curves, public key hash (SHA256) is stored in OTP
	PK1_W_Forbidden_EN	Physical 0x365[1]	1	PK1 cannot be modified after burning
	PK2_W_Forbidden_EN	Physical 0x365[2]	1	PK2 cannot be modified after burning
	SECURE_BOOT_EN_PHY	Physical 0x368[3]	1	Secure boot is enabled when any enable bit is burned For devices in development and debugging phase, use SECURE_BOOT_EN_LOG as it can be disabled For devices in mass production phase, burn SECURE_BOOT_EN_PHY to permanently enable secure boot
	SECURE_BOOT_EN_LOG	Logical 0x3[2]	1
RMA	RMA_PK	Physical 0x720~0x73F	256	Hash value of secure boot public key in RMA mode For security reasons, users can maintain RMA keys different from PK1/PK2
	RMA_PK_W_Forbidden_EN	Physical 0x702[2]	1	RMA_PK cannot be modified after burning

After completing the OTP configuration of public key hashes, the next step is to select the signature and hash algorithms.

Authentication and Hash Algorithms

Signature and hash algorithm configuration items will be written to the Manifest as algorithm identifiers. Two configuration methods are supported:

1. Development Stage: when algorithms are not specified in OTP, the chip performs signature verification based on configuration in the firmware Manifest (manifest.json5).

2. Mass Production Stage: permanently lock hash and signature algorithms in OTP.

The algorithms supported by different chips and OTP configurations are as follows:

RTL8721DxRTL8720ERTL8710ERTL8726ERTL8713ERTL8730ERTL8721F

RTL8721Dx:

Name	OTP Address	Length (bit)	Description
SECURE_BOOT_AUTH_ALG	Physical Address 0x36B[3:0]	4	Specifies signature curve 0x0: (EdDSA) ed25519
SECURE_BOOT_HASH_ALG	Physical Address 0x36B[7:4]	4	Specifies hash algorithm 0x0: SHA2 256 0x1: SHA2 384 0x2: SHA2 512 0x3: HMAC-SHA2 256 0x4: HMAC-SHA2 384 0x5: HMAC-SHA2 512

Once the algorithm configuration is locked in OTP, the auth_alg and hash_alg settings in manifest.json5 must be completely consistent with OTP, otherwise the chip will not be able to start. This restriction applies to Bootloader, key certificate, and application firmware simultaneously.

HMAC Key

This section only applies to scenarios using HMAC for firmware hash verification. HMAC enhances hash calculation security through keys and requires pre-configuring a unified key in OTP for hash verification of all firmware. Storage location and protection settings are as follows:

Name	OTP Address	Size (bits)	Description
S_IPSEC_Key2	Physical address 0x220~0x23F	256	HMAC key storage location.
S_IPSEC_Key2_R_Protection_EN	Physical address 0x365[5]	1	When set to 1, CPU cannot read the key (prevents key theft).
S_IPSEC_Key2_W_Protection_EN	Physical address 0x365[6]	1	When set to 1, the key can no longer be modified (prevents key tampering).

Usage Instructions

After completing the above parameter configuration, follow the steps below to complete the Secure Boot configuration process. The entire usage process is divided into three stages:

• Development Stage: completed by developers, including key generation, project configuration, and firmware compilation;

• Mass Production Stage: completed by production line, including firmware burning and OTP configuration;

• Runtime Stage: executed by the chip, including device reset and log verification.

Development Stage

1. Generate Key Pairs

Key pairs are the foundation of Secure Boot: private keys are used to sign firmware, and public keys are written to the Manifest for signature verification. Navigate to the SDK {SDK}/tools/scripts directory. Depending on the signature algorithm, use different key generation commands:

$ python axf2bin.py encrypt keypair -a ed25519 -o keypair.json5

• Supported ECC curves: ed25519, secp192r1, secp224r1, secp256r1, bp256r1, secp192k1, secp224k1, secp256k1

• Supported PQC algorithms: ml_dsa_65

After script execution, the keypair.json5 file will be generated. It is recommended to generate different key pairs for application firmware (image2) and Bootloader (image1) to achieve key isolation.

In keypair.json5, the key byte order and public key hash calculation for each algorithm are as follows:

Algorithm	Private Key Endianness	Public Key Endianness	Public Key Hash Algorithm	Public Key Byte Order for Hash
ECDSA	Big-endian	Big-endian	SHA-256	Big-endian
Ed25519	Little-endian	Little-endian	SHA-256	Little-endian
ML-DSA-65	Little-endian	Little-endian	SHA-256	Little-endian

ECC Key File ExamplePQC Key File Example

ECC Key File Example:

{
   sboot_algorithm: ed25519,
   sboot_private_key: "6AA34203018334474B25A0600996CA0968AA6228B886FF234B4EB9628B703C0A",
   sboot_public_key: "E2A0D6500BBF1DD8DC212098C230EB731ECE3A81AA11D0E6E538FA36BBA4FF6E",
   sboot_public_key_hash: "72B2E1CB0E8F715262AF38DFA0E522C95660D0EBFD920F4B1A229845E599C697",
}

2. Modify Secure Boot Configuration Script

Write key and algorithm configuration to the chip-specific manifest.json5:

RTL8721DxRTL8720ERTL8710ERTL8726ERTL8713ERTL8730ERTL8721F

RTL8721Dx:

github source code

• manifest.json5

The post-build script will use the keys and algorithms in this file to sign the firmware and write information such as public keys to the firmware’s Manifest. Different fields in manifest.json5 correspond to different signature verification stages:

• image1: first-level verification (Boot ROM verifies Bootloader), storing Bootloader’s signature configuration;

• cert: second-level verification (Bootloader verifies certificate), storing key certificate’s signature configuration;

• image2: third-level verification (Bootloader verifies application firmware), storing application firmware’s signature configuration.

ECC Configuration InstructionsPQC Configuration Instructions

ECC Configuration Instructions:

Copy the key content from keypair.json5 and overwrite it to the corresponding location in manifest.json5, and enable Secure Boot (sboot_enable: true). In the example below, image1 and cert use the same PK1 key pair, while image2 uses a different key pair:

{
   version: 1,
   image1: {
      sboot_private_key: "6AA34203018334474B25A0600996CA0968AA6228B886FF234B4EB9628B703C0A",
      sboot_public_key: "E2A0D6500BBF1DD8DC212098C230EB731ECE3A81AA11D0E6E538FA36BBA4FF6E",
      sboot_public_key_hash: "72B2E1CB0E8F715262AF38DFA0E522C95660D0EBFD920F4B1A229845E599C697",
   },

   /* cert/image2 share img_id/img_ver, cert and image3 img are packed in app.bin */
   cert: {
      sboot_private_key: "6AA34203018334474B25A0600996CA0968AA6228B886FF234B4EB9628B703C0A",
      sboot_public_key: "E2A0D6500BBF1DD8DC212098C230EB731ECE3A81AA11D0E6E538FA36BBA4FF6E",
      sboot_public_key_hash: "72B2E1CB0E8F715262AF38DFA0E522C95660D0EBFD920F4B1A229845E599C697",
   },
   image2: {
      sboot_private_key: "9FC60C4CB6162E49C54FB94511497E16F5EB605167836F15DECBB8363B18E243",
      sboot_public_key: "45BABD665908AD5576D9DA4A80287262A4CB1475ACAD543E27A9C2598579FC72",
      sboot_public_key_hash: "1DFC2FE01CA8274F06E2E112D027C3C6FF9CED59EE79944BED46ADE35C44B422",
   },

   ...

   /* ============================ Secure Boot globle settings ============================ */
   sboot_enable: true,
   sboot_algorithm: "ed25519",
   sboot_hash_alg: "sha256",
   sboot_hmac_key: ["otp_key_0x220"],

   ...

   /* =================================== OTP key value =================================== */
   /* Only configure when using HMAC */
   otp_key_0x220: "9874918301909234686574856692873911223344556677889900aabbccddeeff",
}

3. Compile Firmware

To prevent TOCTOU attacks, Bootloader (IMG1) does not support XIP and needs to be configured in menuconfig to run IMG1 in SRAM:

$ ameba.py menuconfig

(Top) -> CONFIG Link Option -> IMG1(Bootloader) running on FLASH or SRAM

Execute the compilation command. The SDK script will automatically sign the firmware according to the configuration in manifest.json5:

$ ameba.py build

4. Deploy Flash Loader

After enabling Secure Boot, the chip can only boot from authorized firmware. The Flash Loader (tool firmware used for downloading firmware) is also part of the chain of trust and must be signed with the same key and algorithm as the target firmware.

When sboot_enable: true is set in manifest.json5, the build system automatically signs the Flash Loader during the CMake configuration phase. After building, the signed file is output to:

build_RTLxxx/floader_xxx.bin

Note

Each time you change keys or modify signature and hash algorithms, you must rebuild to generate a Flash Loader matching the new configuration; otherwise, the programming tool will not function correctly.

Copy the floader_xxx.bin to the corresponding path below, overwriting the existing file, based on your programming method:

Programming Method	Target Path
ImageTool.exe (GUI tool)	{ImageTool}/Devices/Floaders/
Mass production / VS Code plugin	{SDK}/Tools/ameba/Flash/Devices/Floaders/

Mass Production Stage

5. Burn Secure Boot Related OTP Bits

Warning

• CONFIG_ATCMD_SECURE must be enabled in menuconfig before using AT+SEC commands (disabled by default). Path: CONFIG SHELL -> Enable ATCMD SECURE.

• OTP burning prerequisite: a normally bootable firmware must exist in the device Flash to send AT commands via serial port. The key strings in the following commands are for example only and should not be used in production.

• OTP area can only be written once and cannot be erased or undone. Please carefully verify the address and data before executing write commands.

• In the mass production stage, it is recommended to verify on a small number of sample devices before performing batch operations.

• Pay special attention to whether OTP addresses are in logical zone or physical zone. For specific OTP operation methods, please refer to OTP Serial Programming Chapter.

Step 5.1: Burn ROT Public Key Hash

Burn the public key hash to OTP to establish a tamper-proof trust anchor.

ECC Configuration InstructionsPQC Configuration Instructions

ECC Configuration Instructions:

Find image1 -> sboot_public_key_hash in manifest.json5 and write it to the PK1 area:

AT+SEC=SBOOT_PK,pk1,72B2E1CB0E8F715262AF38DFA0E522C95660D0EBFD920F4B1A229845E599C697

If an independent certificate key is configured (using PK2 to verify Cert), you also need to write the cert public key hash value to PK2 and modify the ameba_bootcfg.c configuration file:

AT+SEC=SBOOT_PK,pk2,XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX

Note that in PQC or hybrid signature mode, PK2 is fixed for PQC public key hash.

Step 5.2: Burn HMAC Key (only required for HMAC mode)

This step is only required when sboot_hash_alg in manifest.json5 is set to HMAC. Write the HMAC key:

AT+SEC=SBOOT_HMAC,9874918301909234686574856692873911223344556677889900aabbccddeeff

The command automatically reads back and verifies the OTP after writing.

Step 5.3: Enable Secure Boot

Choose the appropriate enable method based on the current stage:

Development Debugging StageMass Production Delivery Stage

Development Debugging Stage:

The development debugging stage is used to verify the signature process and allows disabling Secure Boot by modifying logical OTP after failure. Only need to set the corresponding bit at logical address 0x3:

• ECC Secure Boot:

  AT+SEC=SBOOT_EN,temp
  

• PQC Secure Boot:

  AT+SEC=SBOOT_PQC,temp
  

• Hybrid Signature Mode: enable both ECC and PQC:

  AT+SEC=SBOOT_EN,temp
  AT+SEC=SBOOT_PQC,temp
  

To disable the temporary enable above (this has no effect if permanently enabled via perm):

AT+SEC=SBOOT_EN,temp_off
AT+SEC=SBOOT_PQC,temp_off

6. Download Firmware

Use ImageTool and the signed Flash Loader to download the firmware to the device. At startup, the chip will read this signature information for verification.

Runtime Stage

7. Reset Verification

After startup, check the serial port log to confirm the Secure Boot status.

ECC Verification LogPQC Verification Log

ECC Verification Log:

ECC Secure Boot enabled log:

IMG1 SBOOT EN

Secure Boot in RMA State

The above steps cover the Secure Boot configuration under the normal mass production process. When a product needs to be returned to the factory for analysis due to failure, it will enter RMA Return Merchandise Authorization State .

In RMA state, the OTP secure area cannot be read or written, which can protect user confidential information such as keys from leaking. Realtek provides an independent RMA Secure Boot mechanism. The chip only detects whether the current firmware is signed by an “RMA private key”. The Secure Boot verification mechanism in normal mode becomes invalid.

Depending on whether the RMA public key hash value is burned, there are two operating states in RMA mode:

• RMA public key hash value burned: Secure Boot is forcibly enabled in RMA mode, only allowing firmware signed by the corresponding RMA private key to run.

• RMA public key hash value not burned: Secure Boot is disabled in RMA mode, allowing arbitrary code to run.

It is recommended to maintain RMA keys different from the regular Secure Boot keys (PK1 and PK2). By burning OTP to set a group of public key hashes (physical address 0x720~0x73F) specifically used for RMA mode, permission isolation can be achieved.

Steps to enable RMA Secure Boot:

1. Burn RMA public key hash value (physical address 0x720):

   AT+OTP=WRAW,0x720,0x20,<RMA public key hash value>
   

2. Lock RMA public key hash (physical address 0x702):

   AT+OTP=WRAW,0x702,0x1,FB
   

Caution

• In RMA state, PQC Secure Boot verification will be automatically skipped, and only RMA ECC Secure Boot verification is performed.

• Flash Loader: The Flash Loader used to download firmware in RMA mode must also be re-signed using the RMA key.

• HMAC Limitation: If the HMAC algorithm was locked during mass production, this restriction must also be followed in RMA mode. However, due to the user information protection mechanism in RMA state, software cannot read the correct HMAC key in the OTP area and can only read 0xFF. Therefore, when compiling RMA firmware, the HMAC key field in manifest.json5 needs to be filled with all 0xFF.

Note

After entering RMA state, if RSIP is enabled, the RSIP decryption key read at this time will be all Fs, which will prevent the firmware from being decrypted correctly, resulting in a startup error. This problem can be temporarily circumvented by changing the key to all Fs when compiling the firmware.