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（Encalve 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 开发指南中对应内容。

  1. 编写顶层文件 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 参考：

  1.    <EnclaveConfiguration>
  2.      <ProdID>0</ProdID>
  3.      <ISVSVN>0</ISVSVN>
  4.      <StackMaxSize>0x40000</StackMaxSize>
  5.      <HeapMaxSize>0x100000</HeapMaxSize>
  6.      <TCSNum>10</TCSNum>
  7.      <TCSPolicy>1</TCSPolicy>
  8.      <!-- Recommend changing 'DisableDebug' to 1 to make the enclave undebuggable for enclave release -->
  9.      <DisableDebug>0</DisableDebug>
  10.      <MiscSelect>0</MiscSelect>
  11.      <MiscMask>0xFFFFFFFF</MiscMask>
  12.    </EnclaveConfiguration>

Enclave.lds 参考：

  1.    enclave.so
  2.    {
  3.        global:
  4.            g_global_data_sim;
  5.            g_global_data;
  6.            enclave_entry;
  7.            g_peak_heap_used;
  8.        local:
  9.            *;
  10.    };

将设备公钥文件 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!