Security Mechanism RTL87x3E/RTL87x3D

This document is about the following content for RTL87x3E and RTL87x3D:

  1. How to enable secure features on a non-secure IC.

  2. How to generate an RSA signature key.

  3. How to prepare RSA-signed images for the secure IC.

For secure IC, the secure mechanism can be activated in the boot flow. It can trigger the eFuse legality verification, and enable the integrity and authenticity validation for the images. For non-secure IC, only some parts of the fields in the image header are checked, and the integrity verification of the image is usually disabled due to time consumption. If the IC is being used in non-secure status in the project and does not need to be enabled to secure status, please skip this document.

Note

Users can check the IC secure status by clicking on the Check Secure Boot button on the RD_Download page of MPPG Tool.

Secure Mechanism

The secure mechanism is used in the boot procedure. It is related to the RSA signature and verification of the image.

Secure Boot

Secure boot is used to enhance security authentication for the images in the boot procedure. Various algorithm mechanisms are used for the images in the different procedures. These mechanisms include RSA-2048 signature, AES CMAC algorithm, AES ECB algorithm, AES CBC algorithm, SHA256 algorithm, and CRC algorithm.

  • If an image does not have valid CMAC value in the image header, RSA verification will be performed during the first boot procedures. The CMAC value will then be updated in the boot procedure if the RSA verification is successful. Subsequent boot procedures will only require CMAC verification, thereby speeding up the boot time.

  • The image header contains fields for SHA256 value and CRC value. These values are typically used to check the image integrity during OTA upgrade procedures. The SHA256 algorithm is also used in the RSA verification procedure.

  • The AES ECB algorithm is used in the eFuse key management, while the AES CBC algorithm is used in the image encryption and decryption procedure for the RAM code in the image. The application image is usually executed as flash XIP code due to its large size that cannot be put in the RAM.

  • The RSA algorithm and AES algorithm for images are used in conjunction with the key management mechanism in the eFuse. The AES keys for image RAM code encryption and decryption are specific to the IC part number and are protected by RTK as proprietary information. The RSA keys, on the other hand, can be generated and held privately by users. It is important for users to adhere to the RSA verification procedure.

The RSA verification process is used for the image authentication, and there are two essential checking points for the images:

  1. The RSA public key in the image is checked against the RSA public key hash stored in the eFuse. This ensures that the public key used for verification is trusted and matches the expected key.

  2. The RSA signature in the image is verified to ensure the integrity and authenticity of the image. This signature serves as a cryptographic proof that the image has not been altered or tampered with.

If the secure boot status is enabled, the RSA public key hash needs to be burned into the eFuse of the IC. Additionally, all important images, such as the application image developed by users, need to be signed before downloading into flash. With the tool provided by RTK, different users can generate their own unique RSA key. By bonding the chip with the key, potential risks resulting from image leakage by users can be prevented.

If User A and User B generate RSA keys separately, their RSA keys will be different and private. If User A wants to modify the images to run on User B's device, User A will not get User B's RSA key. As a result, the modified images cannot run on User B's device. Additionally, since the RSA keys between User A and User B are different, their images cannot run on each other's devices. Therefore, protecting the RSA key is very important.

If the IC is initially in a non-secure status, it will transition to a secure status when a user bonds an RSA key with the IC.

Note

Secure boot is not designed to prevent images in flash from being unintentionally or maliciously damaged. It is designed to avoid the following situations:

  1. Acquiring and tampering with the user's images by hackers: Secure boot helps protect against unauthorized access to and modification of the user's images by validating the integrity and authenticity of the images using RSA verification procedures.

  2. Attempts to re-run the acquired and modified images in the user's IC: Secure boot ensures that only trusted and validated images can be executed on the device, preventing modified images from running and potentially compromising the customer's product behavior.

RSA Signature

