From cacdd05ab4436bd5df85f6ed0fdec058cc6d20d3 Mon Sep 17 00:00:00 2001 From: suwanghw Date: Fri, 18 Aug 2023 13:08:14 +0800 Subject: [PATCH] Optimize some descriptions and add guidance on tee xts test cases. Signed-off-by: suwanghw --- docs/opentrustee-guidelines/README-CN.md | 2 +- ...-adaptation-and-construction-guidelines.md | 232 --------- ...pentrustee-architecture-and-constraints.md | 30 +- ...e-compatibility-test-suite-introduction.md | 21 + ...able-new-platform-adaptation-guidelines.md | 461 ++++++++++-------- .../overview-of-opentrustee.md | 2 - 6 files changed, 296 insertions(+), 452 deletions(-) delete mode 100644 docs/opentrustee-guidelines/opentrustee-adaptation-and-construction-guidelines.md create mode 100644 docs/opentrustee-guidelines/opentrustee-compatibility-test-suite-introduction.md diff --git a/docs/opentrustee-guidelines/README-CN.md b/docs/opentrustee-guidelines/README-CN.md index 648af4e..bafe57e 100644 --- a/docs/opentrustee-guidelines/README-CN.md +++ b/docs/opentrustee-guidelines/README-CN.md @@ -2,7 +2,7 @@ - [OpenTrustee系统概述](overview-of-opentrustee.md) - [OpenTrustee系统架构和约束](opentrustee-architecture-and-constraints.md) -- [OpenTrustee适配和构建指导](opentrustee-adaptation-and-construction-guidelines.md) - [OpenTrustee开发TA指导](opentrustee-develop-ta-guidelines.md) - [OpenTrustee调试机制介绍](opentrustee-debug-mechanism-introduction.md) +- [OpenTrustee兼容性测试套件介绍](opentrustee-compatibility-test-suite-introduction.md) - [OpenTrustee使能新平台适配指导](opentrustee-enable-new-platform-adaptation-guidelines.md) \ No newline at end of file diff --git a/docs/opentrustee-guidelines/opentrustee-adaptation-and-construction-guidelines.md b/docs/opentrustee-guidelines/opentrustee-adaptation-and-construction-guidelines.md deleted file mode 100644 index dff76f7..0000000 --- a/docs/opentrustee-guidelines/opentrustee-adaptation-and-construction-guidelines.md +++ /dev/null @@ -1,232 +0,0 @@ -# OpenTrustee 适配和构建指导 - -## Tee Client的适配和构建 - -### Tee Client使能实例 - -本章节讲述如何针对一款芯片适配TEE Client，在相应配置json文件中增加tee_client部件即可。 - -以RK3568芯片为例，在vendor/hihope/rk3568/config.json中增加以下内容： - -```c -{ - "subsystem": "tee", - "components": [ - { - "component": "tee_client", - "features": [] - } - ] -} -``` - -### Tee Client编译命令 - -Tee Client代码位置：`base/tee/tee_client` - -以RK3568芯片为例，运行以下命令编译TEE Client部件，产物路径：out/rk3568/tee/tee_client - -```shell -./build.sh --product-name rk3568 --ccache --build-target tee_client -``` - -## Tzdriver的适配和构建 - -### 概述 - -tzdriver是TEE的内核驱动，主要功能是在整个TEE子系统中起连接作用，是使用TEE OS服务的桥梁，tzdriver处理来自于tee\_client的ioctl命令，并通过smc指令从REE切换到TEE。 - ->![](public_sys-resources/icon-caution.gif) **注意：** ->单独适配tzdriver，系统并不能正常启动，必须同时适配TEE OS。 - -### 适配指导以及适配实例 - -本章节中会讲述如何针对一款芯片适配tzdriver，此章节中以RK3568芯片为例。 - -第一小节介绍tzdriver入口和tzdriver代码位置，本章下面几个小节，每小节都是一个适配步骤。（这几个适配步骤顺序无关，但推荐将配置选项放到最后） - -#### tzdriver入口 - -- Linux内核tzdriver代码位置：base/tee/tee\_tee\_tzdriver/linux。 - -tzdriver是内核中的一个字符设备驱动。 - -tzdriver初始化时会创建一个字符设备文件，一般为/dev/tc\_ns\_client，用户态进程可以打开此节点，以及通过ioctl接口调用tzdriver相关功能。 - -tzdriver总入口在core/tc\_client\_driver.c中的tc\_client\_ioctl函数。 - -设备节点函数接口： - -```c -static const struct file_operations_vfs g_tc_ns_client_fops = { - .open = tc_client_open, - .close = tc_client_close, - .ioctl = tc_client_ioctl, - .mmap = tc_client_mmap, -}; -``` - -#### 工程编译适配 - -tzdriver需要被编译到内核中作为内核驱动。 - -- Linux内核tzdriver编译适配 - - 在Linux内核可以通过defconfig文件中的CONFIG\_TZDRIVER选项控制tzdriver的编译使能。 - - 1. defconfig文件修改 - - defconfig文件在kernel/linux/config仓，每个芯片应当创建自己的defconfig文件，后面会介绍tzdriver中的所有defconfig配置项。 - - 2. kernel补丁 - - 其他内核相关修改在kernel/linux/patches仓，以补丁方式提供。 - - RK3568芯片的patch在kernel/linux/patches/linux-5.10/rk3568_patch/kernel.patch，其他芯片平台也可以参考这个patch，每个芯片应该创建自己的patch文件。此patch补丁中应当包含以下内容： - - - 对于内核的根Makefile的修改（在其中引用tzdriver仓的子Makefile，其中tzdriver path需要修改为实际的相对路径，注意Linux kernel的编译是会将kernel仓代码拷贝到out目录打patch，因此这个相对路径是相对于out下的临时kernel仓的路径）。 - - ``` - obj-y += {tzdriver path} - ``` - - - 对于内核的根Kconfig的需改（在其中引用tzdriver仓的子Kconfig，其中tzdriver path需要修改为实际的相对路径，同上需要注意这个相对路径应当是在out目录下的临时kernel仓路径）。 - - ``` - source "{tzdriver path}/Kconfig" - ``` - - - dtsi的修改：需要在相应芯片的disi文件中包含trusted\_core节点，对于RK3568芯片，需要修改patch中的/arch/arm64/boot/dts/rockchip/rk3568-toybrick-x0.dtsi文件，新增以下内容 - - ``` - /{ - trusted_core { - compatible = "trusted_core"; - interrupts = <0 73 4>; - }; - }; - ``` - 其中，Linux内核中tzdriver支持中断号的动态配置，上面的73为spi中断号 - >![](public_sys-resources/icon-caution.gif) **注意：** - >注意dtsi里面的spi中断号应该比实际的中断号小32，且需要保证不与其他组件的中断号冲突。 - - -#### 驱动初始化 - -- Linux内核中tzdriver驱动初始化方式 - - 自动初始化，无需适配修改。 - -### 配置选项 - -#### 内核配置选项 - -tzdriver有一些特性或者选项，可以选择配置，控制这些选项的地方如下： - -- Linux内核tzdriver配置选项 - - tzdriver选项应该写在kernel/linux/config仓，修改芯片的defconfig文件： - - ``` - # - # TEE OS - # - CONFIG_TZDRIVER=y - CONFIG_CPU_AFF_NR=1 - CONFIG_KERNEL_CLIENT=y - CONFIG_TEELOG=y - CONFIG_PAGES_MEM=y - CONFIG_THIRDPARTY_COMPATIBLE=y - - ``` - - 各选项其含义如下表所示： - - **表 1** 配置选项说明 - - - - - - - - - - - - - - - - - - - - - - - - - -

