Secure Image Protection (RSIP)

Introduction

Security Image Protection (RSIP) 专为固件保护设计。其通过AES加密技术对整个或部分Flash存储器中的数据进行加密，防止遭到非法固件复制和产品破解。

../../_images/rsip_work_flow.svg

RSIP使用方法：

  1. 开发和生产阶段：客户需要在image编译时提供RSIP密钥。这把密钥在后用于编译后处理阶段的固件加密。产线上flash中是烧录的是密文固件，同时将RSIP密钥烧录到OTP区域。

  2. 存储阶段：产品flash中的固件是加密固件，保证固件无法被解密或者用于其它产品。同时MCU中OTP key限定了只能从特定的固件boot，从而保证固件无法被替换。

  3. 运行阶段：RSIP经过SPIC自动从flash中读取加密固件。使用OTP中存储的RSIP key进行解密出明文，返回给CPU。

../../_images/rsip_brife.svg

RSIP并不提供写入加密数据的功能，只支持自动读取解密。当CPU在自动模式下从Flash读取数据时，数据会在传输过程中实时解密。 当从Flash读取数据或执行代码时，系统默认选择自动模式。若在用户模式下直接读取，数据则不会解密。 若需进行手动读写flash操作，SDK中提供了flash操作的API接口。

RSIP-AES Entry

RSIP-AES模块中共包含8个Entry （但是对于amebasmart，只有6个），每个Entry均具备： 独立IV值（Initialization Vector）、加密算法配置（CTR或XTS模式）、独立启用/禁用控制位。

在自动模式下： 当访问已启用Entry对应地址区域的数据时，系统将在读取过程中进行实时解密； 若访问未启用Entry对应的地址区域，数据将以明文形式直接传输（RSIP模块不会触发实时解密）。

RSIP OTP

Name

Address

Size

Default

Description

RSIP Enable

Logical Map 0x3[3]

(for test)

1 bit

0

RSIP is enabled or not.

1: RSIP is enabled

0: RSIP is disabled

RSIP Enable

Physical Map 0x368[2]

1 bit

1

RSIP is enabled or not.

0: RSIP is enabled

1: RSIP is disabled

RSIP Key 1

Physical Map 0x2C0 ~ 0x2DF

32 bytes

Each Byte 0xFF

RSIP key will be stored in security OTP and auto-loaded to RSIP when boot.

The most significant byte of the key is stored last (at the highest storage address).

For example, the RSIP key is [32982100546871a0aa983b298756 2233], value 0x32 needs to be programmed into OTP 0x2C0, 0x98 into 0x2C1, and so on.

RSIP Key 2

Physical Map 0x2E0 ~ 0x2FF

32 bytes

Each Byte 0xFF

RSIP key will be stored in security OTP and auto-loaded to RSIP when boot.

The most significant byte of the key is stored last (at the highest storage address).

For example, the RSIP key is [32982100546871a0aa983b298756 2233], value 0x32 needs to be programmed into OTP 0x2C0, 0x98 into 0x2C1, and so on.

RSIP Mode

Physical Map 0x369[1:0]

2 bit

0x3

Encryption algorithm for Bootloader.

00/11b: XTS mode

01/10b: CTR mode

RSIP Key1 Read Protection

Physical Map 0x366[7]

1 bit

1

0: Enable read protection for RSIP Key1 to prevent from being read out.

1: Disable read protection for RSIP Key1

RSIP Key1 Write Protection

Physical Map 0x367[0]

1 bit

1

0: Enable write protection for RSIP Key1 to prevent from being programmed to all 0 by hacker

1: Disable write protection for RSIP Key1

RSIP Key2 Read Protection

Physical Map 0x367[1]

1 bit

1

0: Enable read protection for RSIP Key2 to prevent from being read out.

1: Disable read protection for RSIP Key2

RSIP Key2 Write Protection

Physical Map 0x367[2]

1 bit

1

0: Enable write protection for RSIP Key2 to prevent from being programmed to all 0 by hacker

1: Disable write protection for RSIP Key2

RSIP Mode Write Protection

Physical Map 0x367[3]

1 bit

1

0: Enable write protection for RSIP Mode to prevent from being programmed by hacker

1: Disable write protection for RSIP Mode

Build Secure Image