This document will reference several important concepts about RSA signature, which are clarified below.

  1. RSA Sign: It refers to the action of applying an RSA signature on the image using the tool provided by RTK.

  2. RSA Verify: It refers to the action of performing RSA verification on the image stored on flash by secure bootloader.

  3. RSA Key: It refers to the RSA private key in PEM format generated by the RSA key generator tool provided by RTK. This key is intended to be kept by users and used for RSA signing of their images.

  4. RSA Public Key Hash: It refers to the SHA256 hash file in the binary format that is generated by the RSA key generator tool. This file is intended to be kept by users and used for burning into eFuse. The secure bootloader will check whether the RSA public key hash matches with the RSA public key in the image header during image authentication.

Chapter Reading Guide

Users can refer to the different parts of this document as follows:

  1. The secure EVB has already been bonded with the RTK default RSA Key, so there is no need to burn any key hash into the EVB. Users only need to follow the instructions in Sign Images by Re-sign Tool to do the re-sign step with the default key.

  2. The secure IC for MP, provided directly by RTK, has not been bonded with any RSA key. Users should refer to MP Flow for Secure-Enabled Chip to undergo the entire validation process.

  3. If users need to convert the IC from a non-secure state to a secure state, skip to the chapter MP Flow for Secure-Enabled Chip to complete the whole validation process. The non-secure IC will be changed into a secure state once the RSA public key hash is burned into the eFuse.

Prerequisites

The images should be signed by RSA private key, and the RSA public key hash should be burned on the eFuse. These operations depend on the realted tools.

Toolset

First, please ensure that you have the following tools prepared:

  • RSA Key Generator (v0.5.3 or above): This tool is used to generate the customer's own RSA key and public key hash.

  • Re-sign tool (v3.7 or above): This tool is used to re-sign images that require re-signing.

  • MPPG Tool (v6.1.81.0 or above):

    • Use the pack function under the tool menu of MPPG Tool to pack the signed images.

    • Use the tool to download the packed signed images into flash.

    • Use the tool to burn the RSA public key hash into eFuse. Note that this step is only required once for each IC.

Images

Please prepare the images that need to be downloaded for the project. Note that data type images are usually not authenticated by RSA signature in the secure boot flow. Examples of data type images includes system configuration image, VP data image, application UI parameter image, DSP UI parameter image, and ANC image. However, the authentication rules can be updated in the boot patch and FSBL, so which images require signatures may vary depending on the specific project.

RTL87x3E Images

Take the default images for the primary device provided in the bin directory of the RTL87x3E SDK package as an example, and there are 16 images listed below to be downloaded.

Images under the bank directory are shown in the following figure:

../../../../_images/RTL87x3E_SDK_IMG_1.png

RTL87x3E Images

Images generated by the MCUConfig Tool are shown in the following figure:

../../../../_images/RTL87x3E_SDK_IMG_2.png

RTL87x3E Configuration Images

The image type and image name mapping table for RTL87x3E is shown in the following table.

RTL87x3E Images Table

No.

Image Type

Image Name

1

System Config Image

SYSTEM_Config_xxxx.bin

2

Boot Patch Image

boot_patch_xxxx.bin

3

Platform Extension Image

platform_ext_image_xxxx.bin

4

Bluetooth Controller Extension Image

lowerstack_ext_image_xxxx.bin

5

Bluetooth Host Imag

upperstack_xxxx.bin

6

VP Data Image

VPData_xxxx.bin

7

OTA Header Image

OTAHeader_xxxx.bin

8

FSBL Image

fsbl_xxxx.bin

9

System Patch Image

sys_patch_xxxx.bin

10

Stack Patch Image

stack_patch_xxxx.bin

11

Application Image

app_xxxx.bin

12

Application UI Parameter Image

App_Config_xxxx.bin

13

DSP System Image

dsp_sys_image_xxxx.bin

14

DSP Application Image

dsp_app_image_xxxx.bin

15

DSP UI Parameter Image

dsp_config_image_xxxx.bin

16

ANC Image

ANCxxxxx.bin

RTL87x3D Images

Take the default images in the bin directory of RTL87x3D SDK package as an example, there are 11 images listed below to be downloaded.