参数

-

说明

-

CONFIG_TZDRIVER

-

模块开关，使能tzdriver必须打开

-

CONFIG_CPU_AFF_NR

-

CA绑核功能，非零值代表限制仅cpuid小于CONFIG_CPU_AFF_NR的CPU可以进入TEE，0代表无限制，当前只支持在0核运行，所以值为1

-

CONFIG_KERNEL_CLIENT

-

内核CA支持，默认建议开启

-

CONFIG_TEELOG

-

TEE日志开关，默认建议开启

-

CONFIG_PAGES_MEM

-

tlogger使用的内存类型，开发者无需修改

-

CONFIG_THIRDPARTY_COMPATIBLE

-

兼容第三方opteed的适配，例如适配RK3568芯片需要开启此选项

-
- -### TEE Tzdriver编译命令 -tzdriver部件跟随kernel一起编译，编译命令如下 -```Bash -./build.sh --product-name rk3568 --ccache --build-target kernel --gn-args linux_kernel_version=\"linux-5.10\" -``` - -## TEE OS镜像的构建指导 - -以RK3568芯片为例，TEEOS的二进制文件（bl32.bin）被打包在uboot.img中，以下是构建TEEOS镜像的指导。 - -### 编译TEEOS - -TEEOS内核代码位置：`base/tee/tee_os_kernel` - -TEEOS框架代码位置：`base/tee/tee_os_framework` - -切换目录至OpenHarmony源码根目录, 输入以下指令编译TEEOS镜像 - -```Bash -./build.sh --product-name rk3568 --build-target tee --ccache -``` -构建产物为TEEOS镜像，路径如下：`base/tee/tee_os_kernel/kernel/bl32.bin` - -### 编译uboot.img -根据以下步骤编译uboot.img -- 克隆`https://github.com/rockchip-linux/rkbin`，其中包含bl31.elf -- 克隆`https://github.com/rockchip-linux/u-boot`，其中包含u-boot -- 将rkbin和u-boot放在同一目录下, 修改rkbin/RKTRUST/RK3568TRUST.ini中BL32_OPTION下的PATH指向bl32.bin -- 其中，u-boot/make.sh中有以下内容，搜索RK3568TRUST.ini中包含_bl32_的文件名，如果BL32的文件名是bl32.bin的话，需要修改下匹配规则 -```Bash -BL32_BIN=`sed -n '/_bl32_/s/PATH=//p' ${INI} | tr -d '\r'` -``` -- 修改u-boot/configs/rk3568_defconfig，关闭OPTEE驱动，增大镜像大小到6M。 -```Bash -- CONFIG_OPTEE_CLIENT=y -+ CONFIG_SPL_FIT_IMAGE_KB=6144 -+ CONFIG_SPL_FIT_IMAGE_MULTIPLE=1 -``` ->![](public_sys-resources/icon-caution.gif) **注意：** ->烧录的时候需要修改分区表parameter.txt，和uboot.img的镜像大小一致 -- 修改make.sh中编译工具链路径，使其指向正确的路径（可以使用openharmony工程prebuilts目录下的工具链） -```Bash --CROSS_COMPILE_ARM32=../prebuilts/gcc/linux-x86/arm/gcc-linaro-6.3.1-2017.05-x86_64_arm-linux-gnueabihf/bin/arm-linux-gnueabihf- --CROSS_COMPILE_ARM64=../prebuilts/gcc/linux-x86/aarch64/gcc-linaro-6.3.1-2017.05-x86_64_aarch64-linux-gnu/bin/aarch64-linux-gnu- -``` -- 在u-boot目录下执行./make.sh rk3568，最终会在u-boot目录中生成uboot.img \ No newline at end of file diff --git a/docs/opentrustee-guidelines/opentrustee-architecture-and-constraints.md b/docs/opentrustee-guidelines/opentrustee-architecture-and-constraints.md index 67a8917..75967b3 100644 --- a/docs/opentrustee-guidelines/opentrustee-architecture-and-constraints.md +++ b/docs/opentrustee-guidelines/opentrustee-architecture-and-constraints.md @@ -1,3 +1,4 @@ +# OpenTrustee系统架构和约束 ## 系统架构 OpenTrustee是一套完整的TEE解决方案，包含多个部件，系统架构如同所示： @@ -6,41 +7,46 @@ OpenTrustee是一套完整的TEE解决方案，包含多个部件，系统架构 各部件基本功能介绍如下： -**TEE Client** +#### TEE Client - 部署在REE侧用户态，为CA提供符合GP TEE标准的TEE Client API； - 内置TEE的代理服务：如日志代理服务，支持获取TEE侧日志并落盘到REE侧文件系统；如安全存储服务，支持获取TEE侧加密的数据并落盘到REE侧文件系统。 -**Tzdriver** +#### Tzdriver - 部署在REE侧内核中的驱动，支持REE和TEE进行通信。 -**OpenTrustee 操作系统框架** +#### OpenTrustee 操作系统框架 - 为TA提供符合GP TEE标准的TEE Internal API； - 提供TA运行管理、驱动运行管理等框架基础服务； - 提供安全存储、加解密等安全能力。 -**OpenTrustee 操作系统内核** +#### OpenTrustee 操作系统内核 - ChCore微内核，提供IPC/进程管理/内存管理/调度/中断管理/REE和TEE切换等基础内核功能。 -**OpenTrustee 开发套件** +#### OpenTrustee 开发套件 - 包括TA开发套件和驱动开发套件两部分，提供API头文件、编译框架、签名脚本、demo样例等，支持高效开发TA和驱动。 -**OpenTrustee Dispatcher** +#### OpenTrustee Dispatcher - 部署在ATF中，在REE和TEE之间交互时完成两个世界上下文的切换。 -## 贡献 +## 约束 +- 开发语言：c； +- 支持的系统类型：目前仅支持标准系统； +- 对硬件的要求：CPU需要支持trustzone机制，安全内存至少需要28M； -[如何贡献](https://gitee.com/openharmony/docs/blob/HEAD/zh-cn/contribute/%E5%8F%82%E4%B8%8E%E8%B4%A1%E7%8C%AE.md) - -### 编码规范 +## 编码规范 [OpenHarmony C&C++ 安全编程指南](https://gitee.com/openharmony/docs/blob/master/zh-cn/contribute/OpenHarmony-c-cpp-secure-coding-guide.md) -### license +## license -遵循Mulan PSL V2协议； \ No newline at end of file +遵循Mulan PSL V2协议; + +## 贡献 + +[如何贡献](https://gitee.com/openharmony/docs/blob/HEAD/zh-cn/contribute/%E5%8F%82%E4%B8%8E%E8%B4%A1%E7%8C%AE.md) \ No newline at end of file diff --git a/docs/opentrustee-guidelines/opentrustee-compatibility-test-suite-introduction.md b/docs/opentrustee-guidelines/opentrustee-compatibility-test-suite-introduction.md new file mode 100644 index 0000000..df95f88 --- /dev/null +++ b/docs/opentrustee-guidelines/opentrustee-compatibility-test-suite-introduction.md @@ -0,0 +1,21 @@ +## OpenTrustee的验证测试套件说明 +OpenTrustee提供了acts兼容性测试套件，CA的具体目录在`test/xts/acts/tee`下，TA以签名后的二进制存放在`https://gitee.com/openharmony-sig/compatibility/tree/master/test_suite/resource/tee`资源目录下。 +| 测试CA | 测试TA | 说明 | +| ------------ | ------------------------------------------------------------ | --- | +| tee_test_client_api | 534d4152-542d-4353-b919-d3016a171fc5.sec | CA与TA通信API | + +使用指导如下： +- 进入openharmony根目录，在test/xts/acts目录下执行编译命令，编译CA测试用例。 + +```Bash +./build.sh product_name=rk3568 system_size=standard target_subsystem=tee +``` + +- 参考`https://www.openharmony.cn/certification/document/guid`中的《标准系统应用兼容性测试指导》章节，在Windows工作台上搭建运行环境 +- 从 `https://gitee.com/openharmony-sig/compatibility` 下载资源文件，将`test_suite/resource/master/standard system/acts`目录下的文件拷贝到`acts/resource`目录下 +- 进入acts目录，直接执行run.bat，然后在命令框里输入以下命令运行用例 + +```Bash +run -l tee_test_client_api +``` +- 用例运行过程中，可以使用tlogcat查看TEE侧日志，用例执行的报告和log会在acts/report目录生成 \ No newline at end of file diff --git a/docs/opentrustee-guidelines/opentrustee-enable-new-platform-adaptation-guidelines.md b/docs/opentrustee-guidelines/opentrustee-enable-new-platform-adaptation-guidelines.md index dfafc94..bf4a2bc 100644 --- a/docs/opentrustee-guidelines/opentrustee-enable-new-platform-adaptation-guidelines.md +++ b/docs/opentrustee-guidelines/opentrustee-enable-new-platform-adaptation-guidelines.md @@ -1,218 +1,243 @@ -# 使能新平台的指南 -## TEE 安全镜像Loader适配指导 +# OpenTrustee 使能新平台的指南 +本章节介绍如何针对一款芯片适配OpenTrustee，包含TEE CLient、TEE Tzdriver、TEE Loader、TEE ATF的适配。 +## Tee Client的适配 -### 概述 +### Tee Client使能实例 -#### 功能简介 +适配TEE Client，在相应配置json文件中增加tee_client部件即可。 -TEE Loader主要负责加载安全镜像并将启动参数传递给TEE OS的功能。 +以RK3568芯片为例，在vendor/hihope/rk3568/config.json中增加以下内容： -#### 约束与限制 - -- 芯片架构为ARMv7/ARMv8架构。 -- CPU需支持安全内存和非安全内存的划分，安全和非安全外设的划分。 - -### 开发指导 - -#### 场景介绍 - -由于安全镜像在flash中是以加密形式存储的，因此需要对镜像进行解密处理，随后拷贝到目标执行地址。在TEE OS启动时，需要对其传递启动参数。以上这些都是在Loader中进行的。因此在芯片使能TEE时，需要对Loader进行开发适配。 - -#### 接口说明 - -以下接口说明列表将介绍我们在实际使能TEE过程中对Loader适配将用到的接口。包括： - -- 启动参数配置 -- 镜像加载 - -**表 1** 启动参数配置调用接口表 - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -

