
# ARM TrustZone

ARM TrustZone技术是所有 Cortex-A 类处理器的基本功能，是通过 ARM 架构安全扩展引入的。这些扩展可在供应商、平台和应用程序中提供一致的程序员模型，同时提供真实的硬件支持的安全环境。

ARM TrustZone 技术是系统范围的安全方法，针对高性能计算平台上的大量应用，包括安全支付、数字版权管理 (DRM)、企业服务和基于 Web 的服务。TrustZone 技术与 Cortex-A 处理器紧密集成，并通过 AMBA AXI 总线和特定的 TrustZone 系统 IP 块在系统中进行扩展，所以 ARM TrustZone 技术是从硬件层次上提供的安全机制。此系统方法意味着可以保护安全内存、加密块、键盘和屏幕等外设，从而可确保它们免遭软件攻击。

目前用于 ARM TrustZone 技术的开源项目中，使用比较广泛的有 ARM Trusted Firmware 和 OPTEE OS，它们都是针对 ARM 芯片给出的底层固件开源项目，二者之间可以配合使用或单独使用。

## 系统架构

从系统架构角度看，如下是启用了 ARM TrustZone 技术后的 64 位平台系统架构图。整个系统被分成了两个世界：左边是非安全世界，右边是安全世界。安全世界可以访问两个世界的所有资源，非安全世界只能访问非安全世界的资源，如果非安全世界访问安全世界的资源，则将产生系统硬件总线报错等异常，是无法获取到资源的。

这两个世界之间的往来需要通过 ARM Trusted Firmware 作为桥梁。当 CPU 处于非安全世界时，如果想进入安全世界则需要先进入 ARM Trusted Firmware（通过 ARM 的 SMC 硬件指令），在 ARM Trusted Firmware 里的 Secure Monitor 代码会把 CPU 从非安全身份切换成安全的身份，然后再以安全身份进入安全世界。反之亦然。这个是完全从硬件级别上进行的安全和非安全身份转变。

X5 平台 的 TEE 可以理解为是 ARM Trusted Firmware + OP-TEE OS 的功能集合，它实现了安全世界里我们需求的功能以及 Secure Monitor (两个世界转换的核心代码)的功能。

![](./_static/_images/software_stack.png)

![](./_static/_images/arm_software_stack.png)

## CPU 特权等级

从 CPU 的视角看，如下是一个标准的启用了 ARM TrustZone 技术后的 CPU 特权模式等级架构图。它的特权等级分为 EL0、EL1、EL2、EL3，
根据 CPU 所处的世界又分为安全EL0、安全 EL1 或者非安全 EL0、非安全 EL1。

![](./_static/_images/exception_level.png)

X5平台的 TEE 可以理解为是 EL3 + 安全 EL1 的功能集合。

## 名词解释

| 缩写  |  全称   | 解释  |
| :-------- | :--------- | :--------- |
| TEE | Trusted Execution Environment | 安全执行环境，指的是在设备中运行受信任的代码的隔离区域，确保安全敏感操作不受恶意软件的干扰 |
| REE | Rich Execution Environment | 富执行环境，与 TEE 不同的是 REE 是设备中非安全区域的执行环境，通常承载着设备的大部分应用程序、操作系统和服务 |
| OP-TEE | Open Portable Trusted Execution Environment | 开源项目，提供一个实现了ARM架构的受信任执行环境（TEE），用于运行安全应用程序 |
| TA | Trusted Application | 受信任的应用程序，指的是在TEE中运行的应用程序，通常用于执行安全任务，如加密操作、身份认证等 |
| EL3 | Exception Level 3 | ARM架构中的异常级别，通常用来表示处理器处于最高权限级别。在TEE中，EL3常用于运行安全代码 |
| EL1/EL2 | Exception Level 1/2 | ARM架构中的其他异常级别，EL1用于运行操作系统内核，EL2用于虚拟化支持 |


# 关于 X5 TEE

## 实现机制

目前 X5 平台上的 64 位 SoC 平台上使用的是 ARM Trusted Firmware BL31 + OP-TEE OS 的组合

