secGear 开发指南

这里给出使用 secGear 开发一个 C 语言程序 helloworld 的例子，方便用户理解使用 secGear 开发应用程序。

目录结构说明

使用 secGear 开发的应用程序，遵循统一的目录结构如下：

  1. ├── helloworld
  2. │   ├── CMakeLists.txt
  3. │   ├── enclave
  4. │   │   ├── CMakeLists.txt
  5. │   │   ├── Enclave.config.xml
  6. │   │   ├── Enclave.lds
  7. │   │   ├── hello.c
  8. │   │   ├── manifest.txt.in
  9. │   │   └── rsa_public_key_cloud.pem
  10. │   ├── helloworld.edl
  11. │   └── host
  12. │       ├── CMakeLists.txt
  13. │       └── main.c

快速入门

  1. 创建程序工作目录 helloworld，并在 helloworld 目录下新建 enclave 和 host

  2. 编写 EDL（Enclave Definition Language）文件

    为了确保开发代码的一致性，secGear 提供了 secgear_urts.h 和 secgear_tstdc.edl 用于屏蔽底层 Intel SGX 和 ARM iTrustee 之间的差异。因此，使用到 C 语言函数库时，EDL 文件默认需要导入 secgear_urts.h 和 secgear_tstdc.edl。helloworld.edl 文件参考如下：

    1. enclave {
    2.     include "secgear_urts.h"
    3.     from "secgear_tstdc.edl" import *;
    4.     trusted {
    5.         public int get_string([out, size=32]char *buf);
    6.     };
    7. };

    说明：EDL 语法详细信息请参见 Intel SGX 开发指南中对应内容。

  3. 编写顶层文件 CMakeLists.txt

    编写顶层文件 CMakeLists.txt，置于 helloworld 工作目录下，用于配置编译时的处理器架构、所需的 EDL 文件等信息。

    其中，EDL_FILE 是 EDL 文件，需用户指定，例子中为 helloworld.edl。DPATH 是安全侧加载动态库，配置如例子中所示。

    1. cmake_minimum_required(VERSION 3.12 FATAL_ERROR)
    2. project(HelloWorld  C)
    3. set(CMAKE_C_STANDARD 99)
    4. set(CURRENT_ROOT_PATH ${CMAKE_CURRENT_SOURCE_DIR})
    5. set(EDL_FILE helloworld.edl)
    6. set(LOCAL_ROOT_PATH "$ENV{CC_SDK}")
    7.     set(SECGEAR_INSTALL_PATH /lib64/)
    8. if(CC_GP)
    9.     set(CODETYPE trustzone)
    10.     set(CODEGEN codegen_arm64)
    11.     execute_process(COMMAND uuidgen -r OUTPUT_VARIABLE UUID)
    12.     string(REPLACE "\n" "" UUID ${UUID})
    13.     add_definitions(-DPATH="/data/${UUID}.sec")
    14. endif()
    15. if(CC_SGX)
    16.     set(CODETYPE sgx)
    17.     set(CODEGEN codegen_x86_64)
    18.     add_definitions(-DPATH="${CMAKE_CURRENT_BINARY_DIR}/enclave/enclave.signed.so")
    19. endif()
    20. add_subdirectory(${CURRENT_ROOT_PATH}/enclave)
    21. add_subdirectory(${CURRENT_ROOT_PATH}/host)

  1. 编写非安全侧代码和 CMakeLists.txt

    4.1 编写 main.c

    编写非安全侧 main.c，置于 host目录。enclave.h 为 secGear 头文件，helloworld_u.h 为辅助代码生成工具生成的头文件。使用 cc_enclave_create 创建安全区 enclave 上下文，cc_enclave_destroy 销毁安全区上下文。 get_string 为 EDL 文件中定义 trusted 的安全侧函数，注意这里与 EDL 中定义的 get_string 有差别，多出两个参数 context 为安全区上下文，retval 为 EDL 中get_string 的返回值。 res 为 get_string 调用成功标志。

    1. #include <stdio.h>
    2. #include "enclave.h"
    3. #include "helloworld_u.h"
    5. #define BUF_LEN 32
    7. int main()
    8. {
    9.     int  retval = 0;
    10.     char *path = PATH;
    11.     char buf[BUF_LEN];
    12.     cc_enclave_t *context = NULL;
    13.     cc_enclave_result_t res;
    14.     res = cc_enclave_create(path, AUTO_ENCLAVE_TYPE, 0, SECGEAR_DEBUG_FLAG, NULL, 0, &context);
    15. ...
    17.     res = get_string(context, &retval, buf);
    18.     if (res != CC_SUCCESS || retval != (int)CC_SUCCESS) {
    19.         printf("Ecall enclave error\n");
    20.     } else {
    21.         printf("%s\n", buf);
    22.     }
    24.     if (context != NULL) {
    25.         res = cc_enclave_destroy(context);
    26.         ...
    27.     }
    28.     return res;
    29. }

    4.2 编写非安全侧 CMakeLists.txt

    1. # 设置编译环境变量
    2. #set auto code prefix
    3. set(PREFIX helloworld)
    4. #set host exec name
    5. set(OUTPUT secgear_helloworld)
    6. #set host src code
    7. set(SOURCE_FILE ${CMAKE_CURRENT_SOURCE_DIR}/main.c)
    9. # 使用代码生成工具生成辅助代码。CODEGEN 和 CODETYPE 变量也在顶层 CMakeLists.txt 中定义。--search-path 用于指定 helloword.edl 中导入依赖的其他 EDL 文件路径    
    10. #set auto code
    11. if(CC_GP)
    12.     set(AUTO_FILES  ${CMAKE_CURRENT_BINARY_DIR}/${PREFIX}_u.h ${CMAKE_CURRENT_BINARY_DIR}/${PREFIX}_u.c ${CMAKE_CURRENT_BINARY_DIR}/${PREFIX}_args.h)
    13.     add_custom_command(OUTPUT ${AUTO_FILES}
    14.     DEPENDS ${CURRENT_ROOT_PATH}/${EDL_FILE}
    15.     COMMAND ${CODEGEN} --${CODETYPE} --untrusted ${CURRENT_ROOT_PATH}/${EDL_FILE} --search-path ${LOCAL_ROOT_PATH}/inc/host_inc/gp)
    16. endif()
    18. if(CC_SGX)
    19.     set(AUTO_FILES  ${CMAKE_CURRENT_BINARY_DIR}/${PREFIX}_u.h ${CMAKE_CURRENT_BINARY_DIR}/${PREFIX}_u.c)
    20.     add_custom_command(OUTPUT ${AUTO_FILES}
    21.     DEPENDS ${CURRENT_ROOT_PATH}/${EDL_FILE}
    22.     COMMAND ${CODEGEN} --${CODETYPE} --untrusted ${CURRENT_ROOT_PATH}/${EDL_FILE} --search-path ${LOCAL_ROOT_PATH}/inc/host_inc/sgx  --search-path ${SGXSDK}/include)
    23. endif()
    25. # 设置编译选项和链接选项
    26. set(CMAKE_C_FLAGS "-fstack-protector-all -W -Wall -Werror -Wextra -Werror=array-bounds -D_FORTIFY_SOURCE=2 -O2 -ftrapv -fPIE")
    27. set(CMAKE_EXE_LINKER_FLAGS    "-Wl,-z,relro -Wl,-z,now -Wl,-z,noexecstack")
    29. # 编译链接引用目录
    30. if(CC_GP)
    31.     if(${CMAKE_VERSION} VERSION_LESS "3.13.0")
    32.         link_directories(${SECGEAR_INSTALL_PATH})
    33.     endif()
    34.     add_executable(${OUTPUT} ${SOURCE_FILE} ${AUTO_FILES})
    35.     target_include_directories(${OUTPUT} PRIVATE
    36.                     /usr/include/secGear/host_inc
    37.                     /usr/include/secGear/host_inc/gp
    38.                     ${CMAKE_CURRENT_BINARY_DIR})
    39.     if(${CMAKE_VERSION} VERSION_GREATER_EQUAL "3.13.0")
    40.         target_link_directories(${OUTPUT} PRIVATE ${SECGEAR_INSTALL_PATH})
    41.     endif()
    42.     target_link_libraries(${OUTPUT} secgear)
    43. endif()
    44. if(CC_SGX)
    45.     if(${CMAKE_VERSION} VERSION_LESS "3.13.0")
    46.         link_directories(${SECGEAR_INSTALL_PATH}  ${SGXSDK}/lib64)
    47.     endif()
    48.     set(SGX_MODE HW)
    49.     if(${SGX_MODE} STREQUAL HW)
    50.         set(Urts_Library_Name sgx_urts)
    51.     else()
    52.         set(Urts_Library_Name sgx_urts_sim)
    53.     endif()
    54.     add_executable(${OUTPUT} ${SOURCE_FILE} ${AUTO_FILES} ${LOCAL_ROOT_PATH}/src/host_src/sgx/sgx_log.c)
    55.     target_include_directories(${OUTPUT} PRIVATE
    56.                         /usr/include/secGear/host_inc
    57.                         /usr/include/secGear/host_inc/sgx
    58.                         ${CMAKE_CURRENT_BINARY_DIR})
    59.     if(${CMAKE_VERSION} VERSION_GREATER_EQUAL "3.13.0")
    60.         target_link_directories(${OUTPUT} PRIVATE ${SECGEAR_INSTALL_PATH}  ${SGXSDK}/lib64)
    61.     endif()
    62.     target_link_libraries(${OUTPUT} secgear ${Urts_Library_Name})
    63. endif()
    65. # 指定二进制安装目录
    66. set_target_properties(${OUTPUT} PROPERTIES SKIP_BUILD_RPATH TRUE)
    67. if(CC_GP)
    68.     install(TARGETS  ${OUTPUT}
    69.             RUNTIME
    70.             DESTINATION /vendor/bin/
    71.             PERMISSIONS OWNER_EXECUTE OWNER_WRITE OWNER_READ)
    72. endif()
    73. if(CC_SGX)
    74.     install(TARGETS  ${OUTPUT}
    75.             RUNTIME
    76.             DESTINATION ${CMAKE_BINARY_DIR}/bin/
    77.             PERMISSIONS OWNER_EXECUTE OWNER_WRITE OWNER_READ)
    78. endif()

  1. 编写安全侧代码、CMakeLists.txt 和配置文件，放在 enclave 目录

    5.1 编写安全侧代码 hello.c

    编写安全侧代码 hello.c，置于 enclave 目录。其中，helloworld_t.h 为辅助代码生成工具，通过 EDL 文件生成的安全侧头文件。

    1. #include <stdio.h>
    2. #include <string.h>
    3. #include "helloworld_t.h"
    5. #define TA_HELLO_WORLD        "secGear hello world!"
    6. #define BUF_MAX 32
    7. int get_string(char *buf)
    8. {
    9.     strncpy(buf, TA_HELLO_WORLD, strlen(TA_HELLO_WORLD) + 1);
    10.     return 0;
    11. }

    5.2 编写安全侧 CMakeLists.txt

    1. #set auto code prefix
    2. set(PREFIX helloworld)
    4. #set sign key
    5. set(PEM Enclave_private.pem)
    7. #set sign tool
    8. set(SIGN_TOOL ${LOCAL_ROOT_PATH}/tools/sign_tool/sign_tool.sh)
    10. #set enclave src code
    11. set(SOURCE_FILES ${CMAKE_CURRENT_SOURCE_DIR}/hello.c)
    13. #set log level
    14. set(PRINT_LEVEL 3)
    15. add_definitions(-DPRINT_LEVEL=${PRINT_LEVEL})
    17. # WHITE_LIS_X 设置 itrustee 白名单，只有这些路径的主机二进制文件可以调用此安全映像，并且最多可以配置 8 个列表路径。WHITE_LIST_OWNER 设置用户，此用户将应用于所有白名单路径。DEVICEPEM 公钥由itrustee 使用，并用于通过动态生成的 aes 密钥加密安全侧的安全动态库。
    18. if(CC_GP)
    19.     #set signed output
    20.     set(OUTPUT ${UUID}.sec)
    21.     #set itrustee device key
    22.     set(DEVICEPEM ${CMAKE_CURRENT_SOURCE_DIR}/rsa_public_key_cloud.pem)
    23.     #set whilelist. default: /vendor/bin/teec_hello
    24.     set(WHITE_LIST_0 /vendor/bin/helloworld)
    25.     set(WHITE_LIST_OWNER root)
    26.     set(WHITE_LIST_1 /vendor/bin/secgear_helloworld)
    27.     set(WHITELIST WHITE_LIST_0 WHITE_LIST_1)
    29.     set(AUTO_FILES  ${CMAKE_CURRENT_BINARY_DIR}/${PREFIX}_t.h ${CMAKE_CURRENT_BINARY_DIR}/${PREFIX}_t.c ${CMAKE_CURRENT_BINARY_DIR}/${PREFIX}_args.h)
    30.     add_custom_command(OUTPUT ${AUTO_FILES}
    31.     DEPENDS ${CURRENT_ROOT_PATH}/${EDL_FILE}
    32.     COMMAND ${CODEGEN} --${CODETYPE} --trusted ${CURRENT_ROOT_PATH}/${EDL_FILE} --search-path ${LOCAL_ROOT_PATH}/inc/host_inc/gp)
    33. endif()
    35. # SGX 安全侧动态库签名
    36. if(CC_SGX)
    37.     set(OUTPUT enclave.signed.so)
    38.     set(AUTO_FILES  ${CMAKE_CURRENT_BINARY_DIR}/${PREFIX}_t.h ${CMAKE_CURRENT_BINARY_DIR}/${PREFIX}_t.c)
    39.     add_custom_command(OUTPUT ${AUTO_FILES}
    40.     DEPENDS ${CURRENT_ROOT_PATH}/${EDL_FILE}
    41.     COMMAND ${CODEGEN} --${CODETYPE} --trusted ${CURRENT_ROOT_PATH}/${EDL_FILE} --search-path ${LOCAL_ROOT_PATH}/inc/host_inc/sgx --search-path ${SGXSDK}/include)
    42. endif()
    44. # 设置编译选项
    45. set(COMMON_C_FLAGS "-W -Wall -Werror  -fno-short-enums  -fno-omit-frame-pointer -fstack-protector \
    46.     -Wstack-protector --param ssp-buffer-size=4 -frecord-gcc-switches -Wextra -nostdinc -nodefaultlibs \
    47.     -fno-peephole -fno-peephole2 -Wno-main -Wno-error=unused-parameter \
    48.         -Wno-error=unused-but-set-variable -Wno-error=format-truncation=")
    50. set(COMMON_C_LINK_FLAGS "-Wl,-z,now -Wl,-z,relro -Wl,-z,noexecstack -Wl,-nostdlib -nodefaultlibs -nostartfiles")
    52. # itrustee 需生成 manifest.txt。指定 itrustee 编译选项和头文件、链接文件的搜索路径
    53. if(CC_GP)
    54.     configure_file("${CMAKE_CURRENT_SOURCE_DIR}/manifest.txt.in" "${CMAKE_CURRENT_SOURCE_DIR}/manifest.txt")
    56.     set(CMAKE_C_FLAGS "${COMMON_C_FLAGS}  -march=armv8-a ")
    57.     set(CMAKE_C_FLAGS_RELEASE "${CMAKE_C_FLAGS}  -s -fPIC")
    58.     set(CMAKE_SHARED_LINKER_FLAGS  "${COMMON_C_LINK_FLAGS} -Wl,-s")
    60.     set(ITRUSTEE_TEEDIR ${iTrusteeSDK}/)
    61.     set(ITRUSTEE_LIBC ${iTrusteeSDK}/thirdparty/open_source/musl/libc)
    63.     if(${CMAKE_VERSION} VERSION_LESS "3.13.0")
    64.         link_directories(${CMAKE_BINARY_DIR}/lib/)
    65.     endif()
    67.     add_library(${PREFIX} SHARED ${SOURCE_FILES} ${AUTO_FILES})
    69.     target_include_directories( ${PREFIX} PRIVATE
    70.     ${CMAKE_CURRENT_BINARY_DIR}
    71.     ${LOCAL_ROOT_PATH}/inc/host_inc
    72.     ${LOCAL_ROOT_PATH}/inc/host_inc/gp
    73.     ${LOCAL_ROOT_PATH}/inc/enclave_inc
    74.     ${LOCAL_ROOT_PATH}/inc/enclave_inc/gp
    75.     ${ITRUSTEE_TEEDIR}/include/TA
    76.     ${ITRUSTEE_TEEDIR}/include/TA/huawei_ext
    77.     ${ITRUSTEE_LIBC}/arch/aarch64
    78.     ${ITRUSTEE_LIBC}/
    79.     ${ITRUSTEE_LIBC}/arch/arm/bits
    80.     ${ITRUSTEE_LIBC}/arch/generic
    81.     ${ITRUSTEE_LIBC}/arch/arm
    82.     ${LOCAL_ROOT_PATH}/inc/enclave_inc/gp/itrustee)
    84.     if(${CMAKE_VERSION} VERSION_GREATER_EQUAL "3.13.0")
    85.         target_link_directories(${PREFIX} PRIVATE
    86.             ${CMAKE_BINARY_DIR}/lib/)
    87.     endif()
    89.     foreach(WHITE_LIST ${WHITELIST})
    90.         add_definitions(-D${WHITE_LIST}="${${WHITE_LIST}}")
    91.     endforeach(WHITE_LIST)
    92.     add_definitions(-DWHITE_LIST_OWNER="${WHITE_LIST_OWNER}")
    94.     target_link_libraries(${PREFIX} -lsecgear_tee)
    96.     add_custom_command(TARGET ${PREFIX}
    97.           POST_BUILD
    98.               COMMAND bash ${SIGN_TOOL} -d sign -x trustzone -i ${CMAKE_LIBRARY_OUTPUT_DIRECTORY}/lib${PREFIX}.so -m ${CMAKE_CURRENT_SOURCE_DIR}/manifest.txt 
    99.                   -e ${DEVICEPEM} -o ${CMAKE_LIBRARY_OUTPUT_DIRECTORY}/${OUTPUT})
    101.     install(FILES ${CMAKE_LIBRARY_OUTPUT_DIRECTORY}/${OUTPUT}  
    102.         DESTINATION /data
    103.         PERMISSIONS OWNER_EXECUTE OWNER_WRITE OWNER_READ GROUP_READ GROUP_EXECUTE  WORLD_READ  WORLD_EXECUTE)
    105. endif()
    107. if(CC_SGX)
    108.     set(SGX_DIR ${SGXSDK})
    109.     set(CMAKE_C_FLAGS "${COMMON_C_FLAGS} -m64 -fvisibility=hidden")
    110.     set(CMAKE_C_FLAGS_RELEASE "${CMAKE_C_FLAGS}  -s")
    111.     set(LINK_LIBRARY_PATH ${SGX_DIR}/lib64)
    113.     if(CC_SIM)
    114.         set(Trts_Library_Name sgx_trts_sim)
    115.         set(Service_Library_Name sgx_tservice_sim)
    116.     else()
    117.         set(Trts_Library_Name sgx_trts)
    118.         set(Service_Library_Name sgx_tservice)
    119.     endif()
    121.     set(Crypto_Library_Name sgx_tcrypto)
    123.     set(CMAKE_SHARED_LINKER_FLAGS  "${COMMON_C_LINK_FLAGS} -Wl,-z,defs -Wl,-pie -Bstatic -Bsymbolic -eenclave_entry \
    124.     -Wl,--export-dynamic -Wl,--defsym,__ImageBase=0 -Wl,--gc-sections -Wl,--version-script=${CMAKE_CURRENT_SOURCE_DIR}/Enclave.lds")
    126.     if(${CMAKE_VERSION} VERSION_LESS "3.13.0") 
    127.         link_directories(${LINK_LIBRARY_PATH})
    128.     endif()
    130.     add_library(${PREFIX}  SHARED ${SOURCE_FILES} ${AUTO_FILES})
    132.     target_include_directories(${PREFIX} PRIVATE
    133.         ${CMAKE_CURRENT_BINARY_DIR}
    134.         ${SGX_DIR}/include/tlibc
    135.         ${SGX_DIR}/include/libcxx
    136.         ${SGX_DIR}/include
    137.         ${LOCAL_ROOT_PATH}/inc/host_inc
    138.         ${LOCAL_ROOT_PATH}/inc/host_inc/sgx)
    140.     if(${CMAKE_VERSION} VERSION_GREATER_EQUAL "3.13.0") 
    141.         target_link_directories(${PREFIX} PRIVATE
    142.             ${LINK_LIBRARY_PATH})
    143.     endif()
    145.     target_link_libraries(${PREFIX}  -Wl,--whole-archive ${Trts_Library_Name} -Wl,--no-whole-archive 
    146.             -Wl,--start-group -lsgx_tstdc -lsgx_tcxx -l${Crypto_Library_Name} -l${Service_Library_Name}   -Wl,--end-group)
    147.     add_custom_command(TARGET ${PREFIX} 
    148.     POST_BUILD
    149.     COMMAND umask 0177
    150.     COMMAND openssl genrsa -3 -out ${PEM} 3072
    151.     COMMAND bash ${SIGN_TOOL} -d sign -x sgx -i ${CMAKE_LIBRARY_OUTPUT_DIRECTORY}/lib${PREFIX}.so -k ${PEM} -o ${OUTPUT} -c ${CMAKE_CURRENT_SOURCE_DIR}/Enclave.config.xml)
    152. endif()
    154. set_target_properties(${PREFIX} PROPERTIES SKIP_BUILD_RPATH TRUE)

  1. 编写配置文件

    针对使用 Intel SGX 的 x86_64 处理器架构，请编写 Enclave.config.xml 和 Enclave.lds 文件，置于安全侧 enclave 目录。文件的具体配置格式请参见 SGX 官方文档。

    Enclave.config.xml 参考：

    ```c 0 0 0x40000 0x100000 10

    1 
  1.  <DisableDebug>0</DisableDebug>
  2.  <MiscSelect>0</MiscSelect>
  3.  <MiscMask>0xFFFFFFFF</MiscMask>

  2.    Enclave.lds 参考：
  4.    ```c
  5.    enclave.so
  6.    {
  7.        global:
  8.            g_global_data_sim;
  9.            g_global_data;
  10.            enclave_entry;
  11.            g_peak_heap_used;
  12.        local:
  13.            *;
  14.    };

将设备公钥文件 rsa_public_key_cloud.pem 复制到 enclave 目录。此处的设备公钥用于使用临时生成的 aes 密钥对安全区动态库进行加密。

说明：rsa_public_key_cloud.pem 文件下载路径：https://gitee.com/openeuler/secGear/blob/master/examples/helloworld/enclave/rsa_public_key_cloud.pem

  1. 编译程序

    SGX 版本编译命令如下，编译后将生成可执行程序 secgear_helloworld

    1. cmake -DCMAKE_BUILD_TYPE=debug -DCC_SGX=ON -DSGXSDK="PATH"  ./ && make

  1. 执行程序

    1. $ ./secgear_helloworld
    2. Create secgear enclave
    3. secgear hello world!