接口名

-

描述

-

必选/可选

-

void set_teeos_mem(uintptr_t teeos_base_addr, uint64_t size)

-

设置TEE OS的起始地址size大小。

-

必选，OS需要。

-

void set_teeos_uart(uint64_t uart_addr)

-

设置串口地址。

-

可选，建议配置，启动调试用。

-

void set_gic(struct gic_config_t gic_config)

-

配置gic寄存器。结构体定义见。

-

必选，OS需要。

-

bool copy_extend_datas(void * extend_datas, uint64_t extend_length)

-

保留字段拷贝。

-

可选，根据实际情况。

-

bool copy_teeos_cfg(void)

-

拷贝启动参数到目标位置，配置TEE OS属性后再调用此接口。

-

必选，OS需要。

-
- - -**表 2** 镜像加载调用接口表 - - - - - - - - - - - - - - - - - - - - - - -

接口名

-

描述

-

uintptr_t read_teeos(const char *part_name, uint32_t part_size)

-

将TEE OS从flash分区读镜像到RAM中。

-

int32_t verify_teeos(uintptr_t buf_addr)

-

TEE OS镜像验签。

-

int32_t decrypt_teeos(uintptr_t buf_addr)

-

TEE OS镜像解密。

-

int32_t copy_teeos(uintptr_t buf_addr)