BL31 和 OP-TEE OS 的内存范围和生命周期如下:

| 名称  |  内存类型   |  地址范围     |  是否常驻内存     |
| :-------- | :--------- | :--------- | :-------- |
| BL31  | AON SRAM | 0x2000_0000 ~ 0x2002_0000 | 是 |
| OP-TEE OS | DDR | 0x8000_0000 ~ 0x8400_0000 | 是 |


## 固件获取

目前只提供 binary 文件，不提供源代码。

OP-TEE 的 binary 文件在如下路径
```
miniboot/bl3x/tee-header_v2.bin
miniboot/bl3x/tee-pageable_v2.bin
miniboot/bl3x/tee-pager_v2.bin
```

BL31 的 binary 文件在如下路径
```
miniboot/bl3x/bl31.bin
```

## 版本信息
BL31 和 OP-TEE 版本信息可通过启动 log 信息得到

### BL31
BL31 启动 log 信息如下

```bash
NOTICE:  BL31: v2.8(release):v1.0.8-77-g72e4fe066
NOTICE:  BL31: Built : 20:12:37, Jun 11 2025
NOTICE:  plat_setup_psci_ops: sec_entrypoint = 0x2000010c
...
```

以上信息得知: ARM Trusted Firmware 的版本号 `v2.8`。

### OP-TEE
OP-TEE 启动 log 信息如下
```
I/TC:
I/TC: OP-TEE version: 05e24fd71 (gcc version 11.3.1 20220712 (Arm GNU Toolchain 11.3.Rel1)) #32 Thu Jun  6 13:14:26 UTC 2024 aarch64
...
```

以上信息得知: OP-TEE OS 的 commit hash 值为 `05e24fd71`。

**注意: 如上打印仅供参考，版本号及日期可能随着SDK发布有变化**

# TA 开发
## 概述
TA（Trusted Application，受信任应用）是指在 TEE（Trusted Execution Environment，受信任执行环境）中运行的应用程序，它们执行高度安全的任务和敏感操作，如加密、密钥管理、身份验证、数字签名等。TA是TEE中的核心组成部分，它们在一个隔离且受保护的环境中运行，与REE（非安全世界）中的普通应用程序和操作系统隔离开来，确保敏感数据和操作不受外部恶意攻击的影响。

## 构建 TA
关于构建TA所需要的依赖在项目代码 `miniboot/optee/hobot_tee_devkit` 目录中，其中参考 demo 路径 `ta/demo` 。

要构建可信应用程序(TA)，切换到目录 `miniboot/optee/hobot_tee_devkit` 并请遵循以下步骤:

1. 将您的 TA 源代码放在 `ta/customer` 目录中。

2. 打开位于 `ta/customer` 目录中的 `Makefile`。

3. 在 `Makefile` 文件中将新建的目录名添加到 `CTA_DIRS` 变量。

4. 切换到项目代码根目录，执行以下命令编译TA: `./bd.sh lunch  ## 选择开发板类型` 和 `./bd.sh`

5. 编译完成后，在 `miniboot/optee/hobot_tee_devkit/out/ta` 目录中可以看到与 **TA源代码** 同名目录，里面就是对应的TA程序，以 `.ta` 为后缀的ELF文件。

6. 如果您需要清理构建并重新开始，您可以切换到项目代码根目录使用以下命令: `./bd.sh distclean`

7. 将编译完成的镜像烧录进开发板，启动开发板进到 linux shell 命令行，可在文件系统中，`/lib/optee_armtz` 目录找到 **ta** 程序

## TA的签名与加密

### TA的签名

TA由客户签名，目前只支持在BL2由客户签名的板子上使用，请参考[X5 Customer root rsa key hash烧录及使用](../efuse/cus_key_hash_update.html)。BL2是由地瓜签名加密的板子，不支持此形式。

#### 生成新的私钥文件

签名TA的私钥位于

```bash
miniboot/optee/hobot_tee_devkit/export-ta_arm64/keys/default_ta.pem
```