../../../../_images/RTL87x3D_SDK_IMG_1.png

RTL87x3D Images

../../../../_images/RTL87x3D_SDK_IMG_2.png

RTL87x3D Configuration Images

The image type and image name mapping table for RTL87x3D is shown in the following table.

RTL87x3D Images Table

No.

Image Type

Image Name

1

System Config Image

SYSTEM_Config_xxxx.bin

2

Boot Patch Image

boot_patch_xxxx.bin

3

OTA Header Image

OTAHeader_xxxx.bin

4

FSBL Image

fsbl_xxxx.bin

5

ROM Patch Image

patch_bankxxxx.bin

6

Stack Patch Image

stack_patch_xxxx.bin

7

Application Image

app_xxxx.bin

8

Application UI Parameter Image

App_Config_xxxx.bin

9

DSP1 System Image

dsp1_sys_image_xxxx.bin

10

DSP1 Application Image

dsp1_app_image_xxxx.bin

11

DSP2 System Image

dsp2_sys_image_xxxx.bin

12

DSP3 Application Image

dsp3_app_image_xxxx.bin

13

DSP UI Parameter Image

dsp_config_image_xxxx.bin

14

ANC Image

ANCxxxxx.bin

MP Flow for Secure-Enabled Chip

The main purpose of validation on a secure chip is to establish a bond between the chip and an RSA key. Note that this process only needs to be done once for a new secure chip.

For a new secure chip, please guarantee the following four points:

  1. Ensure there is a well-kept RSA key (e.g., default_rsa_key.pem) and its corresponding public key hash (e.g., default_rsa_key_hash.bin).

  2. The public key hash should be downloaded into eFuse (note that this step can only be performed in MP mode of MPPG Tool).

  3. The images that need to be re-signed should be re-signed.

  4. Make sure the images that have been re-signed with the correct RSA key are downloaded into flash memory of the secure chip.

For a validated secure chip, please make sure the following two points:

  1. The images that need to be re-signed should be re-signed with the correct RSA key.

  2. The correctly signed images should be downloaded into flash.

Generate RSA Key and Key Hash by RSA Key Generator

RSA key generator tool is a Windows command-line tool.

Open the command window in the directory of tool\Gadgets\rsa_key_generator.exe and input command:

rsa_key_generator.exe -g file_name

Then a key named file_name and its corresponding hash will be generated.

For example, if a key file named rsa_key is to be generated, just input the command as shown in the following figure:

rsa_key_generator.exe -g rsa_key
../../../../_images/RSA_Key_and_Key_Hash.png

Generate RSA Key Pair and Public Key Hash

Three files will be generated in the current directory:

  1. rsa_key.pem: It is the RSA private key needed by the re-sign tool to sign images. Keep this file secure and ensure it is properly backed up.

  2. rsa_key.pub: It is an appendant RSA public key, which has no practical role for validation and can be ignored.

  3. rsa_key_hash.bin: It is the RSA public key hash file needed by the MPPG Tool to validate a new secure chip.

In addition to RSA key generator tool, a default RSA key and its corresponding public key hash file (default_rsa_key.pem and default_rsa_key_hash.bin) are provided in SDK and secure tool package by RTK, as shown in the following figure.

../../../../_images/Default_RSA_Key_and_Key_Hash.png

Default RSA Key and Key Hash

Note

The default RSA key is provided for all SDK users by RTK. For the customer in the development stage, the default RSA key can be used to validate secure chip quickly and reduce the risk of the chaos of key management caused by the generation of multiple keys. However, this ease of use will eliminate secure boot's security advantages. Therefore, it is strongly recommended that users use the tool to generate their own RSA key and hash in the MP stage and keep them safely to really protect their products.

Sign Images by Re-sign Tool

Re-sign tool is a Windows command-line tool. It's under tool\Gadgets\resign_tool directory of the SDK. It can be used to re-sign a single image or all the images in a directory at one time.

Re-sign command line for a single image is as follows:

resign_tool.exe -f img_file.bin -k rsa_key.pem