-

TEE OS镜像拷贝到目标执行地址。

-

uint64_t get_teeos_start(void)

-

获取TEE OS启动地址。

-
- - -#### 接口参数结构体定义 - -``` -struct gic_config_t { - char version; - union { - struct v2_t { - p_region_t dist; - p_region_t contr; - } v2; - struct v3_t { - p_region_t dist; - uint32_t redist_num; - uint32_t redist_stride; - p_region_t redist[GICR_MAX_NUM]; - } v3; - }; -}; +```c +{ + "subsystem": "tee", + "components": [ + { + "component": "tee_client", + "features": [] + } + ] +} ``` -#### 开发步骤 +### Tee Client编译命令 -1. 启动参数配置 +Tee Client代码位置：`base/tee/tee_client` - 启动参数包含TEE OS用到的安全内存地址和大小，串口的地址，gic寄存器配置，其它拓展参数。 +本模块支持单独编译，以RK3568芯片为例，运行以下命令编译TEE Client部件，产物路径：out/rk3568/tee/tee_client - loader中启动参数的适配方法可以按照产品的习惯要求采用不同的方法，例如结构体中直接填写相应的参数，或者增加配置文件的方法。 +```shell +./build.sh --product-name rk3568 --ccache --build-target tee_client +``` - **表 3** 启动参数列表 +单独编译的产物需要自行推入设备中。 +```shell +hdc file send cadaemon.json /system/profile/ +hdc file send cadaemon.cfg /system/etc/init/ +hdc file send libteec.z.so /system/lib/ +hdc file send libcadaemon.z.so /system/lib/ +hdc file send tlogcat /system/bin/ +``` - -