To use RSIP to protect the image, users should follow these steps:

  1. Generate RSIP keys and IV values for each image, the keys and IV values can be random, and the keys should be 32 bytes.

  2. Make sure RSIP related OTP bit are set according to RSIP OTP.

    1. Write RSIP Key to OTP physical map. Users can read it back to check if it is written correctly. If not match, re-write it.

      • Using the following command to program RSIP key 1:

      efuse wraw 0x2C0 20 E2A0D6500BBF1DD8DC212098C230EB731ECE3A81AA11D0E6E538FA36BBA4FF6E

      • Using the following command to program RSIP key 2:

      efuse wraw 0x2E0 20 6AA34203018334474B25A0600996CA0968AA6228B886FF234B4EB9628B703C0A

    2. Enable RSIP Key Read Protection and Write Protection to prevent key exposure and tampering after the written RSIP Key is confirmed.

    3. Enable RSIP function.

      When in device-development stage, it is recommended to program RSIP Enable bit in logical OTP, which can be disabled afterward. Use efuse rmap first to check value in 0x3, then enable RSIP bit (0x3 bit3).

      efuse rmap
      ../../_images/rsip_efuse_rmap.png 
      efuse wmap 0x3 1 e8

      When in device-MP stage, RSIP_EN_PHY bit should be programmed to enable RSIP permanently.

      efuse rraw
      ../../_images/rsip_efuse_rraw.png 
      efuse wraw 0x368 1 FB

      When in device-development stage, it is recommended to program RSIP Enable bit in logical OTP, which can be disabled afterward. Use efuse rmap first to check value in 0x3, then enable RSIP bit (0x3 bit3).

      efuse rmap
      ../../_images/rsip_efuse_rmap_lite.png 
      efuse wmap 0x3 1 08

      When in device-MP stage, SECURE_BOOT_EN_PHY bit should be programmed to enable secure boot permanently.

      efuse rraw
      ../../_images/rsip_efuse_rraw_lite.png 
      efuse wraw 0x368 1 FB

      When in device-development stage, it is recommended to program RSIP Enable bit in logical OTP, which can be disabled afterward. Use efuse rmap first to check value in 0x3, then enable RSIP bit (0x3 bit3).

      efuse rmap
      ../../_images/rsip_efuse_rmap_lite.png 
      efuse wmap 0x3 1 08

      When in device-MP stage, SECURE_BOOT_EN_PHY bit should be programmed to enable secure boot permanently.

      efuse rraw
      ../../_images/rsip_efuse_rraw_lite.png 
      efuse wraw 0x368 1 FB

备注

When OTP is programed, the Board needs to be reset to take the setting effect.

  1. Generate encrypted images.

    In SDK, the configuration file locates in {SDK}\amebaxxx_gcc_project\manifest.json can be used to configure security parameters, including RSIP.

     1"boot":
 2   {
 3      "IMG_ID": "0",
 4      "IMG_VER_MAJOR": 1,
 5      "IMG_VER_MINOR": 1,
 6      "SEC_EPOCH": 1,
 7
 8      "HASH_ALG": "sha256",
 9
10      "RSIP_IV": "0102030405060708",
11   },
12
13   "//": "cert/app share IMG_ID/IMG_VER, rdp img is in app",
14   "app":
15   {
16      "IMG_ID": "1",
17      "IMG_VER_MAJOR": 1,
18      "IMG_VER_MINOR": 1,
19      "SEC_EPOCH": 1,
20
21      "HASH_ALG": "sha256",
22
23      "RSIP_IV": "213253647586a7b8",
24   },
25
26   "SECURE_BOOT_EN": 0,
27   "//": "HASH_ALG: sha256/sha384/sha512/hmac256/hmac384/hmac512, hamc need key",
28   "HMAC_KEY": "9874918301909234686574856692873911223344556677889900aabbccddeeff",
29
30   "RSIP_EN": 0,
31   "//": "RSIP_MODE: 1 is XTS(CTR+ECB), 0 is CTR",
32   "RSIP_MODE": 1,
33   "CTR_KEY": "6AA34203018334474B25A0600996CA0968AA6228B886FF234B4EB9628B703C0A",
34   "ECB_KEY": "E2A0D6500BBF1DD8DC212098C230EB731ECE3A81AA11D0E6E538FA36BBA4FF6E",
35
36   "//": "Actual RDP IV is 16Byte which is composed by app RSIP_IV[7:0] + RDP_IV[15:8]",
37   "RDP_EN": 0,
38   "RDP_IV": "0123456789abcdef",
39   "RDP_KEY": "11223344556677889900aabbccddeeff11223344556677889900aabbccddeeff"

    1. Set RSIP_EN=1, and set RSIP_MODE (0 for CTR mode, 1 for XTS mode), then fill the user-defined RSIP Key and IV in (XTS mode is recommended from the perspective of safety).

    2. All images set the same RSIP mode and each image can have its own RSIP IV value, there are boot field for bootloader, app field for application image.

  2. Rebuild each project to generate encrypted image automatically as the following table, then download them into Flash.

    Project

    Encrypted image

    Download address

    km4_bootloader

    km4_boot_all.bin

    0x0800_0000

    km0_application

    km0_km4_app.bin

    0x0801_4000

    km4_application

    km0_km4_app.bin

    0x0801_4000

  3. Reset the board. When RSIP image is loaded successfully, you can see OTF EN print out in log.

     1ROM:[V1.0]
 2FLASH RATE:1, Pinmux:1
 3OTF EN
 4IMG1(OTA1) VALID, ret: 0
 5IMG1 ENTRY[3000ad39:0]
 6[KM4] [MODULE_BOOT-LEVEL_INFO]:IMG1 ENTER MSP:[30009fe4]
 7[KM4] [MODULE_BOOT-LEVEL_INFO]:IMG1 SECURE STATE: 1
 8[KM4] [MODULE_BOOT-LEVEL_INFO]:Flash ID: c8-65-17
 9[KM4] [MODULE_BOOT-LEVEL_INFO]:Flash Read 4IO