Re-sign command line for all images in a directory command line is as follows:

resign_tool.exe -d resign_imgs_dir -k rsa_key.pem

For RTL87x3E, --sign_all needs to be used with -d resign_imgs_dir for the SDK images of RTL87x3E. For RTL87x3D, --sign_all are not needed in the re-sign command for image directory. For RTL87x3E, re-sign command line for all images in a directory command line is as follows:

resign_tool.exe -d resign_imgs_dir -k rsa_key.pem --sign_all

The flow about how to re-sign images by re-sign tool and RSA private key (generated in Generate RSA Key and Key Hash by RSA Key Generator) is described below.

  1. Create a new directory named resign_imgs in the resign_tool_amd64_v3.4 directory.

  2. Copy the images that need to be re-signed or all SDK images (refer to Images) to resign_imgs directory.

  3. Copy rsa_key.pem generated in Generate RSA Key and Key Hash by RSA Key Generator to re-sign tool directory. Open the command window in this directory and input command.

For RTL87x3D, use the following command:

resign_tool.exe -d resign_imgs -k rsa_key.pem

For RTL87x3E, re-sign all images under the specified directory, use the following command:

resign_tool.exe -d resign_imgs_dir -k rsa_key.pem --sign_all

For RTL87x3E, only re-sign application image under the specified directory, use the following command:

resign_tool.exe -d resign_imgs_dir -k rsa_key.pem --sign_app_only

For RTL87x3E, re-sign all images as the following figure:

../../../../_images/RTL87x3E_resign_all.png

RTL87x3E Re-sign All Images

For RTL87x3E, only re-sign application image as the following figure:

../../../../_images/RTL87x3E_resign_app_only.png

RTL87x3E Re-sign Application Image Only

For RTL87x3D, re-sign all images as the following figure:

../../../../_images/RTL87x3D_resign_dir.png

RTL87x3D Re-sign Images under the Directory

Note

  1. The file content and file name of images will change after being re-signed.

  2. Some old versions of Windows systems may fail with re-sign tool. If users encounter this problem, please refer to the usage document in the tool directory to solve it.

  3. The re-sign tool supports re-signing a single image or images in a directory for both RTL87x3E and RTL87x3D.

  4. The re-sign tool may update in the future, get the re-sign tool under tool\Gadgets\resign_tool directory of the SDK.

Pack Images by MPPG Tool

The image pack function is integrated in the MPPG Tool under the menu Tool ‣ Pack. Using this tool, all images to be downloaded into flash can be packed into one file.

For RTL87x3E and RTL87x3D, the pack file types are different, but the pack procedures are similar.

First, select the IC Series and IC Type on the MPPG Tool start page.

The flow of pack function is described below, taking RTL87x3E pack images as an example.

  1. Copy all the images (including images that do not need to be signed in SDK and images that have been re-signed) to a folder (e.g., imgs_for_pack) before packing.

  2. Open pack function integrated in the MPPG Tool through the menu Tool ‣ Pack, and select For MP mode.

    ../../../../_images/pack_secure_step1.png

    Open Pack Image Function

  3. Click the Load Flash Layout... button to load flash map.ini, e.g., RTL87x3E-SDK-Vx.x.x.x\bin\flash_map_config\flash_4M.

    ../../../../_images/pack_secure_step2.png

    Load Flash Layout File

  4. Choose Bank0 or Bank1 and click Add File(s) ... button to add all the images in imgs_for_pack directory. For RTL87x3E and RTL87x3D, the supported image types are different.

    ../../../../_images/pack_secure_step3.png

    Add Images to Pack

  5. After images are loaded in, the log window in the lower right corner will prompt whether the information such as images format, version, address and so on are all passed by checking.

    ../../../../_images/pack_secure_step4.png

    Check Image Loading Log

  6. Click Pack ... button to see the pack done prompt window.

    ../../../../_images/pack_secure_step5.png

    Pack Images

  7. The packed image (image_pack_bank0-xxxxxxxxx.bin) will be generated in the selected directory.

    ../../../../_images/pack_secure_step6.png

    Generate Packed Image