参数

+## Tzdriver的适配和构建 + +tzdriver是TEE的内核驱动，主要功能是在整个TEE子系统中起连接作用，是使用TEE OS服务的桥梁，tzdriver处理来自于tee\_client的ioctl命令，并通过smc指令从REE切换到TEE。 + +### 适配指导以及适配实例 + +本章节中会讲述如何针对一款芯片适配tzdriver，此章节中以RK3568芯片为例。 + +Linux内核tzdriver代码位置：base/tee/tee\_tee\_tzdriver/linux。 + +tzdriver是内核中的一个字符设备驱动。tzdriver初始化时会创建一个字符设备文件，一般为/dev/tc\_ns\_client，用户态进程可以打开此节点，以及通过ioctl接口调用tzdriver相关功能。 + +#### 工程编译适配 + +tzdriver需要被编译到内核中作为内核驱动。 + +- Linux内核tzdriver编译适配 + + 在Linux内核可以通过defconfig文件中的CONFIG\_TZDRIVER选项控制tzdriver的编译使能。 + + 1. defconfig文件修改 + + defconfig文件在kernel/linux/config仓，每个芯片应当创建自己的defconfig文件，后面会介绍tzdriver中的所有defconfig配置项。 + + 2. kernel补丁 + + 其他内核相关修改在kernel/linux/patches仓，以补丁方式提供。 + + RK3568芯片的patch在kernel/linux/patches/linux-5.10/rk3568_patch/kernel.patch，其他芯片平台也可以参考这个patch，每个芯片应该创建自己的patch文件。此patch补丁中应当包含以下内容： + + - 对于内核的根Makefile的修改（在其中引用tzdriver仓的子Makefile，其中tzdriver path需要修改为实际的相对路径，注意Linux kernel的编译是会将kernel仓代码拷贝到out目录打patch，因此这个相对路径是相对于out下的临时kernel仓的路径）。 + + ``` + obj-y += {tzdriver path} + ``` + + - 对于内核的根Kconfig的需改（在其中引用tzdriver仓的子Kconfig，其中tzdriver path需要修改为实际的相对路径，同上需要注意这个相对路径应当是在out目录下的临时kernel仓路径）。 + + ``` + source "{tzdriver path}/Kconfig" + ``` + + - dtsi的修改：需要在相应芯片的disi文件中包含trusted\_core节点，对于RK3568芯片，需要修改patch中的/arch/arm64/boot/dts/rockchip/rk3568-toybrick-x0.dtsi文件，新增以下内容 + + ``` + /{ + trusted_core { + compatible = "trusted_core"; + interrupts = <0 73 4>; + }; + }; + ``` + 其中，Linux内核中tzdriver支持中断号的动态配置，上面的73为spi中断号 + >![](public_sys-resources/icon-caution.gif) **注意：** + >注意dtsi里面的spi中断号应该比实际的中断号小32，且需要保证不与其他组件的中断号冲突。 + + +#### 驱动初始化 + +- Linux内核中tzdriver驱动初始化方式 + + 自动初始化，无需适配修改。 + +#### 配置选项 + +tzdriver有一些特性或者选项，可以选择配置，控制这些选项的地方如下： + +- Linux内核tzdriver配置选项 + + tzdriver选项应该写在kernel/linux/config仓，修改芯片的defconfig文件： + + ``` + # + # TEE OS + # + CONFIG_TZDRIVER=y + CONFIG_CPU_AFF_NR=1 + CONFIG_KERNEL_CLIENT=y + CONFIG_TEELOG=y + CONFIG_PAGES_MEM=y + CONFIG_THIRDPARTY_COMPATIBLE=y + + ``` + + 各选项其含义如下表所示： + + **表 1** 配置选项说明 + + + - - - - - - - - - - - - - - - - - - - - +