私钥格式为RSA2048，可使用openssl命令生成新的密钥

```bash
openssl genrsa -out default_ta.pem 2048
```

#### 替换optee os中的公钥

用于验签TA的公钥位于optee os中，还需要将其替换为新的公钥，通过以下工具来替换

```bash
miniboot/optee/hobot_tee_devkit/replace_ta_pubkey
```

使用方法:

- -H/--header: 输入，optee的header文件，也就是miniboot/bl3x/tee-header_v2.bin

- -t/--teeos: 输入，optee os的文件，也就是miniboot/bl3x/tee-pager_v2.bin

- -k/--key: 输入， key文件，也就是miniboot/optee/hobot_tee_devkit/export-ta_arm64/keys/default_ta.pem

- -o/--output: 输出，替换了key之后的optee os文件

执行成功之后，将新生成的文件替换miniboot/bl3x/tee-pager_v2.bin

![replace_bin](./_static/_images/replace_bin.png)

#### 编译TA

修改key文件之后，编译TA，部署TA到板端，并烧录新的optee os，即可使用客户的key来验证TA

**注意**

更换密钥default_ta.pem之后运行xtest测试case 1039会失败，需要按照optee-test仓库里ta/subkey_notes.txt的方法更新subkey

### TA加密

##### 开启TA加密功能

TA默认是只签名，不加密的，客户如果需要加密TA，需要在以下文件```miniboot/optee/hobot_tee_devkit/export-ta_arm64/mk/link.mk```中开启宏CFG_ENCRYPT_TA， 加密算法为AES128

```bash
export CFG_ENCRYPT_TA=y
```

##### 修改key文件

同时，修改key文件为客户的key，key文件的路径位于

```bash
device/horizon/x5/board_cfg/soc/bl2_cfg/user_root.key
```

##### 编译TA

修改key文件之后，编译TA，部署TA到板端，即可使用加密的TA

#### 注意

- 客户的key需要烧录到efuse中，烧录的方法参考[烧写efuse](../efuse/efuse_update.html#span-id-bl2-update-efuse-bl2efuse)。

## 单独编译 TA
**前提条件：** 请确保按上述 **步骤1~3** 完成TA源码部署，然后遵循如下步骤：

1. 切换到 `miniboot/optee/hobot_tee_devkit` 目录下

2. 检查 `build.sh` 文件中环境变量 `TOOLCHAIN_PATH` 是否为当前 **编译工具链** 所在路径，确保路径正确

3. 执行编译脚本 `./build.sh` 开始编译

4. 编译完成后，在 `miniboot/optee/hobot_tee_devkit/out/ta` 目录中可以看到与 **TA源代码** 同名目录，里面就是对应的TA程序，以 `.ta` 为后缀的ELF文件。

5. 如果您需要清理构建并重新开始，您可以使用以下命令: `./build.sh clean`

## 部署 TA
**前提条件：** 确保在 `miniboot/optee/hobot_tee_devkit/out/ta` 目录中可以看到开发的TA程序已经编译完成，以 `.ta` 为后缀的ELF文件。并且保证开发板中的镜像在启动后在 `Linux` 文件系统中存在目录 `/lib/optee_armtz` ，然后遵循如下步骤：

1. 在开发板正常启动并找到目录 `/lib/optee_armtz`

2. 使用USB线将板端与PC连接，将编译好的 TA 程序传到开发板 `/lib/optee_armtz` 目录里
以 ADB 方式为例

板端需重新挂载 rootfs 为可读写方式
```
mount / -o rw,remount
```

PC端执行如下命令，将 TA 部署到板端
**注意: 此处以 5b9e0e40-2636-11e1-ad9e-0002a5d5c51b.ta 为例，用户实际使用请以实际编译的 .ta 文件为准**
```
adb.exe push .\5b9e0e40-2636-11e1-ad9e-0002a5d5c51b.ta /lib/optee_armtz
```
ADB 使用方法请参考[通过USB连接](../../../../quick_start/connect_board.html#span-id-connect-by-usb)