Note

For validated secure chip (that is, RSA key hash has been downloaded into eFuse), packing images before downloading is not necessary. The RD mode provided by MPPG Tool can support single image downloading, users can refer to MPPG Tool in Tool Set.

The reason why images need to be packed in secure chip validation is:

  1. The function of burning RSA key hash into eFuse is only supported in MP mode of MPPG Tool.

  2. In MP mode of MPPG Tool before v6.1.124.0, RSA key hash must be burned together with images downloading. In the MPPG Tool v6.1.124.0 or above, RSA key hash can be burned independently without downloading the image.

  3. In MP mode of MPPG Tool, only the packed images processed by the pack function can be downloaded.

Download Public Key Hash by MPPG Tool

MPPG Tool is a Windows tool with a user interface. It is used to download images into flash. There are two modes in this tool: RD mode and MP mode. Please refer to the MPPG Tool User Guide for the specific usage of the two modes. This document will only describe how to download the RSA key hash to eFuse in MP mode.

Note

The MPPG Tool supports downloading the public key hash independently in the version v6.1.124.0 or above, refer to load RSA key file. Prior to version v6.1.124.0, the public key hash should be downloaded along with the packed image.

For RTL87x3E, the power supply for the eFuse is dependent on the VBAT. Please make sure the VBAT is charged.

  1. Before using MPPG Tool, make sure that the serial port of the device is connected properly and the system is in downloadable mode (aka HCI mode).

  2. Open MPPG Tool, first choose the IC Series and IC Type, then click the Confirm button.

    ../../../../_images/download_secure_step1.png

    Select Chip Type in MPPG Tool Startup Page

  3. Click Type in the menu bar and choose MP mode.

    ../../../../_images/download_secure_step2.png

    Select MP Mode

  4. Switch to the MP_Settings interface, and the interface is inoperable at this moment. It is used to protect the setting against arbitrary modification.

  5. Click the Unlock button and enter the password in the pop-up window to make the setting interface operable.

    The default unlock password is 1, and the user can change the unlock password through the menu Settings ‣ Password Modify. If the user has forgotten the current unlock password, please refer to the UNLOCK_PASSWORD item under the UNLockSetting section in the MPPGToolSetting.ini under the MPPG Tool directory.

    ../../../../_images/download_secure_step3.png

    Unlock Setting

    ../../../../_images/download_secure_step4.png

    Input Password

    ../../../../_images/password_modify_menu.png

    Password Modify Menu

    ../../../../_images/modify_password_ui.png

    Modify Password

  6. Load the packed image (refer to Pack Images by MPPG Tool) for the Packet File box in the MP_Settings interface.

    This step is only used for the MPPG Tool before the version v6.1.124.0. For the MPPG Tool v6.1.124.0 or above, user can skip this operation.

  1. Load RSA key file, then click the Lock button.

    For the MPPG Tool before v6.1.124.0, the RSA public key hash file should be downloaded in the packed image downloading procedure.

    For the MPPG Tool v6.1.124.0 or above, the RSA public key hash can be downloaded independently.

    For RTL87x3D, if the IC part number supports writing the public key SHA256, In the MPPG Tool MP_Settings page, there will be a groupbox about Write sha256 key in the UI. Enable the Write sha256 key option and load the rsa_key_hash.bin (refer to Generate RSA Key and Key Hash by RSA Key Generator).

    ../../../../_images/RTL87x3D_write_key_sha256.png

    Write RSA Public Key SHA256 for RTL87x3D

    For RTL87x3E, the RSA public key SHA256 file should be downloaded for secure IC. If the RSA public key SHA256 file is downloaded on a non_secure IC, the non-secure IC will be updated to the secure status. In the MPPG Tool MP_Settings page, there's a groupbox about Write Key in the UI. Enable the Write RSA Key SHA256 option and load the RSA public key hash file (refer to Generate RSA Key and Key Hash by RSA Key Generator).

    ../../../../_images/RTL87x3E_write_rsa_key_sha256.png

    Write RSA Public Key SHA256 for RTL87x3E

    For the MPPG Tool v6.1.124.0 or above, user can select the checkbox of Only write key (bypass download image) in the groupbox of Write key to skip the downloading procedure of the packed image.

    ../../../../_images/only_write_pub_key_hash.png

    Bypass Downloading Image and Only Write Key

  2. Switch to the MP_Download interface, and click the Download button.

    ../../../../_images/download_secure_step6.png

    Download