10[KM4] FLASH HandShake[0x1 OK]
11[KM4] IMG2 OTF EN
12[KM4] [MODULE_BOOT-LEVEL_INFO]:KM0 XIP IMG[0c000000:5020]
13[KM4] [MODULE_BOOT-LEVEL_INFO]:KM0 SRAM[20040000:da0]
14[KM4] [MODULE_BOOT-LEVEL_INFO]:KM0 PSRAM[0c005dc0:20]
15[KM4] [MODULE_BOOT-LEVEL_INFO]:KM0 BOOT[20004d00:40]
16[KM4] IMG2 OTF EN
17[KM4] [MODULE_BOOT-LEVEL_INFO]:KM4 XIP IMG[0e000000:6d60]
18[KM4] [MODULE_BOOT-LEVEL_INFO]:KM4 SRAM[20010000:60]
19[KM4] [MODULE_BOOT-LEVEL_INFO]:KM4 PSRAM[0e006dc0:20]
20[KM4] [MODULE_BOOT-LEVEL_INFO]:IMG2 BOOT from OTA 1
21[KM4] [MODULE_BOOT-LEVEL_INFO]:Start NonSecure @ 0xe000115 ...
22[KM0] [MODULE_BOOT-LEVEL_INFO]:KM0 BOOT UP
23[KM4] [MODULE_BOOT-LEVEL_INFO]:VTOR: 20005000, VTOR_NS:0
24[KM0] [MODULE_BOOT-LEVEL_INFO]:KM0 APP_START
25[KM4] [MODULE_BOOT-LEVEL_INFO]:KM4 APP START
26[KM0] [MODULE_BOOT-LEVEL_INFO]:KM0 CPU CLK: 40000000 Hz
27[KM4] [MODULE_BOOT-LEVEL_INFO]:IMG2 SECURE STATE: 0
28[KM0] [MODULE_BOOT-LEVEL_INFO]:KM0 VTOR:0x20000000
29[KM4] [MODULE_BOOT-LEVEL_INFO]:KM4 BOOT REASON: 0

    备注

    • When RSIP_EN is 1, the generated application image (km0_km4_app.bin) has already been encrypted individually before combination.

    • Considering the KM0 and KM4 application image are combined, users need to download the image only once (km0_km4_app.bin).

    • If you don’t use J-Link to download, you can download the encrypted images to the address with ImageTool.

    • For the IV value in manifest.json, only the lower 8 bytes will be used when doing encryption/decryption, the higher 8 bytes come from the address, so that every block has a different IV value, and users must pay attention that, if the virtual address of km4_bootloader, km0_km4 application image needed to be changed, the shell script for image encryption should be changed at the same time, users may ask Realtek for help if needed.

    • Secure image shouldn’t use RSIP, which will be encrypted by RDP. For more information, refer to 读保护（RDP）.

Secure Data Encryption/Decryption

小心

XIP is forbidden when plaintext or encrypted data needs to be written into the Flash.

For RSIP, it can only decrypt data on the fly in auto mode when CPU/cache reads from a Flash address which is within the range of enabled entries. If users want to encrypt data, another IP called IPsec is provided.

  1. Use any of the algorithms supported in IPsec to encrypt and decrypt data.

  2. Use IPsec to encrypt data, then put the encrypted data in target address in Flash, enable an entry for the encrypted data, and the data will be auto decrypted when CPU/cache reads from Flash in auto mode. (However, in this way, only CTR/XTS mode is supported, and example is provided in SDK).

Troubleshooting

Problem

Possible Causes

Solutions

Boot is failed after reset when using RSIP

RSIP is not enabled.

Check OTP logical map, make sure RSIP is enabled

RSIP Key error or writing key fails.

Check RSIP key setting

Images has not been encrypted before download.

Encrypt images and re-download

Boot log doesn’t show OTF EN

RSIP is not enabled.

Check OTP logical map, make sure RSIP is enabled

Boot still fails after checking RSIP key and images

Select inappropriate device profile in ImageTool.

Click File->Open… button on ImageTool and select profile according to chip number.