参数

含义

-

备注

+

说明

plat_cfg_size

+

CONFIG_TZDRIVER

启动参数大小，包含extend_paras部分

-

整个启动参数的buffer大小，值为sizeof（struct platform_info） + extend _length。

+

模块开关，使能tzdriver必须打开

phys_region_size

+

CONFIG_CPU_AFF_NR

TEE OS内存大小

-

2MB的整数倍。

+

CA绑核功能，非零值代表限制仅cpuid小于CONFIG_CPU_AFF_NR的CPU可以进入TEE，0代表无限制，当前只支持在0核运行，所以值为1

phys_region_start

+

CONFIG_KERNEL_CLIENT

TEE OS内存起始物理地址

-

2MB的整数倍。

+

内核CA支持，默认建议开启

uart_addr

+

CONFIG_TEELOG

串口寄存器的基地址

-

-

+

TEE日志开关，默认建议开启

struct gic_config_t

+

CONFIG_PAGES_MEM

gic寄存器参数

-

-

+

tlogger使用的内存类型，默认需要开启

extend_datas

-

其它参数

-

格式需要和TEE OS核对。

+

CONFIG_THIRDPARTY_COMPATIBLE

兼容第三方opteed的适配，例如适配RK3568芯片需要开启此选项

+
- -2. 镜像加载 - tee loader适配在芯片平台的bios或者fastboot、preloader中，主要完成的功能有配置并传递TEE OS的启动参数、将TEE OS镜像加载到目标内存位置、传递共享内存信息给TEE OS。loader中启动参数的适配方法可以按照产品的习惯和要求采用不同的方法，例如结构体中直接填写相应的参数，或者增加配置文件。以下为镜像加载步骤： +### TEE Tzdriver编译命令 +tzdriver部件跟随kernel一起编译，以rk3568为例，可以重编boot_linux.img，编译命令如下 +```Bash +./build.sh --product-name rk3568 --ccache --build-target kernel --gn-args linux_kernel_version=\"linux-5.10\" +``` - 1. 从flash分区读镜像到RAM中。 - 2. TEE OS镜像验签。 - 3. TEE OS镜像解密。 - 4. TEE OS镜像拷贝到目标执行地址。 - 5. TEE OS启动地址传递。获取TEE OS的启动地址，一般情况下需要将这个值传给atf, 作为ATF初始化TEE OS的入口地址。 +## TEE 的适配指导 +芯片使能TEE时，需要对Loader和ATF进行适配。 -相关配置接口见[接口说明](#section125843344514)。 +### TEE Loader的适配 +TEE Loader主要负责加载安全镜像并将启动参数传递给TEE OS的功能。启动参数包含TEE OS用到的安全内存地址和大小，串口的地址，gic寄存器配置，以及其它拓展参数。 + +**表 2** 启动参数列表 + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +

参数

+

含义

+

备注

+

plat_cfg_size

+

启动参数大小，包含extend_paras部分