Note

For each secure IC, RSA public key hash binary file can only can be downloaded once. Repeated downloading will get an error prompt on the MPPG Tool.

FAQs

  1. What is the meaning of the log wdt reset(3), sb = 987, id = 0x2793, bk = 0, lr = 0x1d15, sp = 0x289398? In the log, id = 0x2793 represents the image ID of the image validated currently. sb = 987 represents the code line number of the fail operation. All the image ID values are as follows (not all image IDs are used for RTL87x3E or RTL87x3D, refer to Images):

    typedef enum _IMG_ID
{
   IMG_OCCD        = 0x278E,
   IMG_BOOTPATCH   = 0x278F,
   IMG_OTA         = 0x2790, /* OTA header */
   IMG_SBL         = 0x2791,
   IMG_MCUPATCH    = 0x2792,
   IMG_MCUAPP      = 0x2793,
   IMG_DSPPATCH    = 0x2794,
   IMG_DSPAPP      = 0x2795,
   IMG_MCUDATA     = 0x2796,
   IMG_DSPDATA     = 0x2797,
   IMG_ANC         = 0x2798,
   IMG_EXT1        = 0x2799,
   IMG_EXT2        = 0x279A,
   IMG_EXT3        = 0x279B,
   IMG_PLATFORM    = 0x279C,
   IMG_LOWERSTACK  = 0x279D,
   IMG_UPPERSTACK  = 0x279E,
   IMG_FRAMEWORK   = 0x279F,
   IMG_SYSDATA     = 0x27A0,
   IMAGE_MAX
} IMG_ID;

typedef enum _PRE_IMG_ID
{
   PRE_IMG_SYSPATCH         = IMAGE_MAX,
   PRE_IMG_STACKPATCH       = 0x27A2,
   PRE_IMG_UPPERSTACK       = 0x27A3,
   PRE_IMG_VP               = 0x27A4,
   PRE_IMAGE_MAX
} PRE_IMG_ID;

    Taking RTL87x3E as an example, the line number of 987 means RSA signature verification has failed, and the integrity checking for application image has failed. Maybe the application image on the flash has been modified. For RTL87x3D, the line number of 1021 means RSA signature verification has failed.

  2. What is the meaning of the log wdt reset(3), sb = 975, id = 0x2793, bk = 0, lr = 0x10f, sp = 0x2893a0 for RTL87x3E? In the log, id = 0x2793 represents the application image. sb = 975 indicates that the RSA public key hash verification has failed. Check whether the application image has been downloaded to the specified flash address, and that the image is signed with the correct RSA private key. Then check whether the RSA public key hash has been burned on the eFuse by clicking on the Check Secure Boot button on the RD_Download page of MPPG Tool. For RTL87x3D, the line number 1009 indicates that the RSA public key hash verification has failed.

  3. What is the meaning of the log port 0, SHA Conflict Error ! in MPPG Tool during the download process of images in MP mode? This log indicates that an incorrect RSA key hash has been tried to be burned into a secure chip which had already been bonded with another key hash.

  4. What is the secure boot normal flow?

    ../../../../_images/secure_boot_flow.png

    Secure Boot Flow for RTL87x3E and RTL87x3D

    For RTL87x3E, the boot patch image is required.

    For RTL87x3D, the boot patch image is required only when the efuse disable_boot_patch filed is burned as b'00. If MPPG Tool v6.1.112.0 or above is used to download images on the IC, the disable_boot_patch will be burned as b'00, and the boot patch image will be required.