From ac94ad2ef113bac1f3c80a654f6c3836e547f96c Mon Sep 17 00:00:00 2001 From: chenmaodong Date: Thu, 18 Feb 2021 14:42:42 +0800 Subject: [PATCH 5/7] delete unnecessary README.cn.md Signed-off-by: chenmaodong --- README.cn.md | 454 ------------------------ README.en.md | 27 +- README.md | 967 ++++++++++++++++++++++++--------------------------- 3 files changed, 469 insertions(+), 979 deletions(-) delete mode 100644 README.cn.md diff --git a/README.cn.md b/README.cn.md deleted file mode 100644 index 54c32e3..0000000 --- a/README.cn.md +++ /dev/null @@ -1,454 +0,0 @@ -secGear - -secGear -============================ - -介绍 ------------ - -SecGear则是面向计算产业的机密计算安全应用开发套件。旨在方便开发者在不同的硬件设备上提供统一开发框架。目前secGear支持intel SGX硬件和Trustzone itrustee。 - -构建、安装 ----------------- - -- [详见 构建、安装](./docs/build_install.md) - -开发应用和编译 ------------------------------- - -开发目录 .../secGear/examples/test/ - -### 1 编写edl接口文件 - - enclave { - include "secgear_urts.h" - from "secgear_tstdc.edl" import *; - trusted { - public int get_string([out, size=32]char *buf); - }; - }; -'include "secgear_urts.h" from "secgear_tstdc.edl" import *'是为了屏蔽SGX和iTrustee在调用libc库之间的差异。所以为了开发代码的一致性，默认导入这两个文件。 -有关edl语法的详细信息，请参阅SGX开发文档定义的EDL(Enclave Definition Language)语法部分。 -目前SGX和iTrustee在基本类型、指针类型和深拷贝方面是相互兼容的。对于user_check、private ecalls、switchless特性仅支持sgx硬件。 - -保存文件名为test.edl - -### 2 编写最外层CMakeLists.txt文件 - - cmake_minimum_required(VERSION 3.12 FATAL_ERROR) - project(TEST C) - set(CMAKE_C_STANDARD 99) - set(CURRENT_ROOT_PATH ${CMAKE_CURRENT_SOURCE_DIR}) - set(EDL_FILE test.edl) - set(LOCAL_ROOT_PATH "$ENV{CC_SDK}") - set(SECGEAR_INSTALL_PATH /lib64/) - if(CC_GP) - set(CODETYPE trustzone) - set(CODEGEN codegen_arm64) - execute_process(COMMAND uuidgen -r OUTPUT_VARIABLE UUID) - string(REPLACE "\n" "" UUID ${UUID}) - add_definitions(-DPATH="/data/${UUID}.sec") - endif() - if(CC_SGX) - set(CODETYPE sgx) - set(CODEGEN codegen_x86_64) - add_definitions(-DPATH="${CMAKE_CURRENT_BINARY_DIR}/enclave/enclave.signed.so") - endif() - add_subdirectory(${CURRENT_ROOT_PATH}/enclave) - add_subdirectory(${CURRENT_ROOT_PATH}/host) - -EDL_FILE、CODETYPE：稍后自动构建的时候会用到这些属性。 -UUID：在iTrustee中，构建安全enclave动态库需要使用UUID命名，这里由uuidgen命令自动生成。 -DPATH：用于定义非安全侧使用安全侧动态库的绝对路径 - -### 3 编写非安全侧代码和CMakeLists.txt文件 - -#### 3.1 创建host目录和main.c文件 - - #include - #include "enclave.h" - #include "test_u.h" - - #define BUF_LEN 32 - - int main() - { - int retval = 0; - char *path = PATH; - char buf[BUF_LEN]; - cc_enclave_t *context = NULL; - cc_enclave_result_t res; - - res = cc_enclave_create(path, AUTO_ENCLAVE_TYPE, 0, SECGEAR_DEBUG_FLAG, NULL, 0, &context); - ... - - res = get_string(context, &retval, buf); - if (res != CC_SUCCESS || retval != (int)CC_SUCCESS) { - printf("Ecall enclave error\n"); - } else { - printf("%s\n", buf); - } - - if (context != NULL) { - res = cc_enclave_destroy(context); - ... - } - return res; - } - -enclave.h: secGear库头文件 -test_u.h: 根据edl文件自动生成的非安全侧头文件。 -cc_enclave_create: 用于创建enclave安全上下文。 -get_string: 根据edl中trusted定义的安全侧代理函数，该代理函数用于进入到安全侧执行安全代码。 -cc_enclave_destroy: 用于销毁enclave安全上下文。 - -注意：这里调用的get_string函数与在edl中定义的get_string函数有些不同，这里的参数比edl中定义的多了前两个参数，分别是enclave安全上下文 -和retval参数。这是因为codegen（自动生成代码工具）通过edl生成的非安全侧代理函数，其声明在test_u.h中。 -如果在edl中定义的函数无返回值时，例如"public void get_string([out,size=32] char *buf);"则非安全侧代理函数为 -"res=get_string(context, buf)"(这里就不在有retval参数) - -#### 3.2 编写非安全侧CMakeLists.txt - - #set auto code prefix - set(PREFIX test) - #set host exec name - set(OUTPUT secgear_test) - #set host src code - set(SOURCE_FILE ${CMAKE_CURRENT_SOURCE_DIR}/main.c) - -设置预备的基础变量 - - #set auto code - if(CC_GP) - set(AUTO_FILES ${CMAKE_CURRENT_BINARY_DIR}/${PREFIX}_u.h ${CMAKE_CURRENT_BINARY_DIR}/${PREFIX}_u.c ${CMAKE_CURRENT_BINARY_DIR}/${PREFIX}_args.h) - add_custom_command(OUTPUT ${AUTO_FILES} - DEPENDS ${CURRENT_ROOT_PATH}/${EDL_FILE} - COMMAND ${CODEGEN} --${CODETYPE} --untrusted ${CURRENT_ROOT_PATH}/${EDL_FILE} --search-path ${LOCAL_ROOT_PATH}/inc/host_inc/gp) - endif() - - if(CC_SGX) - set(AUTO_FILES ${CMAKE_CURRENT_BINARY_DIR}/${PREFIX}_u.h ${CMAKE_CURRENT_BINARY_DIR}/${PREFIX}_u.c) - add_custom_command(OUTPUT ${AUTO_FILES} - DEPENDS ${CURRENT_ROOT_PATH}/${EDL_FILE} - COMMAND ${CODEGEN} --${CODETYPE} --untrusted ${CURRENT_ROOT_PATH}/${EDL_FILE} --search-path ${LOCAL_ROOT_PATH}/inc/host_inc/sgx --search-path ${SGXSDK}/include) - endif() - -设置使用代码辅助生成工具根据edl文件生成辅助代码。CODEGEN和CODETYPE等变量定义在CMakeList.txt文件.--search-path用于搜索在edl文件中导入依赖的其他edl文件。 -当使用SGX时，需要导入sgx提供的基础edl，因此这里指定了SGXSDK的patch "--search-path ${SGXSDK}/include)"。 - - set(CMAKE_C_FLAGS "-fstack-protector-all -W -Wall -Werror -Wextra -Werror=array-bounds -D_FORTIFY_SOURCE=2 -O2 -ftrapv -fPIE") - set(CMAKE_EXE_LINKER_FLAGS "-Wl,-z,relro -Wl,-z,now -Wl,-z,noexecstack") - -设置编译选项和链接选项 - - if(CC_GP) - if(${CMAKE_VERSION} VERSION_LESS "3.13.0") - link_directories(${SECGEAR_INSTALL_PATH}) - endif() - add_executable(${OUTPUT} ${SOURCE_FILE} ${AUTO_FILES}) - target_include_directories(${OUTPUT} PRIVATE - ${LOCAL_ROOT_PATH}/inc/host_inc - ${LOCAL_ROOT_PATH}/inc/host_inc/gp - ${CMAKE_CURRENT_BINARY_DIR}) - if(${CMAKE_VERSION} VERSION_GREATER_EQUAL "3.13.0") - target_link_directories(${OUTPUT} PRIVATE ${SECGEAR_INSTALL_PATH}) - endif() - endif() - -在iTrustee硬件环境上，设置头文件的搜索路径及编译生成非安全侧二进制文件。 - - if(CC_SGX) - if(${CMAKE_VERSION} VERSION_LESS "3.13.0") - link_directories(${SECGEAR_INSTALL_PATH}) - endif() - add_executable(${OUTPUT} ${SOURCE_FILE} ${AUTO_FILES}) - target_include_directories(${OUTPUT} PRIVATE - ${LOCAL_ROOT_PATH}/inc/host_inc - ${LOCAL_ROOT_PATH}/inc/host_inc/sgx - ${CMAKE_CURRENT_BINARY_DIR}) - if(${CMAKE_VERSION} VERSION_GREATER_EQUAL "3.13.0") - target_link_directories(${OUTPUT} PRIVATE ${SECGEAR_INSTALL_PATH}) - endif() - endif() - -在SGX硬件环境上，设置头文件的搜索路径及编译生成非安全侧二进制文件。 - - if(CC_SIM) - target_link_libraries(${OUTPUT} secgearsim) - else() - target_link_libraries(${OUTPUT} secgear) - endif() - set_target_properties(${OUTPUT} PROPERTIES SKIP_BUILD_RPATH TRUE) - if(CC_GP) - install(TARGETS ${OUTPUT} - RUNTIME - DESTINATION /vendor/bin/ - PERMISSIONS OWNER_EXECUTE OWNER_WRITE OWNER_READ) - endif() - if(CC_SGX) - install(TARGETS ${OUTPUT} - RUNTIME - DESTINATION ${CMAKE_BINARY_DIR}/bin/ - PERMISSIONS OWNER_EXECUTE OWNER_WRITE OWNER_READ) - endif() - - -设置secGear链接库，当指定模拟模式CC_SIM时链接libsecgearsim.so，否则链接libsecgear.so。 -在iTrustee硬件环境上需指定安装固定的安全白名单。 - -### 4 编写安全侧代码、CMakeList.txt及基础配置文件 - -#### 4.1 创建enclave目录 编写hello.c - - #include - #include - #include "test_t.h" - - #define TA_HELLO_WORLD "secGear hello world!" - #define BUF_MAX 32 - int get_string(char *buf) - { - strncpy(buf, TA_HELLO_WORLD, strlen(TA_HELLO_WORLD) + 1); - return 0; - } - -test_t.h：该头文件为自动生成代码工具codegen通过edl文件生成的头文件。该头文件命名为edl文件名加"_t"。 - -#### 4.2 编写CMakeList.txt文件 - - #set auto code prefix - set(PREFIX test) - #set sign key - set(PEM Enclave_private.pem) - -设置enclave签名私钥 - - #set sign tool - set(SIGN_TOOL ${LOCAL_ROOT_PATH}/tools/sign_tool/sign_tool.sh) - #set enclave src code - set(SOURCE_FILES ${CMAKE_CURRENT_SOURCE_DIR}/hello.c) - #set log level - set(PRINT_LEVEL 3) - add_definitions(-DPRINT_LEVEL=${PRINT_LEVEL}) - -设置签名工具已经安全侧打印日志level - - if(CC_GP) - #set signed output - set(OUTPUT ${UUID}.sec) - #set itrustee device key - set(DEVICEPEM ${CMAKE_CURRENT_SOURCE_DIR}/rsa_public_key_cloud.pem) - - set(WHITE_LIST_0 /vendor/bin/helloworld) - set(WHITE_LIST_1 /vendor/bin/secgear_test) - set(WHITE_LIST_OWNER root) - set(WHITELIST WHITE_LIST_0 WHITE_LIST_1) - - set(AUTO_FILES ${CMAKE_CURRENT_BINARY_DIR}/${PREFIX}_t.h ${CMAKE_CURRENT_BINARY_DIR}/${PREFIX}_t.c ${CMAKE_CURRENT_BINARY_DIR}/${PREFIX}_args.h) - add_custom_command(OUTPUT ${AUTO_FILES} - DEPENDS ${CURRENT_ROOT_PATH}/${EDL_FILE} - COMMAND ${CODEGEN} --${CODETYPE} --trusted ${CURRENT_ROOT_PATH}/${EDL_FILE} --search-path ${LOCAL_ROOT_PATH}/inc/host_inc/gp) - endif() - -WHITE_LIST_x：为设置iTrustee的二进制白名单，只有这里定义的白名单，在非安全侧的二进制才可以调用安全侧的动态库。上限为8个。 -WHITE_LIST_OWNER：为设置运行二进制的用户，只有该用户才可以调用安全侧动态库。 -DEVICEPEM：该公钥用来动态生成aes秘钥 -AUTO_FILES：由edl文件生成的安全侧二进制文件 - - if(CC_SGX) - set(OUTPUT enclave.signed.so) - set(AUTO_FILES ${CMAKE_CURRENT_BINARY_DIR}/${PREFIX}_t.h ${CMAKE_CURRENT_BINARY_DIR}/${PREFIX}_t.c) - add_custom_command(OUTPUT ${AUTO_FILES} - DEPENDS ${CURRENT_ROOT_PATH}/${EDL_FILE} - COMMAND ${CODEGEN} --${CODETYPE} --trusted ${CURRENT_ROOT_PATH}/${EDL_FILE} --search-path ${LOCAL_ROOT_PATH}/inc/host_inc/sgx --search-path ${SGXSDK}/include) - endif() - -设置自动生成代码及签名动态库。 - - set(COMMON_C_FLAGS "-W -Wall -Werror -fno-short-enums -fno-omit-frame-pointer -fstack-protector \ - -Wstack-protector --param ssp-buffer-size=4 -frecord-gcc-switches -Wextra -nostdinc -nodefaultlibs \ - -fno-peephole -fno-peephole2 -Wno-main -Wno-error=unused-parameter \ - -Wno-error=unused-but-set-variable -Wno-error=format-truncation=") - - set(COMMON_C_LINK_FLAGS "-Wl,-z,now -Wl,-z,relro -Wl,-z,noexecstack -Wl,-nostdlib -nodefaultlibs -nostartfiles") - -设置安全侧便编译选项和链接选项。由于安全侧和非安全侧不同，非安全侧的标准动态库不能被安全侧链接。例如："-nostdlib -nodefaultlibs -nostartfiles" - - - if(CC_GP) - configure_file("${CMAKE_CURRENT_SOURCE_DIR}/manifest.txt.in" "${CMAKE_CURRENT_SOURCE_DIR}/manifest.txt") - - set(CMAKE_C_FLAGS "${COMMON_C_FLAGS} -march=armv8-a ") - set(CMAKE_C_FLAGS_RELEASE "${CMAKE_C_FLAGS} -s -fPIC") - set(CMAKE_SHARED_LINKER_FLAGS "${COMMON_C_LINK_FLAGS} -Wl,-s") - - set(ITRUSTEE_TEEDIR ${iTrusteeSDK}/) - set(ITRUSTEE_LIBC ${iTrusteeSDK}/thirdparty/open_source/musl/libc) - - if(${CMAKE_VERSION} VERSION_LESS "3.13.0") - link_directories(${SECGEAR_INSTALL_PATH}) - endif() - - add_library(${PREFIX} SHARED ${SOURCE_FILES} ${AUTO_FILES}) - - target_include_directories( ${PREFIX} PRIVATE - ${CMAKE_CURRENT_BINARY_DIR} - ${LOCAL_ROOT_PATH}/inc/host_inc - ${LOCAL_ROOT_PATH}/inc/host_inc/gp - ${LOCAL_ROOT_PATH}/inc/enclave_inc - ${LOCAL_ROOT_PATH}/inc/enclave_inc/gp - ${ITRUSTEE_TEEDIR}/include/TA - ${ITRUSTEE_TEEDIR}/include/TA/huawei_ext - ${ITRUSTEE_LIBC}/arch/aarch64 - ${ITRUSTEE_LIBC}/ - ${ITRUSTEE_LIBC}/arch/arm/bits - ${ITRUSTEE_LIBC}/arch/generic - ${ITRUSTEE_LIBC}/arch/arm - ${LOCAL_ROOT_PATH}/inc/enclave_inc/gp/itrustee) - - if(${CMAKE_VERSION} VERSION_GREATER_EQUAL "3.13.0") - target_link_directories(${PREFIX} PRIVATE ${SECGEAR_INSTALL_PATH}) - endif() - - foreach(WHITE_LIST ${WHITELIST}) - add_definitions(-D${WHITE_LIST}="${${WHITE_LIST}}") - endforeach(WHITE_LIST) - add_definitions(-DWHITE_LIST_OWNER="${WHITE_LIST_OWNER}") - - target_link_libraries(${PREFIX} -lsecgear_tee) - - add_custom_command(TARGET ${PREFIX} - POST_BUILD - COMMAND bash ${SIGN_TOOL} -d sign -x trustzone -i lib${PREFIX}.so -m ${CMAKE_CURRENT_SOURCE_DIR}/manifest.txt - -e ${DEVICEPEM} -o ${CMAKE_CURRENT_BINARY_DIR}/${OUTPUT}) - - install(FILES ${CMAKE_CURRENT_BINARY_DIR}/${OUTPUT} - DESTINATION /data - PERMISSIONS OWNER_EXECUTE OWNER_WRITE OWNER_READ GROUP_READ GROUP_EXECUTE WORLD_READ WORLD_EXECUTE) - - endif() - -manifest.txt：itrustee安全侧配置文件，后面对该文件进行详解 -指定itrustee特性编译选项，设置引用头文件和动态库的路径。 -前面声明的白名单在这里定义。 -itrustee需要链接secgear_tee动态库，提供seal接口等。 - - if(CC_SGX) - set(SGX_DIR ${SGXSDK}) - set(CMAKE_C_FLAGS "${COMMON_C_FLAGS} -m64 -fvisibility=hidden") - set(CMAKE_C_FLAGS_RELEASE "${CMAKE_C_FLAGS} -s") - set(LINK_LIBRARY_PATH ${SGX_DIR}/lib64) - - if(CC_SIM) - set(Trts_Library_Name sgx_trts_sim) - set(Service_Library_Name sgx_tservice_sim) - else() - set(Trts_Library_Name sgx_trts) - set(Service_Library_Name sgx_tservice) - endif() - - set(Crypto_Library_Name sgx_tcrypto) - - set(CMAKE_SHARED_LINKER_FLAGS "${COMMON_C_LINK_FLAGS} -Wl,-z,defs -Wl,-pie -Bstatic -Bsymbolic -eenclave_entry \ - -Wl,--export-dynamic -Wl,--defsym,__ImageBase=0 -Wl,--gc-sections -Wl,--version-script=${CMAKE_CURRENT_SOURCE_DIR}/Enclave.lds") - - if(${CMAKE_VERSION} VERSION_LESS "3.13.0") - link_directories(${LINK_LIBRARY_PATH}) - endif() - - add_library(${PREFIX} SHARED ${SOURCE_FILES} ${AUTO_FILES}) - - target_include_directories(${PREFIX} PRIVATE - ${CMAKE_CURRENT_BINARY_DIR} - ${SGX_DIR}/include/tlibc - ${SGX_DIR}/include/libcxx - ${SGX_DIR}/include - ${LOCAL_ROOT_PATH}/inc/host_inc - ${LOCAL_ROOT_PATH}/inc/host_inc/sgx) - - if(${CMAKE_VERSION} VERSION_GREATER_EQUAL "3.13.0") - target_link_directories(${PREFIX} PRIVATE - ${LINK_LIBRARY_PATH}) - endif() - - target_link_libraries(${PREFIX} -Wl,--whole-archive ${Trts_Library_Name} -Wl,--no-whole-archive - -Wl,--start-group -lsgx_tstdc -lsgx_tcxx -l${Crypto_Library_Name} -l${Service_Library_Name} -Wl,--end-group) - add_custom_command(TARGET ${PREFIX} - POST_BUILD - COMMAND openssl genrsa -3 -out ${PEM} 3072 - COMMAND bash ${SIGN_TOOL} -d sign -x sgx -i lib${PREFIX}.so -k ${PEM} -o ${OUTPUT} -c ${CMAKE_CURRENT_SOURCE_DIR}/Enclave.config.xml) - endif() - - -在SGX硬件环境上，指定一些与sgx相关的编译选项、链接选项。链接动态库时有所不同，因为itrustee是一个具有更多功能的安全操作系统。提供如muslibc和openssl。在编译和链接itrustee时不用链接一些基本库，但是sgx没有OS概念。所以要在安全侧调用这些基本库的接口都要以静态的形式在sgxsdk中给出。例如"sgx_trts" - -有关更多详细信息，请参阅sgx示例的Makefile。最后用enclave配置文件完成签名，稍后将进行介绍。secGear尚不支持远程身份验证。 - -#### 4.3 编写安全侧配置文件 - -编写与sgx enclave相关的配置文件中Enclave.config.xml文件及enclave.lds文件与官方sgx配置相同。详情参阅官方开发文档。 - -编写itrustee enclave相关配置文件 -mainfest.txt.in:其中gpd.ta.appID 为动态生成uuid。其他配置参见itrustee开发文档。 - -rsa_public_key_cloud.pem文件请将其他examples的中的拷贝过来，这里的设备公钥用于使用临时生成的aes密钥用于对enclave动态库进行加密。 - -#### 5 构建 安装 - -进入开发目录：cd .../secGear/example/test/ -创建debug目录：mkdir debug && cd debug -cmake构建：cmake -DCMAKE_BUILD_TYPE=Debug -DCC_SGX=ON -DSGXSDK=sgx_sdk path .. && make && sudo make install （sgx硬件环境） - cmake -DCMAKE_BUILD_TYPE=Debug -DCC_GP=ON -DiTrusteeSDK=gp_sdk path .. && make && sudo make install （itrustee硬件环境） - -Log ---- -非安全侧日志记录： - -非安全侧是开发与普通开发环境一样，可使用通用打印日志接口。 - -安全侧日志记录： - -由于各架构安全能力不同的限制，为了像非安全侧一样开发使用日志打印功能，因为我们提供了PrintInfo接口将安全端日志记录到syslog系统中。 -相关配置文件为 conf/logrotate.d/secgear和conf/rsyslog.d/secgear.conf文件，安装时将安装在系统目录/etc/中。 - -注意：在itrustee上，需要include secgear_log.h头文件，但是sgx不需要，sgx通过ocall功能实现的，所以相关代码生成在辅助代码中。 -当文件安装成功后需要运行"systemctl restart rsyslog"使日志功能生效。 - -日志等级： - - PRINT_ERROR 0 - PRINT_WARNING 1 - PRINT_STRACE 2 - PRINT_DEBUG 3 - -使用ocall ---------- - -目前ocall仅在sgx平台支持，itrustee尚不支持。 - -seal, generate_random接口 --------------------------------------- - -接口定义在secgear_dataseal.h、secgear_random.h中。 -注意：由于itrustee派生密钥的功能仍然不完善，因此目前还没有与密封相关的接口在itrustee平台上支持。 - -远程证明（尚不支持） --------------------------------------- - -了解更多关于codegener --------------------------------------- - -secGear引入EDL(Enclave Description Language)和中间代码辅助生成工具codegener。edl与intel sgx定义兼容。 - - -- [了解更多关于codegener](./docs/codegener.md) - -了解更多关于sign_tool ------------------------------ - - -- [了解更多关于签名工具](./docs/sign_tool.md) - -里程碑 ---------- -secGear \ No newline at end of file diff --git a/README.en.md b/README.en.md index a8768cb..fa47d03 100644 --- a/README.en.md +++ b/README.en.md @@ -170,10 +170,9 @@ Set compile and link options if(${CMAKE_VERSION} VERSION_GREATER_EQUAL "3.13.0") target_link_directories(${OUTPUT} PRIVATE ${SECGEAR_INSTALL_PATH}) endif() - target_link_libraries(${OUTPUT} secgear) endif() -In the case of iTrustee, set the search paths of the header file and the link file, and compile the final non-secure binary. +In the case of iTrustee, set the search paths of the header file and compile the final non-secure binary. if(CC_SGX) if(${CMAKE_VERSION} VERSION_LESS "3.13.0") @@ -187,12 +186,16 @@ In the case of iTrustee, set the search paths of the header file and the link fi if(${CMAKE_VERSION} VERSION_GREATER_EQUAL "3.13.0") target_link_directories(${OUTPUT} PRIVATE ${SECGEAR_INSTALL_PATH}) endif() - target_link_libraries(${OUTPUT} secgear) endif() -In the case of sgx, set the search paths of the header file and the link file, and compile the final non-secure binary. +In the case of sgx, set the search paths of the header file and compile the final non-secure binary. - set_target_properties(${OUTPUT} PROPERTIES SKIP_BUILD_RPATH TRUE) + if(CC_SIM) + target_link_libraries(${OUTPUT} secgearsim) + else() + target_link_libraries(${OUTPUT} secgear) + endif() + set_target_properties(${OUTPUT} PROPERTIES SKIP_BUILD_RPATH TRUE) if(CC_GP) install(TARGETS ${OUTPUT} RUNTIME @@ -206,8 +209,9 @@ In the case of sgx, set the search paths of the header file and the link file, a PERMISSIONS OWNER_EXECUTE OWNER_WRITE OWNER_READ) endif() -Specify the installation path of the final binary. The non-secure side image of iTrustee must be installed on the -specified whitelist. The whitelist configuration will be introduced below. +Based on -DCC_SIM=ON or none transferred from cmake, linking secgear or secgearsim. Specify the installation +path of the final binary. The non-secure side image of iTrustee must be installed on the specified whitelist. +The whitelist configuration will be introduced below. ### 4 Write security side code, CMakeLists.txt and some configuration files @@ -353,18 +357,17 @@ whitelist macro. Next, you need to link to the secgear_tee library, in which the random numbers, seal, unseal, etc. The last step is to sign and install. if(CC_SGX) - set(SGX_MODE HW) set(SGX_DIR ${SGXSDK}) set(CMAKE_C_FLAGS "${COMMON_C_FLAGS} -m64 -fvisibility=hidden") set(CMAKE_C_FLAGS_RELEASE "${CMAKE_C_FLAGS} -s") set(LINK_LIBRARY_PATH ${SGX_DIR}/lib64) - if(${SGX_MODE} STREQUAL HW) - set(Trts_Library_Name sgx_trts) - set(Service_Library_Name sgx_tservice) - else() + if(CC_SIM) set(Trts_Library_Name sgx_trts_sim) set(Service_Library_Name sgx_tservice_sim) + else() + set(Trts_Library_Name sgx_trts) + set(Service_Library_Name sgx_tservice) endif() set(Crypto_Library_Name sgx_tcrypto) diff --git a/README.md b/README.md index fa47d03..54c32e3 100644 --- a/README.md +++ b/README.md @@ -1,513 +1,454 @@ -secGear - -secGear -============================ - -Introduction ------------ - -secGear is an SDK to develop confidential computing apps based on hardware enclave features. The target is to use -single source code for developers to develop apps running on different hardware. Currently secGear support Intel SGX -and iTrustee running in ARM Trustzone. - -Build and Install ----------------- - -- [reference build & install](./docs/build_install.md) - -Develop Application and Compile ------------------------------- - -Assuming the development directory is .../secGear/examples/test/ - -### 1 Write edl interface description - - enclave { - include "secgear_urts.h" - from "secgear_tstdc.edl" import *; - trusted { - public int get_string([out, size=32]char *buf); - }; - }; - -include "secgear_urts.h", from "secgear_tstdc.edl" import *, to shield the difference between sgx and iTrustee when -calling the C library. So as long as you use the c library functions, for the consistency of your development code, -the default is to import these two files. - -For details about edl syntax, please refer to the sgx development document Enclave Definition Language Syntax section. -At present, sgx and iTrustee are compatible with each other in basic types, pointer buffers, and deep copy of -structures, but currently only sgx supports such things as user_check, Granting Access to ECALLs, Using Switchless -Calls and so on. - -Then save as test.edl - -### 2 Write the top-level CMakeLists.txt - - cmake_minimum_required(VERSION 3.12 FATAL_ERROR) - project(TEST C) - set(CMAKE_C_STANDARD 99) - set(CURRENT_ROOT_PATH ${CMAKE_CURRENT_SOURCE_DIR}) - set(EDL_FILE test.edl) - set(LOCAL_ROOT_PATH "$ENV{CC_SDK}") - set(SECGEAR_INSTALL_PATH /lib64/) - if(CC_GP) - set(CODETYPE trustzone) - set(CODEGEN codegen_arm64) - execute_process(COMMAND uuidgen -r OUTPUT_VARIABLE UUID) - string(REPLACE "\n" "" UUID ${UUID}) - add_definitions(-DPATH="/data/${UUID}.sec") - endif() - if(CC_SGX) - set(CODETYPE sgx) - set(CODEGEN codegen_x86_64) - add_definitions(-DPATH="${CMAKE_CURRENT_BINARY_DIR}/enclave/enclave.signed.so") - endif() - add_subdirectory(${CURRENT_ROOT_PATH}/enclave) - add_subdirectory(${CURRENT_ROOT_PATH}/host) - -Set the CODETYPE EDL_FILE and CODETYPE attributes, which will be used when automatically generated later. -On the arm platform, the build enclave image needs to be named with a unique UUID, so it is dynamically uniquely -generated using the uuidgen command. The defined DPATH macro is used when loading the enclave image. - - -### 3 Write the non-secure side code and CMakeLists.txt - -#### 3.1 Create a new host directory and write main.c - - #include - #include "enclave.h" - #include "test_u.h" - - #define BUF_LEN 32 - - int main() - { - int retval = 0; - char *path = PATH; - char buf[BUF_LEN]; - cc_enclave_t *context = NULL; - cc_enclave_result_t res; - - res = cc_enclave_create(path, AUTO_ENCLAVE_TYPE, 0, SECGEAR_DEBUG_FLAG, NULL, 0, &context); - ... - - res = get_string(context, &retval, buf); - if (res != CC_SUCCESS || retval != (int)CC_SUCCESS) { - printf("Ecall enclave error\n"); - } else { - printf("%s\n", buf); - } - - if (context != NULL) { - res = cc_enclave_destroy(context); - ... - } - return res; - } - -#include "enclave.h", import the secGear header file, #include "test_u.h" import the automatically generated code -header file. Next, call cc_enclave_create(...) to create the enclave context, and then call the wrapper of the -interface described in the edl file to enter the enclave to execute confidential code. -Finally, call cc_enclave_destroy(...) to destroy the enclave context. - -Note that the interface called here has more context and retval parameters than defined in edl file before. -This is because this function, generated by the automatic code generation tool according to edl, is a wrapper about -the real enclave code, and its declaration is in the test_u.h header file. Where the context parameter it is the -cc_enclave_t * context created before, and retval is the return value of the function defined in edl, and the res -parameter is the return value of the wrapped function. The prefix of test_u.h is consistent with the prefix of test.edl. - -If the function defined in edl does not return a value, such as "public void get_string([out, size=32]char *buf);", -then the prototype called by the user will be "res = get_string(context, buf);". - -According to these rules, you can write code when the wrapper function is not generated by code generation tool and -place the wrapper function generation in the compilation phase, which simplifies the development and compilation steps. - -#### 3.2 Write the CMakeLists.txt file of the host. - - #set auto code prefix - set(PREFIX test) - #set host exec name - set(OUTPUT secgear_test) - #set host src code - set(SOURCE_FILE ${CMAKE_CURRENT_SOURCE_DIR}/main.c) - -Set some variables, which are described in comments. - - #set auto code - if(CC_GP) - set(AUTO_FILES ${CMAKE_CURRENT_BINARY_DIR}/${PREFIX}_u.h ${CMAKE_CURRENT_BINARY_DIR}/${PREFIX}_u.c ${CMAKE_CURRENT_BINARY_DIR}/${PREFIX}_args.h) - add_custom_command(OUTPUT ${AUTO_FILES} - DEPENDS ${CURRENT_ROOT_PATH}/${EDL_FILE} - COMMAND ${CODEGEN} --${CODETYPE} --untrusted ${CURRENT_ROOT_PATH}/${EDL_FILE} --search-path ${LOCAL_ROOT_PATH}/inc/host_inc/gp) - endif() - - if(CC_SGX) - set(AUTO_FILES ${CMAKE_CURRENT_BINARY_DIR}/${PREFIX}_u.h ${CMAKE_CURRENT_BINARY_DIR}/${PREFIX}_u.c) - add_custom_command(OUTPUT ${AUTO_FILES} - DEPENDS ${CURRENT_ROOT_PATH}/${EDL_FILE} - COMMAND ${CODEGEN} --${CODETYPE} --untrusted ${CURRENT_ROOT_PATH}/${EDL_FILE} --search-path ${LOCAL_ROOT_PATH}/inc/host_inc/sgx --search-path ${SGXSDK}/include) - endif() - -Use the code generation tool to generate auxiliary code based on the edl. Variables such as CODEGEN and CODETYPE are -defined at the top of CMakeList.txt. --search-path is used to search for other edl files imported in test.edl. -When SGX is used, the edl imported in test.edl indirectly depends on the edl of the SGX SDK. Therefore, the search -path of the SGX SDK is also specified here. - - set(CMAKE_C_FLAGS "-fstack-protector-all -W -Wall -Werror -Wextra -Werror=array-bounds -D_FORTIFY_SOURCE=2 -O2 -ftrapv -fPIE") - set(CMAKE_EXE_LINKER_FLAGS "-Wl,-z,relro -Wl,-z,now -Wl,-z,noexecstack") - -Set compile and link options - - if(CC_GP) - if(${CMAKE_VERSION} VERSION_LESS "3.13.0") - link_directories(${SECGEAR_INSTALL_PATH}) - endif() - add_executable(${OUTPUT} ${SOURCE_FILE} ${AUTO_FILES}) - target_include_directories(${OUTPUT} PRIVATE - ${LOCAL_ROOT_PATH}/inc/host_inc - ${LOCAL_ROOT_PATH}/inc/host_inc/gp - ${CMAKE_CURRENT_BINARY_DIR}) - if(${CMAKE_VERSION} VERSION_GREATER_EQUAL "3.13.0") - target_link_directories(${OUTPUT} PRIVATE ${SECGEAR_INSTALL_PATH}) - endif() - endif() - -In the case of iTrustee, set the search paths of the header file and compile the final non-secure binary. - - if(CC_SGX) - if(${CMAKE_VERSION} VERSION_LESS "3.13.0") - link_directories(${SECGEAR_INSTALL_PATH}) - endif() - add_executable(${OUTPUT} ${SOURCE_FILE} ${AUTO_FILES}) - target_include_directories(${OUTPUT} PRIVATE - ${LOCAL_ROOT_PATH}/inc/host_inc - ${LOCAL_ROOT_PATH}/inc/host_inc/sgx - ${CMAKE_CURRENT_BINARY_DIR}) - if(${CMAKE_VERSION} VERSION_GREATER_EQUAL "3.13.0") - target_link_directories(${OUTPUT} PRIVATE ${SECGEAR_INSTALL_PATH}) - endif() - endif() - -In the case of sgx, set the search paths of the header file and compile the final non-secure binary. - - if(CC_SIM) - target_link_libraries(${OUTPUT} secgearsim) - else() - target_link_libraries(${OUTPUT} secgear) - endif() - set_target_properties(${OUTPUT} PROPERTIES SKIP_BUILD_RPATH TRUE) - if(CC_GP) - install(TARGETS ${OUTPUT} - RUNTIME - DESTINATION /vendor/bin/ - PERMISSIONS OWNER_EXECUTE OWNER_WRITE OWNER_READ) - endif() - if(CC_SGX) - install(TARGETS ${OUTPUT} - RUNTIME - DESTINATION ${CMAKE_BINARY_DIR}/bin/ - PERMISSIONS OWNER_EXECUTE OWNER_WRITE OWNER_READ) - endif() - -Based on -DCC_SIM=ON or none transferred from cmake, linking secgear or secgearsim. Specify the installation -path of the final binary. The non-secure side image of iTrustee must be installed on the specified whitelist. -The whitelist configuration will be introduced below. - -### 4 Write security side code, CMakeLists.txt and some configuration files - -#### 4.1 Create a new enclave directory and write hello.c - - #include - #include - #include "test_t.h" - - #define TA_HELLO_WORLD "secGear hello world!" - #define BUF_MAX 32 - int get_string(char *buf) - { - strncpy(buf, TA_HELLO_WORLD, strlen(TA_HELLO_WORLD) + 1); - return 0; - } - -Import the test_t.h generated by the automatic code generation tool, and then write the function according to the -interface description in test.edl. - -#### 4.2 Write CMakeLists.txt - - #set auto code prefix - set(PREFIX test) - #set sign key - set(PEM Enclave_private.pem) - -Set the name used to sign the enclave private key - - #set sign tool - set(SIGN_TOOL ${LOCAL_ROOT_PATH}/tools/sign_tool/sign_tool.sh) - #set enclave src code - set(SOURCE_FILES ${CMAKE_CURRENT_SOURCE_DIR}/hello.c) - #set log level - set(PRINT_LEVEL 3) - add_definitions(-DPRINT_LEVEL=${PRINT_LEVEL}) - -Set sign tool and the security side log printing level - - if(CC_GP) - #set signed output - set(OUTPUT ${UUID}.sec) - #set itrustee device key - set(DEVICEPEM ${CMAKE_CURRENT_SOURCE_DIR}/rsa_public_key_cloud.pem) - - set(WHITE_LIST_0 /vendor/bin/helloworld) - set(WHITE_LIST_1 /vendor/bin/secgear_test) - set(WHITE_LIST_OWNER root) - set(WHITELIST WHITE_LIST_0 WHITE_LIST_1) - - set(AUTO_FILES ${CMAKE_CURRENT_BINARY_DIR}/${PREFIX}_t.h ${CMAKE_CURRENT_BINARY_DIR}/${PREFIX}_t.c ${CMAKE_CURRENT_BINARY_DIR}/${PREFIX}_args.h) - add_custom_command(OUTPUT ${AUTO_FILES} - DEPENDS ${CURRENT_ROOT_PATH}/${EDL_FILE} - COMMAND ${CODEGEN} --${CODETYPE} --trusted ${CURRENT_ROOT_PATH}/${EDL_FILE} --search-path ${LOCAL_ROOT_PATH}/inc/host_inc/gp) - endif() - -WHITE_LIS_X sets the whitelist of itrustee, only the host binary of these paths can call this secure image, -and up to 8 list paths can be configured. WHITE_LIST_OWNER set user, this user will be applied to all whitelist paths. -DEVICEPEM public key is used by itrustee and is used to encrypt the enclave image of the security side with the -dynamically generated aes key. Finally, set the name of the security side image after the final signature, and -generate auxiliary code. - - if(CC_SGX) - set(OUTPUT enclave.signed.so) - set(AUTO_FILES ${CMAKE_CURRENT_BINARY_DIR}/${PREFIX}_t.h ${CMAKE_CURRENT_BINARY_DIR}/${PREFIX}_t.c) - add_custom_command(OUTPUT ${AUTO_FILES} - DEPENDS ${CURRENT_ROOT_PATH}/${EDL_FILE} - COMMAND ${CODEGEN} --${CODETYPE} --trusted ${CURRENT_ROOT_PATH}/${EDL_FILE} --search-path ${LOCAL_ROOT_PATH}/inc/host_inc/sgx --search-path ${SGXSDK}/include) - endif() - -In the case of sgx, set the name of the security side image after the final signature, and generate auxiliary code. - - set(COMMON_C_FLAGS "-W -Wall -Werror -fno-short-enums -fno-omit-frame-pointer -fstack-protector \ - -Wstack-protector --param ssp-buffer-size=4 -frecord-gcc-switches -Wextra -nostdinc -nodefaultlibs \ - -fno-peephole -fno-peephole2 -Wno-main -Wno-error=unused-parameter \ - -Wno-error=unused-but-set-variable -Wno-error=format-truncation=") - - set(COMMON_C_LINK_FLAGS "-Wl,-z,now -Wl,-z,relro -Wl,-z,noexecstack -Wl,-nostdlib -nodefaultlibs -nostartfiles") - -Set the security side, no matter whether it is sgx or itrustee will use some compilation and link options, for -example, because the security side is different from the non-secure side, the default library of host OS cannot be used, -so -nostdinc -nodefaultlibs -nostdlib -nodefaultlibs compile link options was introduced. - - if(CC_GP) - configure_file("${CMAKE_CURRENT_SOURCE_DIR}/manifest.txt.in" "${CMAKE_CURRENT_SOURCE_DIR}/manifest.txt") - - set(CMAKE_C_FLAGS "${COMMON_C_FLAGS} -march=armv8-a ") - set(CMAKE_C_FLAGS_RELEASE "${CMAKE_C_FLAGS} -s -fPIC") - set(CMAKE_SHARED_LINKER_FLAGS "${COMMON_C_LINK_FLAGS} -Wl,-s") - - set(ITRUSTEE_TEEDIR ${iTrusteeSDK}/) - set(ITRUSTEE_LIBC ${iTrusteeSDK}/thirdparty/open_source/musl/libc) - - if(${CMAKE_VERSION} VERSION_LESS "3.13.0") - link_directories(${SECGEAR_INSTALL_PATH}) - endif() - - add_library(${PREFIX} SHARED ${SOURCE_FILES} ${AUTO_FILES}) - - target_include_directories( ${PREFIX} PRIVATE - ${CMAKE_CURRENT_BINARY_DIR} - ${LOCAL_ROOT_PATH}/inc/host_inc - ${LOCAL_ROOT_PATH}/inc/host_inc/gp - ${LOCAL_ROOT_PATH}/inc/enclave_inc - ${LOCAL_ROOT_PATH}/inc/enclave_inc/gp - ${ITRUSTEE_TEEDIR}/include/TA - ${ITRUSTEE_TEEDIR}/include/TA/huawei_ext - ${ITRUSTEE_LIBC}/arch/aarch64 - ${ITRUSTEE_LIBC}/ - ${ITRUSTEE_LIBC}/arch/arm/bits - ${ITRUSTEE_LIBC}/arch/generic - ${ITRUSTEE_LIBC}/arch/arm - ${LOCAL_ROOT_PATH}/inc/enclave_inc/gp/itrustee) - - if(${CMAKE_VERSION} VERSION_GREATER_EQUAL "3.13.0") - target_link_directories(${PREFIX} PRIVATE ${SECGEAR_INSTALL_PATH}) - endif() - - foreach(WHITE_LIST ${WHITELIST}) - add_definitions(-D${WHITE_LIST}="${${WHITE_LIST}}") - endforeach(WHITE_LIST) - add_definitions(-DWHITE_LIST_OWNER="${WHITE_LIST_OWNER}") - - target_link_libraries(${PREFIX} -lsecgear_tee) - - add_custom_command(TARGET ${PREFIX} - POST_BUILD - COMMAND bash ${SIGN_TOOL} -d sign -x trustzone -i lib${PREFIX}.so -m ${CMAKE_CURRENT_SOURCE_DIR}/manifest.txt - -e ${DEVICEPEM} -o ${CMAKE_CURRENT_BINARY_DIR}/${OUTPUT}) - - install(FILES ${CMAKE_CURRENT_BINARY_DIR}/${OUTPUT} - DESTINATION /data - PERMISSIONS OWNER_EXECUTE OWNER_WRITE OWNER_READ GROUP_READ GROUP_EXECUTE WORLD_READ WORLD_EXECUTE) - - endif() - -In the case of iTrustee, generate the configuration file manifest.txt, which details of the configuration file will -be explained later, specify some compilation options related to itrustee, set the search paths of the header file and -the link file, and compile the enclave binary. - -Regarding the use of itrustee ocall, there are some other notes, which will be introduced later. Then define the -whitelist macro. Next, you need to link to the secgear_tee library, in which there are interfaces for generating -random numbers, seal, unseal, etc. The last step is to sign and install. - - if(CC_SGX) - set(SGX_DIR ${SGXSDK}) - set(CMAKE_C_FLAGS "${COMMON_C_FLAGS} -m64 -fvisibility=hidden") - set(CMAKE_C_FLAGS_RELEASE "${CMAKE_C_FLAGS} -s") - set(LINK_LIBRARY_PATH ${SGX_DIR}/lib64) - - if(CC_SIM) - set(Trts_Library_Name sgx_trts_sim) - set(Service_Library_Name sgx_tservice_sim) - else() - set(Trts_Library_Name sgx_trts) - set(Service_Library_Name sgx_tservice) - endif() - - set(Crypto_Library_Name sgx_tcrypto) - - set(CMAKE_SHARED_LINKER_FLAGS "${COMMON_C_LINK_FLAGS} -Wl,-z,defs -Wl,-pie -Bstatic -Bsymbolic -eenclave_entry \ - -Wl,--export-dynamic -Wl,--defsym,__ImageBase=0 -Wl,--gc-sections -Wl,--version-script=${CMAKE_CURRENT_SOURCE_DIR}/Enclave.lds") - - if(${CMAKE_VERSION} VERSION_LESS "3.13.0") - link_directories(${LINK_LIBRARY_PATH}) - endif() - - add_library(${PREFIX} SHARED ${SOURCE_FILES} ${AUTO_FILES}) - - target_include_directories(${PREFIX} PRIVATE - ${CMAKE_CURRENT_BINARY_DIR} - ${SGX_DIR}/include/tlibc - ${SGX_DIR}/include/libcxx - ${SGX_DIR}/include - ${LOCAL_ROOT_PATH}/inc/host_inc - ${LOCAL_ROOT_PATH}/inc/host_inc/sgx) - - if(${CMAKE_VERSION} VERSION_GREATER_EQUAL "3.13.0") - target_link_directories(${PREFIX} PRIVATE - ${LINK_LIBRARY_PATH}) - endif() - - target_link_libraries(${PREFIX} -Wl,--whole-archive ${Trts_Library_Name} -Wl,--no-whole-archive - -Wl,--start-group -lsgx_tstdc -lsgx_tcxx -l${Crypto_Library_Name} -l${Service_Library_Name} -Wl,--end-group) - add_custom_command(TARGET ${PREFIX} - POST_BUILD - COMMAND openssl genrsa -3 -out ${PEM} 3072 - COMMAND bash ${SIGN_TOOL} -d sign -x sgx -i lib${PREFIX}.so -k ${PEM} -o ${OUTPUT} -c ${CMAKE_CURRENT_SOURCE_DIR}/Enclave.config.xml) - endif() - -In the case of sgx, specify some compilation, link options related to sgx. When linking libraries, sgx and itrustee -are quite different. This is because itrustee is a secure OS with more capabilities, such as musl libc and openssl. -When compiling and link itrustee's enclave, there is no need to link some basic libraries. But sgx has no OS concept. -The basic library interfaces to be called on the security side are all given in the sgx sdk in the form of static -libraries, so this requires us to link these static libraries, and in order to be able to use these static libraries -correctly, some libraries must be linked between specified options, such as sgx_trts. - -For more detailed information, please refer to the Makefile of sgx examples. Finally, sign the enclave with the -configuration file, which will be introduced later. Note that secGear does not currently support remote authentication. - - set_target_properties(${PREFIX} PROPERTIES SKIP_BUILD_RPATH TRUE) - -Set some safe compilation options. - -#### 4.3 Enclave image configuration file - -Write sgx enclave related configuration files -The configuration content in the Enclave.config.xml and Enclave.lds files is the same as the official sgx -configuration file. For details, please refer to the official development document. - -Write itrustee related configuration files -The gpd.ta.appID in the manifest.txt.in file is the uuid configuration item, which is dynamically generated, -and the other configuration items can refer to the itrustee development document. - -Copy the rsa_public_key_cloud.pem device public key from other examples in the project to the enclave directory. -The device public key here is used to encrypt the enclave image with the temporarily generated aes key. - -### 5 build and install test - -Enter the development directory .../secGear/examples/test/, then run mkdir debug && cd debug -&& cmake -DCMAKE_BUILD_TYPE=Debug -DCC_SGX=ON -DSGXSDK=sgx_sdk path .. && make && sudo make install OR -mkdir debug && cd debug && cmake -DCMAKE_BUILD_TYPE=Debug -DCC_GP=ON -DiTrusteeSDK=gp_sdk path .. && make -&& sudo make install - -Log ---- -Non-secure side log record: - -Non-secure side development, similar to ordinary development, users can implement non-secure side application logs -by themselves - -Security side log record: - -Security side development, due to restrictions on the different security capabilities of each platform, it is -impossible to directly develop the log function like the non-secure side, Therefore, we provide the PrintInfo -interface to record the security side log to the Syslog system. The related configuration files secgear and secgear.conf -have been installed in the system directory during the build and install secGear phase. - -Note that when using on itrustee, you need to import the secgear_log.h header file, but sgx does not need it. -Because sgx implements the log function through ocall, the relevant code is in the auxiliary code. And when the -configuration file is installed, you need to run "systemctl restart rsyslog" to make the log effective. - -Finally, in order to enable itrustee logs to be dumped to the place specified in the configuration file, you also -need to run /vendor/bin/tlogcat -f. The tlogcat tool is a part of the itrustee sdk. - -The meaning of log level (set(PRINT_LEVEL 3)). - - PRINT_ERROR 0 - PRINT_WARNING 1 - PRINT_STRACE 2 - PRINT_DEBUG 3 - -At present, there are some differences in the usage of the log function. After the itrustee ocall function is stable, -the usage will be unified. - -Use ocall ---------- - -The secGear ocall function can be used normally on the sgx platform. There are currently restrictions on itrustee: - - only the specified a3d88d2a-ae2a-4ea5-a37d-35fc5f607e9e uuid can be used, - and two programs that enable ocall cannot be run at the same time, - and config cannot be enabled. ta.instanceKeepAlive. - -Moreover, if the underlying itrustee does not enable ocall, the SDK will only report an error registration ocall failure, -and the ecall function can be used normally. - -Seal, generate random number interface --------------------------------------- - -The related interface is defined in secgear_dataseal.h, secgear_random.h. For usage, please refer to examples/seal_data. -Note: Since the feature for itrustee to derive keys is still not perfect, seal related interfaces are not currently -supported on the itrustee platform. - -Remote authentication capability is currently not supported. ------------------------------------------------------------- - -secGear does not currently support plc, switchless and other about sgx features. --------------------------------------------------------------------------------- - -Learning More About codegener ----------------------------- - -secGear Introduce EDL (Enclave Description Languate) and intermediate code generation tool codegener. EDL is -compatible with Intel SGX's definition. - -- [Learn how to use codegener](./docs/codegener.md) - -Learning More About sign_tool ------------------------------ - -secGear introduce the signing tool to sign the enclave. - -- [Learn how to use signing tool](./docs/sign_tool.md) - -Milestone ---------- -secGear - +secGear + +secGear +============================ + +介绍 +----------- + +SecGear则是面向计算产业的机密计算安全应用开发套件。旨在方便开发者在不同的硬件设备上提供统一开发框架。目前secGear支持intel SGX硬件和Trustzone itrustee。 + +构建、安装 +---------------- + +- [详见 构建、安装](./docs/build_install.md) + +开发应用和编译 +------------------------------ + +开发目录 .../secGear/examples/test/ + +### 1 编写edl接口文件 + + enclave { + include "secgear_urts.h" + from "secgear_tstdc.edl" import *; + trusted { + public int get_string([out, size=32]char *buf); + }; + }; +'include "secgear_urts.h" from "secgear_tstdc.edl" import *'是为了屏蔽SGX和iTrustee在调用libc库之间的差异。所以为了开发代码的一致性，默认导入这两个文件。 +有关edl语法的详细信息，请参阅SGX开发文档定义的EDL(Enclave Definition Language)语法部分。 +目前SGX和iTrustee在基本类型、指针类型和深拷贝方面是相互兼容的。对于user_check、private ecalls、switchless特性仅支持sgx硬件。 + +保存文件名为test.edl + +### 2 编写最外层CMakeLists.txt文件 + + cmake_minimum_required(VERSION 3.12 FATAL_ERROR) + project(TEST C) + set(CMAKE_C_STANDARD 99) + set(CURRENT_ROOT_PATH ${CMAKE_CURRENT_SOURCE_DIR}) + set(EDL_FILE test.edl) + set(LOCAL_ROOT_PATH "$ENV{CC_SDK}") + set(SECGEAR_INSTALL_PATH /lib64/) + if(CC_GP) + set(CODETYPE trustzone) + set(CODEGEN codegen_arm64) + execute_process(COMMAND uuidgen -r OUTPUT_VARIABLE UUID) + string(REPLACE "\n" "" UUID ${UUID}) + add_definitions(-DPATH="/data/${UUID}.sec") + endif() + if(CC_SGX) + set(CODETYPE sgx) + set(CODEGEN codegen_x86_64) + add_definitions(-DPATH="${CMAKE_CURRENT_BINARY_DIR}/enclave/enclave.signed.so") + endif() + add_subdirectory(${CURRENT_ROOT_PATH}/enclave) + add_subdirectory(${CURRENT_ROOT_PATH}/host) + +EDL_FILE、CODETYPE：稍后自动构建的时候会用到这些属性。 +UUID：在iTrustee中，构建安全enclave动态库需要使用UUID命名，这里由uuidgen命令自动生成。 +DPATH：用于定义非安全侧使用安全侧动态库的绝对路径 + +### 3 编写非安全侧代码和CMakeLists.txt文件 + +#### 3.1 创建host目录和main.c文件 + + #include + #include "enclave.h" + #include "test_u.h" + + #define BUF_LEN 32 + + int main() + { + int retval = 0; + char *path = PATH; + char buf[BUF_LEN]; + cc_enclave_t *context = NULL; + cc_enclave_result_t res; + + res = cc_enclave_create(path, AUTO_ENCLAVE_TYPE, 0, SECGEAR_DEBUG_FLAG, NULL, 0, &context); + ... + + res = get_string(context, &retval, buf); + if (res != CC_SUCCESS || retval != (int)CC_SUCCESS) { + printf("Ecall enclave error\n"); + } else { + printf("%s\n", buf); + } + + if (context != NULL) { + res = cc_enclave_destroy(context); + ... + } + return res; + } + +enclave.h: secGear库头文件 +test_u.h: 根据edl文件自动生成的非安全侧头文件。 +cc_enclave_create: 用于创建enclave安全上下文。 +get_string: 根据edl中trusted定义的安全侧代理函数，该代理函数用于进入到安全侧执行安全代码。 +cc_enclave_destroy: 用于销毁enclave安全上下文。 + +注意：这里调用的get_string函数与在edl中定义的get_string函数有些不同，这里的参数比edl中定义的多了前两个参数，分别是enclave安全上下文 +和retval参数。这是因为codegen（自动生成代码工具）通过edl生成的非安全侧代理函数，其声明在test_u.h中。 +如果在edl中定义的函数无返回值时，例如"public void get_string([out,size=32] char *buf);"则非安全侧代理函数为 +"res=get_string(context, buf)"(这里就不在有retval参数) + +#### 3.2 编写非安全侧CMakeLists.txt + + #set auto code prefix + set(PREFIX test) + #set host exec name + set(OUTPUT secgear_test) + #set host src code + set(SOURCE_FILE ${CMAKE_CURRENT_SOURCE_DIR}/main.c) + +设置预备的基础变量 + + #set auto code + if(CC_GP) + set(AUTO_FILES ${CMAKE_CURRENT_BINARY_DIR}/${PREFIX}_u.h ${CMAKE_CURRENT_BINARY_DIR}/${PREFIX}_u.c ${CMAKE_CURRENT_BINARY_DIR}/${PREFIX}_args.h) + add_custom_command(OUTPUT ${AUTO_FILES} + DEPENDS ${CURRENT_ROOT_PATH}/${EDL_FILE} + COMMAND ${CODEGEN} --${CODETYPE} --untrusted ${CURRENT_ROOT_PATH}/${EDL_FILE} --search-path ${LOCAL_ROOT_PATH}/inc/host_inc/gp) + endif() + + if(CC_SGX) + set(AUTO_FILES ${CMAKE_CURRENT_BINARY_DIR}/${PREFIX}_u.h ${CMAKE_CURRENT_BINARY_DIR}/${PREFIX}_u.c) + add_custom_command(OUTPUT ${AUTO_FILES} + DEPENDS ${CURRENT_ROOT_PATH}/${EDL_FILE} + COMMAND ${CODEGEN} --${CODETYPE} --untrusted ${CURRENT_ROOT_PATH}/${EDL_FILE} --search-path ${LOCAL_ROOT_PATH}/inc/host_inc/sgx --search-path ${SGXSDK}/include) + endif() + +设置使用代码辅助生成工具根据edl文件生成辅助代码。CODEGEN和CODETYPE等变量定义在CMakeList.txt文件.--search-path用于搜索在edl文件中导入依赖的其他edl文件。 +当使用SGX时，需要导入sgx提供的基础edl，因此这里指定了SGXSDK的patch "--search-path ${SGXSDK}/include)"。 + + set(CMAKE_C_FLAGS "-fstack-protector-all -W -Wall -Werror -Wextra -Werror=array-bounds -D_FORTIFY_SOURCE=2 -O2 -ftrapv -fPIE") + set(CMAKE_EXE_LINKER_FLAGS "-Wl,-z,relro -Wl,-z,now -Wl,-z,noexecstack") + +设置编译选项和链接选项 + + if(CC_GP) + if(${CMAKE_VERSION} VERSION_LESS "3.13.0") + link_directories(${SECGEAR_INSTALL_PATH}) + endif() + add_executable(${OUTPUT} ${SOURCE_FILE} ${AUTO_FILES}) + target_include_directories(${OUTPUT} PRIVATE + ${LOCAL_ROOT_PATH}/inc/host_inc + ${LOCAL_ROOT_PATH}/inc/host_inc/gp + ${CMAKE_CURRENT_BINARY_DIR}) + if(${CMAKE_VERSION} VERSION_GREATER_EQUAL "3.13.0") + target_link_directories(${OUTPUT} PRIVATE ${SECGEAR_INSTALL_PATH}) + endif() + endif() + +在iTrustee硬件环境上，设置头文件的搜索路径及编译生成非安全侧二进制文件。 + + if(CC_SGX) + if(${CMAKE_VERSION} VERSION_LESS "3.13.0") + link_directories(${SECGEAR_INSTALL_PATH}) + endif() + add_executable(${OUTPUT} ${SOURCE_FILE} ${AUTO_FILES}) + target_include_directories(${OUTPUT} PRIVATE + ${LOCAL_ROOT_PATH}/inc/host_inc + ${LOCAL_ROOT_PATH}/inc/host_inc/sgx + ${CMAKE_CURRENT_BINARY_DIR}) + if(${CMAKE_VERSION} VERSION_GREATER_EQUAL "3.13.0") + target_link_directories(${OUTPUT} PRIVATE ${SECGEAR_INSTALL_PATH}) + endif() + endif() + +在SGX硬件环境上，设置头文件的搜索路径及编译生成非安全侧二进制文件。 + + if(CC_SIM) + target_link_libraries(${OUTPUT} secgearsim) + else() + target_link_libraries(${OUTPUT} secgear) + endif() + set_target_properties(${OUTPUT} PROPERTIES SKIP_BUILD_RPATH TRUE) + if(CC_GP) + install(TARGETS ${OUTPUT} + RUNTIME + DESTINATION /vendor/bin/ + PERMISSIONS OWNER_EXECUTE OWNER_WRITE OWNER_READ) + endif() + if(CC_SGX) + install(TARGETS ${OUTPUT} + RUNTIME + DESTINATION ${CMAKE_BINARY_DIR}/bin/ + PERMISSIONS OWNER_EXECUTE OWNER_WRITE OWNER_READ) + endif() + + +设置secGear链接库，当指定模拟模式CC_SIM时链接libsecgearsim.so，否则链接libsecgear.so。 +在iTrustee硬件环境上需指定安装固定的安全白名单。 + +### 4 编写安全侧代码、CMakeList.txt及基础配置文件 + +#### 4.1 创建enclave目录 编写hello.c + + #include + #include + #include "test_t.h" + + #define TA_HELLO_WORLD "secGear hello world!" + #define BUF_MAX 32 + int get_string(char *buf) + { + strncpy(buf, TA_HELLO_WORLD, strlen(TA_HELLO_WORLD) + 1); + return 0; + } + +test_t.h：该头文件为自动生成代码工具codegen通过edl文件生成的头文件。该头文件命名为edl文件名加"_t"。 + +#### 4.2 编写CMakeList.txt文件 + + #set auto code prefix + set(PREFIX test) + #set sign key + set(PEM Enclave_private.pem) + +设置enclave签名私钥 + + #set sign tool + set(SIGN_TOOL ${LOCAL_ROOT_PATH}/tools/sign_tool/sign_tool.sh) + #set enclave src code + set(SOURCE_FILES ${CMAKE_CURRENT_SOURCE_DIR}/hello.c) + #set log level + set(PRINT_LEVEL 3) + add_definitions(-DPRINT_LEVEL=${PRINT_LEVEL}) + +设置签名工具已经安全侧打印日志level + + if(CC_GP) + #set signed output + set(OUTPUT ${UUID}.sec) + #set itrustee device key + set(DEVICEPEM ${CMAKE_CURRENT_SOURCE_DIR}/rsa_public_key_cloud.pem) + + set(WHITE_LIST_0 /vendor/bin/helloworld) + set(WHITE_LIST_1 /vendor/bin/secgear_test) + set(WHITE_LIST_OWNER root) + set(WHITELIST WHITE_LIST_0 WHITE_LIST_1) + + set(AUTO_FILES ${CMAKE_CURRENT_BINARY_DIR}/${PREFIX}_t.h ${CMAKE_CURRENT_BINARY_DIR}/${PREFIX}_t.c ${CMAKE_CURRENT_BINARY_DIR}/${PREFIX}_args.h) + add_custom_command(OUTPUT ${AUTO_FILES} + DEPENDS ${CURRENT_ROOT_PATH}/${EDL_FILE} + COMMAND ${CODEGEN} --${CODETYPE} --trusted ${CURRENT_ROOT_PATH}/${EDL_FILE} --search-path ${LOCAL_ROOT_PATH}/inc/host_inc/gp) + endif() + +WHITE_LIST_x：为设置iTrustee的二进制白名单，只有这里定义的白名单，在非安全侧的二进制才可以调用安全侧的动态库。上限为8个。 +WHITE_LIST_OWNER：为设置运行二进制的用户，只有该用户才可以调用安全侧动态库。 +DEVICEPEM：该公钥用来动态生成aes秘钥 +AUTO_FILES：由edl文件生成的安全侧二进制文件 + + if(CC_SGX) + set(OUTPUT enclave.signed.so) + set(AUTO_FILES ${CMAKE_CURRENT_BINARY_DIR}/${PREFIX}_t.h ${CMAKE_CURRENT_BINARY_DIR}/${PREFIX}_t.c) + add_custom_command(OUTPUT ${AUTO_FILES} + DEPENDS ${CURRENT_ROOT_PATH}/${EDL_FILE} + COMMAND ${CODEGEN} --${CODETYPE} --trusted ${CURRENT_ROOT_PATH}/${EDL_FILE} --search-path ${LOCAL_ROOT_PATH}/inc/host_inc/sgx --search-path ${SGXSDK}/include) + endif() + +设置自动生成代码及签名动态库。 + + set(COMMON_C_FLAGS "-W -Wall -Werror -fno-short-enums -fno-omit-frame-pointer -fstack-protector \ + -Wstack-protector --param ssp-buffer-size=4 -frecord-gcc-switches -Wextra -nostdinc -nodefaultlibs \ + -fno-peephole -fno-peephole2 -Wno-main -Wno-error=unused-parameter \ + -Wno-error=unused-but-set-variable -Wno-error=format-truncation=") + + set(COMMON_C_LINK_FLAGS "-Wl,-z,now -Wl,-z,relro -Wl,-z,noexecstack -Wl,-nostdlib -nodefaultlibs -nostartfiles") + +设置安全侧便编译选项和链接选项。由于安全侧和非安全侧不同，非安全侧的标准动态库不能被安全侧链接。例如："-nostdlib -nodefaultlibs -nostartfiles" + + + if(CC_GP) + configure_file("${CMAKE_CURRENT_SOURCE_DIR}/manifest.txt.in" "${CMAKE_CURRENT_SOURCE_DIR}/manifest.txt") + + set(CMAKE_C_FLAGS "${COMMON_C_FLAGS} -march=armv8-a ") + set(CMAKE_C_FLAGS_RELEASE "${CMAKE_C_FLAGS} -s -fPIC") + set(CMAKE_SHARED_LINKER_FLAGS "${COMMON_C_LINK_FLAGS} -Wl,-s") + + set(ITRUSTEE_TEEDIR ${iTrusteeSDK}/) + set(ITRUSTEE_LIBC ${iTrusteeSDK}/thirdparty/open_source/musl/libc) + + if(${CMAKE_VERSION} VERSION_LESS "3.13.0") + link_directories(${SECGEAR_INSTALL_PATH}) + endif() + + add_library(${PREFIX} SHARED ${SOURCE_FILES} ${AUTO_FILES}) + + target_include_directories( ${PREFIX} PRIVATE + ${CMAKE_CURRENT_BINARY_DIR} + ${LOCAL_ROOT_PATH}/inc/host_inc + ${LOCAL_ROOT_PATH}/inc/host_inc/gp + ${LOCAL_ROOT_PATH}/inc/enclave_inc + ${LOCAL_ROOT_PATH}/inc/enclave_inc/gp + ${ITRUSTEE_TEEDIR}/include/TA + ${ITRUSTEE_TEEDIR}/include/TA/huawei_ext + ${ITRUSTEE_LIBC}/arch/aarch64 + ${ITRUSTEE_LIBC}/ + ${ITRUSTEE_LIBC}/arch/arm/bits + ${ITRUSTEE_LIBC}/arch/generic + ${ITRUSTEE_LIBC}/arch/arm + ${LOCAL_ROOT_PATH}/inc/enclave_inc/gp/itrustee) + + if(${CMAKE_VERSION} VERSION_GREATER_EQUAL "3.13.0") + target_link_directories(${PREFIX} PRIVATE ${SECGEAR_INSTALL_PATH}) + endif() + + foreach(WHITE_LIST ${WHITELIST}) + add_definitions(-D${WHITE_LIST}="${${WHITE_LIST}}") + endforeach(WHITE_LIST) + add_definitions(-DWHITE_LIST_OWNER="${WHITE_LIST_OWNER}") + + target_link_libraries(${PREFIX} -lsecgear_tee) + + add_custom_command(TARGET ${PREFIX} + POST_BUILD + COMMAND bash ${SIGN_TOOL} -d sign -x trustzone -i lib${PREFIX}.so -m ${CMAKE_CURRENT_SOURCE_DIR}/manifest.txt + -e ${DEVICEPEM} -o ${CMAKE_CURRENT_BINARY_DIR}/${OUTPUT}) + + install(FILES ${CMAKE_CURRENT_BINARY_DIR}/${OUTPUT} + DESTINATION /data + PERMISSIONS OWNER_EXECUTE OWNER_WRITE OWNER_READ GROUP_READ GROUP_EXECUTE WORLD_READ WORLD_EXECUTE) + + endif() + +manifest.txt：itrustee安全侧配置文件，后面对该文件进行详解 +指定itrustee特性编译选项，设置引用头文件和动态库的路径。 +前面声明的白名单在这里定义。 +itrustee需要链接secgear_tee动态库，提供seal接口等。 + + if(CC_SGX) + set(SGX_DIR ${SGXSDK}) + set(CMAKE_C_FLAGS "${COMMON_C_FLAGS} -m64 -fvisibility=hidden") + set(CMAKE_C_FLAGS_RELEASE "${CMAKE_C_FLAGS} -s") + set(LINK_LIBRARY_PATH ${SGX_DIR}/lib64) + + if(CC_SIM) + set(Trts_Library_Name sgx_trts_sim) + set(Service_Library_Name sgx_tservice_sim) + else() + set(Trts_Library_Name sgx_trts) + set(Service_Library_Name sgx_tservice) + endif() + + set(Crypto_Library_Name sgx_tcrypto) + + set(CMAKE_SHARED_LINKER_FLAGS "${COMMON_C_LINK_FLAGS} -Wl,-z,defs -Wl,-pie -Bstatic -Bsymbolic -eenclave_entry \ + -Wl,--export-dynamic -Wl,--defsym,__ImageBase=0 -Wl,--gc-sections -Wl,--version-script=${CMAKE_CURRENT_SOURCE_DIR}/Enclave.lds") + + if(${CMAKE_VERSION} VERSION_LESS "3.13.0") + link_directories(${LINK_LIBRARY_PATH}) + endif() + + add_library(${PREFIX} SHARED ${SOURCE_FILES} ${AUTO_FILES}) + + target_include_directories(${PREFIX} PRIVATE + ${CMAKE_CURRENT_BINARY_DIR} + ${SGX_DIR}/include/tlibc + ${SGX_DIR}/include/libcxx + ${SGX_DIR}/include + ${LOCAL_ROOT_PATH}/inc/host_inc + ${LOCAL_ROOT_PATH}/inc/host_inc/sgx) + + if(${CMAKE_VERSION} VERSION_GREATER_EQUAL "3.13.0") + target_link_directories(${PREFIX} PRIVATE + ${LINK_LIBRARY_PATH}) + endif() + + target_link_libraries(${PREFIX} -Wl,--whole-archive ${Trts_Library_Name} -Wl,--no-whole-archive + -Wl,--start-group -lsgx_tstdc -lsgx_tcxx -l${Crypto_Library_Name} -l${Service_Library_Name} -Wl,--end-group) + add_custom_command(TARGET ${PREFIX} + POST_BUILD + COMMAND openssl genrsa -3 -out ${PEM} 3072 + COMMAND bash ${SIGN_TOOL} -d sign -x sgx -i lib${PREFIX}.so -k ${PEM} -o ${OUTPUT} -c ${CMAKE_CURRENT_SOURCE_DIR}/Enclave.config.xml) + endif() + + +在SGX硬件环境上，指定一些与sgx相关的编译选项、链接选项。链接动态库时有所不同，因为itrustee是一个具有更多功能的安全操作系统。提供如muslibc和openssl。在编译和链接itrustee时不用链接一些基本库，但是sgx没有OS概念。所以要在安全侧调用这些基本库的接口都要以静态的形式在sgxsdk中给出。例如"sgx_trts" + +有关更多详细信息，请参阅sgx示例的Makefile。最后用enclave配置文件完成签名，稍后将进行介绍。secGear尚不支持远程身份验证。 + +#### 4.3 编写安全侧配置文件 + +编写与sgx enclave相关的配置文件中Enclave.config.xml文件及enclave.lds文件与官方sgx配置相同。详情参阅官方开发文档。 + +编写itrustee enclave相关配置文件 +mainfest.txt.in:其中gpd.ta.appID 为动态生成uuid。其他配置参见itrustee开发文档。 + +rsa_public_key_cloud.pem文件请将其他examples的中的拷贝过来，这里的设备公钥用于使用临时生成的aes密钥用于对enclave动态库进行加密。 + +#### 5 构建 安装 + +进入开发目录：cd .../secGear/example/test/ +创建debug目录：mkdir debug && cd debug +cmake构建：cmake -DCMAKE_BUILD_TYPE=Debug -DCC_SGX=ON -DSGXSDK=sgx_sdk path .. && make && sudo make install （sgx硬件环境） + cmake -DCMAKE_BUILD_TYPE=Debug -DCC_GP=ON -DiTrusteeSDK=gp_sdk path .. && make && sudo make install （itrustee硬件环境） + +Log +--- +非安全侧日志记录： + +非安全侧是开发与普通开发环境一样，可使用通用打印日志接口。 + +安全侧日志记录： + +由于各架构安全能力不同的限制，为了像非安全侧一样开发使用日志打印功能，因为我们提供了PrintInfo接口将安全端日志记录到syslog系统中。 +相关配置文件为 conf/logrotate.d/secgear和conf/rsyslog.d/secgear.conf文件，安装时将安装在系统目录/etc/中。 + +注意：在itrustee上，需要include secgear_log.h头文件，但是sgx不需要，sgx通过ocall功能实现的，所以相关代码生成在辅助代码中。 +当文件安装成功后需要运行"systemctl restart rsyslog"使日志功能生效。 + +日志等级： + + PRINT_ERROR 0 + PRINT_WARNING 1 + PRINT_STRACE 2 + PRINT_DEBUG 3 + +使用ocall +--------- + +目前ocall仅在sgx平台支持，itrustee尚不支持。 + +seal, generate_random接口 +-------------------------------------- + +接口定义在secgear_dataseal.h、secgear_random.h中。 +注意：由于itrustee派生密钥的功能仍然不完善，因此目前还没有与密封相关的接口在itrustee平台上支持。 + +远程证明（尚不支持） +-------------------------------------- + +了解更多关于codegener +-------------------------------------- + +secGear引入EDL(Enclave Description Language)和中间代码辅助生成工具codegener。edl与intel sgx定义兼容。 + + +- [了解更多关于codegener](./docs/codegener.md) + +了解更多关于sign_tool +----------------------------- + + +- [了解更多关于签名工具](./docs/sign_tool.md) + +里程碑 +--------- +secGear \ No newline at end of file -- 2.27.0