README_zh.md
1# TA编译指导手册<a name="ZH-CN_TOPIC_0000001078026808"></a>
2
3## TA编译与签名指导说明
4### 目录文件介绍
5```
6teekit
7├── cmake # TA cmake编译框架
8├── config # TA签名使用的配置文件(包括TA配置信息、TA签名公钥配置文件、TA签名私钥配置文件)
9├── ld # 生成TA ELF文件的链接脚本
10├── mk # TA make编译框架
11├── script # TA签名和证书签名相关脚本
12├── tools # CA信息hash值计算工具
13├── TA_demo # TA源码编译文件夹
14 ├── build_ta.sh # TA编译构建脚本
15 ├── configs.xml # TA 配置信息文本文件
16 ├── CMakeLists.txt # TA CMake编译框架配置文件
17 ├── Makefile # TA Make编译框架配置文件
18 └── defconfig # TA编译配置选项，包括编译器、编译工具链、TA编译版本、签名版本选择
19```
20
21### defconfig文件介绍<a name="section21267445213"></a>
22
23defconfig文件为编译配置文件，该文件中可以指定使用的编译器、编译工具链、指定编译32位或64位。
24
25- CONFIG\_BUILD\_TOOL为指定编译器，其值为make代表使用make编译，其值为cmake代表使用cmake编译。
26
27- CONFIG\_GCC为指定编译工具链，其值为y代表使用GCC编译，其值为n代表使用LLVM编译。
28
29- TARGET\_IS\_ARM64为指定编译版本，其值为y时编译64位驱动，为其值为n时编译32位驱动。
30
31- SIGNATURE\_VER为指定签名版本，其值为V3时TA的签名版本为V3，为其值为V3_1时TA的签名版本为V3.1。
32
33defconfig文件举例如下：
34
35```
36#set CONFIG_BUILD_TOOL (cmake / make)
37CONFIG_BUILD_TOOL=make
38
39#set CONFIG_GCC (y / n)
40CONFIG_GCC=n
41
42#set TARGET_IS_ARM64 (y / n)
43TARGET_IS_ARM64=y
44
45#set SIGNATURE_VER (V3 / V3_1 )
46SIGNATURE_VER=V3
47```
48
49### API_LEVEL配置
50API_LEVEL编译选项表示TA的GP API版本，其中当API_LEVEL=2时表示GP 1.1.1，API_LEVEL=3时表示GP 1.2。<br>
51CMake编译框架适配CMakeLists.txt文件：<br>
52```
53# API_LEVEL which indicates the GP API version of TA
54# API_LEVEL=2 indicates GP 1.1.1 which is the current version of the partner
55# API_LEVEL=3 indicates GP 1.2 which is the version we both going to support
56# If no API_LEVEL is specified, API of GP 1.1.1 will be taken
57# TEE flags
58set(COMMON_CFLAGS -DAPI_LEVEL=2)
59```
60
61Make编译框架适配MakeFile文件：
62```
63CFLAGS += -DAPI_LEVEL=2
64```
65
66### MakeFile文件
67MakeFile文件参考teekit/TA_demo目录下示例内容。如下所示，表示将源文件放置于TA_demo路径下，编译生成目标文件libcombine.so
68```
69CFLAGS += -DAPI_LEVEL=2
70
71include ${TEE_OH_BUILD_PATH}/mk/common.mk
72
73SRC += $(wildcard ./*.c)
74
75# set header directory
76INCLUDEDIR += -I./include
77
78# set target
79COBJS := $(SRC:%.c=%.o)
80TARGET = $(COBJS)
81
82libcombine: $(TARGET)
83 $(LD) $(LDFLAGS) $(TARGET) $(EXTRAO) -o libcombine.so
84
85src/%.o: ./src/%.c
86 $(CC) $(CFLAGS) $(INCLUDEDIR) -c $< -o $@
87
88%.o: %.c
89 $(CC) $(CFLAGS) $(INCLUDEDIR) -c $< -o $@
90
91clean:
92 rm -f $(COBJS) *.o *.so *.sec
93```
94
95### CMakeLists.txt文件
96选用CMake编译框架需要填写CMakeLists.txt文件，如下所示为teekit/TA_demo目录下MakeLists.txt示例：
97```
98cmake_minimum_required(VERSION 3.16 FATAL_ERROR)
99project(tee_sdk C)
100
101if (PROJECT_SOURCE_DIR STREQUAL PROJECT_BINARY_DIR)
102 message(FATAL_ERROR "Forbid compiling in the source tree")
103endif()
104
105# API_LEVEL which indicates the GP API version of TA
106# API_LEVEL=2 indicates GP 1.1.1 which is the current version of the partner
107# API_LEVEL=3 indicates GP 1.2 which is the version we both going to support
108# If no API_LEVEL is specified, API of GP 1.1.1 will be taken
109# TEE flags
110set(COMMON_CFLAGS -DAPI_LEVEL=2)
111
112include($ENV{TEE_OH_BUILD_PATH}/cmake/common.cmake)
113
114set(LIBRARY_OUTPUT_PATH ${CMAKE_CURRENT_SOURCE_DIR})
115set(CURRENT_TARGET_SO "combine")
116
117file(GLOB SOURCES *.c)
118
119set(SDK_C_SOURCES
120 ${SDK_C_SOURCES}
121 ${SOURCES}
122)
123
124add_library(${CURRENT_TARGET_SO} SHARED ${SDK_C_SOURCES})
125target_include_directories(${CURRENT_TARGET_SO} PUBLIC ${COMMON_INCLUDES})
126target_compile_options(${CURRENT_TARGET_SO} PRIVATE ${COMMON_CFLAGS})
127target_link_options(${CURRENT_TARGET_SO} PRIVATE ${COMMON_LDFLAGS})
128```
129
130### configs.xml文件/manifest.txt文件
131TA开发时需要提供TA配置信息文本文件，以configs.xml或manifest.txt两种格式呈现。<br>
132manifest.txt示例：
133```
134gpd.ta.appID: e3d37f4a-f24c-48d0-8884-3bdd6c44e988
135gpd.ta.service_name: demo-ta
136gpd.ta.singleInstance: true
137gpd.ta.multiSession: false
138gpd.ta.instanceKeepAlive: false
139gpd.ta.dataSize: 327680
140gpd.ta.stackSize: 32768
141```
142configs.xml文本文件的编写需要参照示例的xml文件格式要求进行。可信应用镜像生成时，configs.xml文件格式错误，可信应用镜像的生成会终止。64位TA的configs.xml文件格式与32位TA相同。如下为configs.xml示例：
143```
144<?xml version="1.0" encoding="utf-8"?>
145<ConfigInfo>
146 <TA_Basic_Info>
147 <service_name>demo-ta</service_name>
148 <uuid>e3d37f4a-f24c-48d0-8884-3bdd6c44e988</uuid>
149 </TA_Basic_Info>
150 <TA_Manifest_Info>
151 <instance_keep_alive>false</instance_keep_alive>
152 <stack_size>32768</stack_size>
153 <heap_size>327680</heap_size>
154 <multi_session>false</multi_session>
155 <single_instance>true</single_instance>
156 </TA_Manifest_Info>
157</ConfigInfo>
158```
159
160## TA签名公私钥对生成与配置
161通过openssl生成TA对应签名私钥，并将生成的私钥文件ta_sign_priv_key.pem放置于TA_demo目录下用于TA签名：
162```
163openssl genrsa -out ta_sign_priv_key.pem 4096
164```
165并基于生成的私钥文件生成对于的签名公钥文件
166```
167openssl rsa -in ta_sign_priv_key.pem -pubout -out ta_verify_pub_key.pem
168```
169通过以下命令查看验签公钥的详细信息，获取rsa公钥n值（去除Modulus信息中首位00），并替换base/tee/tee_os_frame_work仓下lib/syslib/libelf_verify_key/src/common/openharmony/ta_verify_key.c中全局结构体 g_ta_verify_pub_rsa_key中结构体中数组n的值：
170```
171openssl rsa -in ta_verify_pub_key.pem -pubin -text -noout
172```
173如下示例为随机生成的rsa验签公钥Modulus信息：
174```
175RSA Public-Key: (4096 bit)
176Modulus:
177 00:bf:b7:80:7f:89:6b:c4:2d:fa:d3:02:8f:f3:f4:
178 54:6e:a2:51:a1:5c:9a:10:85:b2:37:f4:56:73:6f:
179 11:af:ff:b7:22:04:4b:44:55:47:f7:39:52:cf:e4:
180 0e:ab:19:91:9e:a2:31:65:60:67:39:df:bd:f1:a2:
181 57:aa:f7:0f:ff:d4:4e:11:95:9e:8d:88:f0:9b:70:
182 37:3a:74:d7:14:8e:85:bf:a4:60:74:54:b7:f3:7d:
183 b3:62:b6:bf:f8:6c:18:d3:7e:4e:7d:31:2b:b8:a4:
184 09:04:d8:68:a9:08:7e:34:57:47:b0:d7:c6:11:ee:
185 e0:23:0d:97:a9:1c:a2:ca:27:e6:cc:8e:aa:ea:5f:
186 d5:e2:a2:2e:c3:eb:10:4e:86:bf:ce:b2:c5:0a:39:
187 01:62:da:38:f3:8d:11:0e:b8:a2:f1:4d:97:56:d1:
188 f2:91:75:06:f4:e0:2b:c6:4f:a9:df:e5:1f:e2:19:
189 7a:df:79:6b:39:31:a7:fd:48:5e:72:95:91:23:80:
190 ca:fd:e4:2e:f6:87:8e:cb:d8:73:72:5f:7b:c1:5f:
191 4f:eb:a0:4e:38:08:ea:e0:5c:e7:ec:e5:21:5e:39:
192 11:4d:66:60:95:fc:83:1f:67:6a:46:32:bf:81:b1:
193 7f:ad:0d:ed:e7:1e:eb:1e:09:a0:65:da:e4:71:e7:
194 42:e7:5c:7f:c3:63:9d:5d:da:3b:59:1d:79:1a:d2:
195 f5:3c:c5:51:3a:8b:81:20:f2:33:69:95:0a:03:0b:
196 52:a8:85:1c:e6:5d:a2:39:05:9a:73:c7:d6:d9:5a:
197 42:19:82:60:a9:56:72:f5:88:f5:fa:f7:e5:14:24:
198 b3:9d:93:a4:40:ac:27:ac:6b:83:88:80:68:7e:24:
199 57:a4:a7:8d:41:01:3a:bc:a6:c6:cc:a6:8a:91:14:
200 d7:ca:bf:85:ea:ac:1a:1a:b5:cc:13:1d:82:20:33:
201 2b:55:2f:fd:ac:a5:e3:9e:db:81:af:58:c5:c5:f3:
202 07:b3:f6:b4:bf:26:57:a0:51:3e:60:31:88:70:3e:
203 af:16:fd:0b:6e:55:2b:d5:38:a7:9d:3a:d0:54:d0:
204 cc:30:51:49:c1:a5:05:03:f9:25:35:4d:1c:e1:e0:
205 63:2d:c8:47:0a:0c:78:9d:ce:35:bc:66:39:80:52:
206 04:6e:7c:47:44:2d:d5:4b:54:18:80:8a:a4:4e:d4:
207 69:4b:87:21:92:d1:9f:07:2c:be:02:c9:cf:0a:01:
208 35:c1:68:b5:fd:a5:e2:b1:67:bf:b7:4c:32:cf:1f:
209 ce:9c:d0:12:bd:00:5c:45:f0:ed:46:27:ca:7d:dd:
210 4f:1e:73:2c:f3:1c:72:4e:28:9a:10:3a:45:53:b9:
211 b1:87:a1
212Exponent: 65537 (0x10001)
213```
214
215## Config证书签名指导说明
216
217在./script/目录下创建新文件夹，目录结构如下：
218```
219./script
220├── config_cert # 放置taconfig.der（证书）和 taconfig_key.pem（私钥）
221├── ta_cert # 放置TA/DRV开发者证书ta_cert.der
222├── output # 生成签名后证书文件perm_config
223```
224
225config证书签名操作示例：
226```
227python3 signtool_config.py ./config ./ta_cert/ta_cert.der ./output/perm_config
228```
229
230## 三方头文件导出
231可信应用编译依赖三方libc和musl开源头文件，开发者需要预先下载openharmony代码，并于/base/tee/tee_dev_kit/thirdparty/open_source/目录下执行：
232```
233bash import_open_source_header.sh
234```
235
236## CA hash鉴权哈希值生成工具
237
2381、根据应用信息填写ca_caller_info.xml<br>
2392、执行calc_ca_caller_hash.py脚本获取CA信息对应哈希值<br>
240```
241python3 calc_ca_caller_hash.py
242```
243获取示例如下:
244```
24516:59:42 line:128 INFO:root:cmdline: /vendor/bin/teec_hello, uid: 0
24616:59:42 line:42 INFO:root:caller hash: 0xca 0x9f 0x5e 0xd7 0x6d 0x7 0xd 0x66 0xe7 0xb2 0xab 0xb3 0x55 0xfc 0xb0 0xbf 0xc8 0x16 0x52 0x37 0x5f 0xfe 0x99 0xfc 0x34 0x43 0xf6 0x5f 0xc 0x70 0x44 0x48
24716:59:42 line:152 INFO:root:cmdline: /vendor/bin/teec_hello, username: root
24816:59:42 line:42 INFO:root:caller hash: 0x29 0x89 0x3c 0x7f 0x92 0xfd 0xce 0x8e 0xd9 0x66 0xfc 0xa0 0x10 0xa0 0xe2 0xa3 0x42 0x31 0x7d 0x65 0x36 0x48 0x38 0x86 0xf1 0x8 0x1b 0x8 0x12 0xc2 0x4c 0x9b
24916:59:42 line:180 INFO:root:pkg_name: com.example.myapplicationohdemo, modulue:6f85f3ad5fa01dfcddd4b2f23815f47fc03a68fbe99297be20bd0e114b7e8c54, exponent: 650769812a97c80a3751f015e7b6069492c0fe8de375abe8cdf9188c9c0d3851
25016:59:42 line:42 INFO:root:caller hash: 0x5c 0x86 0x46 0xb2 0x11 0xb 0x92 0xa0 0x5a 0x12 0x90 0x8c 0x6a 0x98 0xbe 0xf2 0x10 0x6e 0x65 0x20 0x7b 0xa1 0xc5 0x3e 0x55 0x34 0xac 0x36 0x5a 0xe2 0xf5 0xe9
251```
252
253