README.md
1# TEE Client
2
3## Introduction
4
5TEE Client provides an API interface for accessing TEE to the OpenHarmony side CA (Client Application), and also includes TEE's proxy services to work with TEE to achieve secure storage, log printing, and other functions.
6
7TEE Client includes the following modules:
8
9- libteec.so: Provide the TEE Client API for native applications of HAP applications or system components.
10- libteec_vendor.so: Provide TEE Client API for Native applications of chip components.
11- cadaemon: Forward CA requests and authenticate the CA.
12- teecd: As a proxy service for TEE, it supports TEE's implementation of secure storage and other functions. Simultaneously teecd supports identity recognition for CA.
13- tlogcat: Support printing TEE logs.
14
15Figure 1: Architecture diagram of TEE Client
16
17
18
19## Directory
20
21```
22base/tee/tee_client
23├── frameworks
24│ └── libteec_vendor # libteec_vendor.so library, providing TEE Client API.
25├── interfaces
26│ ├── inner_api # Internal interfaces of this component
27| └── kits # The libteec.so library and corresponding TEE Client API published to SDK
28└── services
29 ├── authentication # CA identity recognition（Reserved function, not yet enabled）
30 ├── cadaemon # Forward CA request
31 ├── teecd # TEE proxy services
32 └── tlogcat # TEE log service
33```
34
35## Interface Description
36
37The list of APIs provided by the TEE Client to CA is as follows：
38
39| Name | Description |
40| ------------------------------------------------------------ | -------------------- |
41| TEEC_InitializeContext (const char *name, TEEC_Context *context) | Initialize TEE context. |
42| TEEC_FinalizeContext (TEEC_Context *context) | End TEE context. |
43| TEEC_OpenSession (TEEC_Context *context, TEEC_Session *session, const TEEC_UUID *destination, uint32_t connectionMethod, const void *connectionData, TEEC_Operation *operation, uint32_t *returnOrigin) | Establish a conversation with TEE. |
44| TEEC_CloseSession (TEEC_Session *session) | Close the session with TEE. |
45| TEEC_InvokeCommand (TEEC_Session *session, uint32_t commandID, TEEC_Operation *operation, uint32_t *returnOrigin) | Send commands to TEE. |
46| TEEC_RegisterSharedMemory (TEEC_Context *context, TEEC_SharedMemory *sharedMem) | Register for shared memory. |
47| TEEC_AllocateSharedMemory (TEEC_Context *context, TEEC_SharedMemory *sharedMem) | Apply for shared memory. |
48| TEEC_ReleaseSharedMemory (TEEC_SharedMemory *sharedMem) | Release shared memory. |
49| TEEC_RequestCancellation (TEEC_Operation *operation) | Cancel the running operation. |
50
51The above APIs are all specified by the GlobalPlatform TEE standard, which can be referred to in the "[TEE Client API Specification v1.0 (GPD_SPE_007)](https://globalplatform.org/specs-library/?filter-committee=tee)". There are differences between a small number of implementations and the GlobalPlatform TEE specification, and the differences are as follows:
52
531. The TEEC_Context structure member ta_path of the TEEC_OpenSession interface supports specifying the file path of TA (limited to the /data directory).
54
55 Give an example：
56
57 ```
58 TEEC_Context context;
59 context.ta_path = (uint8_t *)"/data/58dbb3b9-4a0c-42d2-a84d-7c7ab17539fc.sec"
60 ```
61
62 If CA doesn't use ta_path to specify the file path of TA, TEE Client will read the TA file named uuid.sec (uuid needs to be replaced with TA's real uuid) from the default path. There are two default paths: "/system/bin" and "/vendor/bin".
63
642. The input parameter connectionMethod of the TEEC_OpenSession interface only supports TEEC_LOGIN_IDENTIFY.
65
66 For the fourth input parameter connectionMethod in the TEEC-OpenSession function, the GP specification defines six Login Methods, and TEE Client extends the type of TEEC_LOGIN_IDENTIFY and only supports this type of connectionMethod.
67
683. When calling TEEC_OpenSession, its parameters are limited.
69
70 When calling the TEEC_OpenSession interface, the params[2] and params[3] in TEEC_Operation are reserved for the system and are not allowed for use by CA. CA can only use params[0] and [1].
71
72## Guidelines for Compilation
73
74The TEE Client component supports separate compilation and debugging. Taking the RK3568 chip as an example, run the following command to compile the TEE Client component：
75
76```
77./build.sh --product-name rk3568 --ccache --build-target tee_client
78```
79
80The path to the compiled product：out/rk3568/tee/tee_client
81
82Compilation products can be pushed into the device for debugging：
83
84```
85hdc file send cadaemon.json /system/profile/
86hdc file send cadaemon.cfg /system/etc/init/
87hdc file send libteec.so /system/lib/
88hdc file send libcadaemon.so /system/lib/
89hdc file send tlogcat /system/bin/
90hdc file send libteec_vendor.so /vendor/lib/
91hdc file send teecd /vendor/bin/
92```
93
94## Related code repository
95
96[tee_tzdriver](https://gitee.com/openharmony-sig/tee_tee_tzdriver)
97
README_zh.md
1# TEE Client组件
2
3## 简介
4
5TEE Client组件向OpenHarmony侧CA（Client APP，即客户端应用）提供访问TEE的API接口，同时也包含TEE的代理服务，配合TEE实现安全存储、日志打印等功能。
6
7TEE Client组件包含如下模块：
8
9- libteec.so：为系统组件Native应用提供TEE Client API。
10- libteec_vendor.so：为芯片组件Native应用提供TEE Client API。
11- cadaemon：转发CA请求到Tzdriver驱动。
12- teecd：作为TEE的代理服务，支持TEE实现安全存储等功能。
13- tlogcat：支持打印TEE日志。
14
15图1 TEE Client组件架构图
16
17
18
19## 目录
20
21```
22base/tee/tee_client
23├── frameworks
24│ └── libteec_vendor # libteec_vendor.so库，提供TEE Client API
25├── interfaces
26│ ├── inner_api # 本组件内部接口
27| └── kits # 发布到SDK中的libteec.so库和对应的TEE Client API
28└── services
29 ├── authentication # CA身份识别（预留功能，暂未使能）
30 ├── cadaemon # 转发CA请求
31 ├── teecd # TEE代理服务
32 └── tlogcat # TEE日志服务
33```
34
35## 接口说明
36
37TEE Client组件对CA提供的API列表如下：
38
39| 名称 | 描述 |
40| ------------------------------------------------------------ | -------------------- |
41| TEEC_InitializeContext (const char *name, TEEC_Context *context) | 初始化TEE上下文。 |
42| TEEC_FinalizeContext (TEEC_Context *context) | 结束TEE上下文。 |
43| TEEC_OpenSession (TEEC_Context *context, TEEC_Session *session, const TEEC_UUID *destination, uint32_t connectionMethod, const void *connectionData, TEEC_Operation *operation, uint32_t *returnOrigin) | 建立与TEE的会话。 |
44| TEEC_CloseSession (TEEC_Session *session) | 关闭与TEE的会话。 |
45| TEEC_InvokeCommand (TEEC_Session *session, uint32_t commandID, TEEC_Operation *operation, uint32_t *returnOrigin) | 向TEE发送命令。 |
46| TEEC_RegisterSharedMemory (TEEC_Context *context, TEEC_SharedMemory *sharedMem) | 注册共享内存。 |
47| TEEC_AllocateSharedMemory (TEEC_Context *context, TEEC_SharedMemory *sharedMem) | 申请共享内存。 |
48| TEEC_ReleaseSharedMemory (TEEC_SharedMemory *sharedMem) | 释放共享内存。 |
49| TEEC_RequestCancellation (TEEC_Operation *operation) | 取消正在运行的操作。 |
50
51上述API均是GlobalPlatform TEE标准规定的，可参考《[TEE Client API Specification v1.0 (GPD_SPE_007)](https://globalplatform.org/specs-library/?filter-committee=tee)》。少量实现与GlobalPlatform TEE规范有差异，差异点如下：
52
531. TEEC_OpenSession接口的TEEC_Context结构体成员 ta_path支持指定TA的文件路径（限制在/data目录）。
54
55 举例如下：
56
57 ```
58 TEEC_Context context;
59 context.ta_path = (uint8_t *)"/data/58dbb3b9-4a0c-42d2-a84d-7c7ab17539fc.sec"
60 ```
61
62 如果CA不通过ta_path指定TA的文件路径，则TEE Client会从缺省路径下读取uuid.sec（uuid需要替换为TA的真实uuid）命名的TA文件。缺省路径有两个：/system/bin和/vendor/bin。
63
642. TEEC_OpenSession接口入参connectionMethod只支持TEEC_LOGIN_IDENTIFY。
65
66 对于TEEC_OpenSession函数中第四个入参connectionMethod，GP规范定义了六种Login Method，TEE Client组件拓展了TEEC_LOGIN_IDENTIFY的类型，且只支持该种connectionMethod。
67
683. 调用TEEC_OpenSession时，TEEC_Operation参数有限制。
69
70 在调用TEEC_OpenSession接口时，TEEC_Operation中params[2]和params[3]是预留给系统的，不允许CA使用，CA仅可以使用params[0]和params[1]。
71
72## 编译指导
73
74TEE Client组件支持单独编译调试，以RK3568芯片为例，运行以下命令编译TEE Client组件：
75
76```
77./build.sh --product-name rk3568 --ccache --build-target tee_client
78```
79
80编译产物路径：out/rk3568/tee/tee_client
81
82可将编译产物自行推入设备中进行调试：
83
84```
85hdc file send cadaemon.json /system/profile/
86hdc file send cadaemon.cfg /system/etc/init/
87hdc file send libteec.so /system/lib/
88hdc file send libcadaemon.so /system/lib/
89hdc file send tlogcat /system/bin/
90hdc file send libteec_vendor.so /vendor/lib/
91hdc file send teecd /vendor/bin/
92```
93
94## 相关仓
95
96[tee_tzdriver](https://gitee.com/openharmony-sig/tee_tee_tzdriver)
97