+

整个启动参数的buffer大小，值为sizeof（struct platform_info） + extend _length。

+

phys_region_size

+

TEE OS内存大小

+

2MB的整数倍。

+

phys_region_start

+

TEE OS内存起始物理地址

+

2MB的整数倍。

+

uart_addr

+

串口寄存器的基地址

+

-

+

struct gic_config_t

+

gic寄存器参数

+

-

+

extend_datas

+

其它参数

+

格式需要和TEE OS核对。

+
#### 开发实例 -- 使用 TEE Loader，在芯片使能TEE时，配置启动参数的开发实例。详细示例代码位于 `base/tee/tee_os_framework/sample/teeloader` 目录。 +- 下面展示了在芯片使能TEE时，使用 TEE Loader配置启动参数的开发实例。详细示例代码位于 `base/tee/tee_os_framework/sample/teeloader` 目录。 ```C #define TEEOS_TEXT_OFFSET (0x8000) @@ -306,37 +331,24 @@ uint64_t get_teeos_size(void) } ``` -- 不使用 TEE Loader（如 ATF 闭源等原因），需要在 TEE OS 中配置平台相关参数，以 RK3568 平台为例（详见 `base/tee/tee_os_kernel/kernel/arch/aarch64/plat/rk3568/machine.c`）。 - -- 若需要使能新平台，需要在 `base/tee/tee_os_kernel/kernel/arch/aarch64/plat` 目录下添加新平台的适配代码，并且在 `base/tee/tee_os_kernel/config.mk` 中更新 CHCORE_PLAT 配置 +- 第二步，需要在 `base/tee/tee_os_kernel/kernel/arch/aarch64/plat` 目录下添加新平台的适配代码，可以参考`plat/rk3399`里的适配。同时，需要在 `base/tee/tee_os_kernel/config.mk` 中更新 CHCORE_PLAT 配置 ```makefile CHCORE_PLAT=new_plat ``` +>![](public_sys-resources/icon-caution.gif) **注意：** +启动参数的适配方法可以按照产品的习惯要求采用不同的方法，例如结构体中直接填写相应的参数，或者增加配置文件的方法。启动参数也可以直接配置在TEE OS 中，以 RK3568 平台为例（详见 `base/tee/tee_os_kernel/kernel/arch/aarch64/plat/rk3568/machine.c`）。 +### TEE ATF适配指导 -## TEE ATF适配指导 +- ARM从v6架构开始就引入了TrustZone技术，将AMR核的工作状态分为安全态和非安全态两种，在芯片级别对硬件资源提供保护和隔离。在实现了BL32（即安全OS）的平台，需要在ATF中添加SPD模块来实现安全世界和非安全世界的切换，对于teeos，我们提供了teed模块，位于 `base/tee/tee_os_framework/sample/teed`。**按照ATF的编译框架，在ATF根目录下的Makefile里面添加如下选项可以使能teed**。 +```makefile + SPD := teed +``` +- 同时，TEE OS 需要适配 ATF 中的 teed，适配代码位于`base/tee/tee_os_kernel/kernel/arch/aarch64/trustzone/spd/teed`目录中，此代码开发者适配新平台时无需修改。 +- 另外，SMC在TEEOS中负责CA和TA的交互、ATF和TEE的交互，TEE OS的适配需要关注SMC通信参数。下表进行了具体介绍。 -### 概述 - -#### 功能简介 - -ATF提供了安全世界的参考实现软件\[ARMv8-A\],包括执行的\[Secure Monitor\] \[TEE-SMC\]异常级别 3\(EL3\)。它实现了各种 ARM 接口标准,如电源状态协调接口\(\[PSCI\]\),可信板启动要求\(TBBR,ARM DEN0006C-1\)和\[SMC 呼叫公约\] \[SMCCC\]。 - -#### 约束与限制 - -- 芯片架构为ARMv7/ARMv8架构。 -- CPU需支持安全内存和非安全内存的划分，安全和非安全外设的划分。 - -### 开发指导 - -#### 场景介绍 - -芯片使能TEE时，需要对ATF进行适配，以下将相关内容做介绍。 - -#### 接口说明 - -**表 4** teed smc id管理列表 +**表 3** teed smc id管理列表 @@ -420,12 +432,51 @@ ATF提供了安全世界的参考实现软件\[ARMv8-A\],包括执行的\[Secure
-#### 开发实例 - -- 在芯片使能TEE ATF时，需要修改teed，适配示例代码位于 `base/tee/tee_os_framework/sample/teed` -- TEE OS 需要适配 ATF 中的 TEED，目前 TEE OS 支持 teed 和 opteed 两种，分别位于 `base/tee/tee_os_kernel/kernel/arch/aarch64/trustzone/spd` 下的 teed 和 opteed 两个目录中。 -- 若需要使能新的 TEED，需要在该目录下添加相应 TEED 的适配代码，并且在 `base/tee/tee_os_kernel/tee_tee_os_kernel/config.mk` 中更新 CHCORE_SPD 配置 +#### 兼容opteed +对于无法修改ATF的单板，TEE OS提供了兼容opteed的方案，具体适配代码位于 `base/tee/tee_os_kernel/kernel/arch/aarch64/trustzone/spd/opteed` 目录中。 +另外，若需要使能新的 TEED，可以在`spd`目录下添加相应 TEED 的适配代码，并且在 `base/tee/tee_os_kernel/config.mk` 中更新 CHCORE_SPD 配置. ```makefile CHCORE_SPD=new_teed - ``` \ No newline at end of file + ``` + +## TEE OS镜像的构建指导 + +以RK3568芯片为例，TEEOS的二进制文件（bl32.bin）被打包在uboot.img中，以下是构建TEEOS镜像的指导。 + +### 编译TEEOS + +TEEOS内核代码位置：`base/tee/tee_os_kernel` + +TEEOS框架代码位置：`base/tee/tee_os_framework` + +切换目录至OpenHarmony源码根目录, 输入以下指令编译TEEOS镜像 + +```Bash +./build.sh --product-name rk3568 --build-target tee --ccache +``` +构建产物为TEEOS镜像，路径如下：`base/tee/tee_os_kernel/kernel/bl32.bin` + +### 编译uboot.img +根据以下步骤编译uboot.img +- 克隆`https://github.com/rockchip-linux/rkbin`，其中包含bl31.elf +- 克隆`https://github.com/rockchip-linux/u-boot`，其中包含u-boot +- 将rkbin和u-boot放在同一目录下, 修改rkbin/RKTRUST/RK3568TRUST.ini中BL32_OPTION下的PATH指向bl32.bin +- 其中，u-boot/make.sh中有以下内容，搜索RK3568TRUST.ini中包含_bl32_的文件名，如果BL32的文件名是bl32.bin的话，需要修改以下匹配规则 +```Bash +BL32_BIN=`sed -n '/_bl32_/s/PATH=//p' ${INI} | tr -d '\r'` +``` +- 修改u-boot/configs/rk3568_defconfig，关闭OPTEE驱动，增大镜像大小到6M。 +```Bash +- CONFIG_OPTEE_CLIENT=y ++ CONFIG_SPL_FIT_IMAGE_KB=6144 ++ CONFIG_SPL_FIT_IMAGE_MULTIPLE=1 +``` +>![](public_sys-resources/icon-caution.gif) **注意：** +>烧录的时候需要修改分区表parameter.txt，和uboot.img的镜像大小一致 +- 修改make.sh中编译工具链路径，使其指向正确的路径（可以使用openharmony工程prebuilts目录下的工具链） +```Bash +-CROSS_COMPILE_ARM32=../prebuilts/gcc/linux-x86/arm/gcc-linaro-6.3.1-2017.05-x86_64_arm-linux-gnueabihf/bin/arm-linux-gnueabihf- +-CROSS_COMPILE_ARM64=../prebuilts/gcc/linux-x86/aarch64/gcc-linaro-6.3.1-2017.05-x86_64_aarch64-linux-gnu/bin/aarch64-linux-gnu- +``` +- 在u-boot目录下执行./make.sh rk3568，最终会在u-boot目录中生成uboot.img \ No newline at end of file diff --git a/docs/opentrustee-guidelines/overview-of-opentrustee.md b/docs/opentrustee-guidelines/overview-of-opentrustee.md index 4194894..9a6c218 100644 --- a/docs/opentrustee-guidelines/overview-of-opentrustee.md +++ b/docs/opentrustee-guidelines/overview-of-opentrustee.md @@ -6,8 +6,6 @@ OpenTrustee是一个部署在可信执行环境（TEE）中的安全操作系统 OpenTrustee支持安全计算、安全存储、安全密钥、安全外设、安全时钟等安全能力。 -备注：应该展开介绍，是否放到单独章节 - ## **应用场景** 在终端设备越来越智能化的今天，人们正在把越来越多的个人应用和数据放到设备上，安全性成为一个很重要的命题。可信执行环境（TEE）已逐渐成为终端设备必备的安全技术。OpenTrustee具备丰富的安全特性，可以支持开发者灵活部署安全应用，应用场景也非常广泛，例如：移动支付、生物认证、版权保护等，也可以为系统安全提供保护，如安全启动、系统完整性检测等。