接口说明

secGear 机密计算统一开发框架提供了屏蔽TEE SDK差异的基础接口，还提供了switchless、远程证明、安全通道等高级特性。

基础接口

cc_enclave_create

创建 enclave 接口

功能：

初始化接口，函数根据不同 type，调用不同的 TEE 创建函数，完成不同 TEE 方案关于 enclave 上下文初始化，由非安全侧调用。

说明：

由于 Intel SGX 限制，多线程并发调用 cc_enclave_create 时存在内存映射的竞争关系，会导致创建 enclave 概率性失败。所以编码时要避免线程并发调用 cc_enclave_create。

函数声明：

cc_enclave_result_t cc_enclave_create(
            const char* path, 
            enclave_type_t type, 
            uint32_t version,
            uint32_t flags,
            const enclave_features_t* features,
            uint32_t features_count,
            cc_enclave_t  ** enclave);

参数：

• path：入参，要加载的 enclave 路径
• type：入参，用来指定 TEE 解决方案， 如 SGX_ENCLAVE_TYPE、GP_ENCLAVE_TYPE、AUTO_ENCLAVE_TYPE
• version：入参，指定的 enclave engine 的版本，目前只有一个版本，取值为 0。
• flags：入参，标志位，说明这个 enclave 运行状态，例如调试状态 SECGEAR_DEBUG_FLAG、模拟状态 SECGEAR_SIMULATE_FLAG（目前不支持）
• features：入参，用于设置一些关于 enclave 支持的特性，例如 SGX 的 PCL、 switchless 等。目前不支持，请设置为 NULL
• features_count：入参，入参 features 特性结构体的数量。目前不支持，请设置为 0
• enclave：出参，创建的 enclave 上下文

返回值：

• CE_SUCCESS：认证信息验证成功
• CE_ERROR_INVALID_PARAMETER：输入参数有误
• CE_ERROR_OUT_OF_MEMORY：无可用内存
• CC_FAIL：通用错误
• CC_ERROR_UNEXPECTED：不可预期错误
• CC_ERROR_ENCLAVE_MAXIMUM：单个 app 创建的 enclave 数量达到最大
• CC_ERROR_INVALID_PATH：安全二进制路径无效
• CC_ERROR_NO_FIND_REGFUNC：enclave 引擎搜索失败

cc_enclave_destroy

销毁 enclave 接口

功能：

调用不同 TEE 的退出函数，释放已经创建的 enclave 实体，由非安全侧调用。

函数声明：

cc_enclave_result_t cc_enclave_destroy (cc_enclave_t ** enclave)；

参数：

• enclave：入参，已经创建 enclave 的上下文

返回值：

• CE_SUCCESS：认证信息验证成功
• CE_ERROR_INVALID_PARAMETER：输入参数有误
• CE_ERROR_OUT_OF_MEMORY：无可用内存
• CC_ERROR_NO_FIND_UNREGFUNC：enclave引擎搜索失败
• CC_FAIL：通用错误
• CC_ERROR_UNEXPECTED：不可预期错误

cc_malloc_shared_memory

创建共享内存

功能：

开启switchless特性后，创建安全环境与非安全环境可同时访问的共享内存，由非安全侧调用。

函数声明：

void *cc_malloc_shared_memory(cc_enclave_t *enclave, size_t size);

参数：

• enclave：入参，安全环境上下文句柄。因不同平台共享内存模型不同，同时为了保持接口跨平台一致性，该参数仅在ARM平台被使用，SGX平台该入参会被忽略
• size：入参，共享内存大小

返回值：

• NULL：共享内存申请失败
• 其他：为创建的共享内存的首地址

cc_free_shared_memory

释放共享内存

功能：

开启switchless特性后，释放共享内存，由非安全侧调用。

函数声明：

cc_enclave_result_t cc_free_shared_memory(cc_enclave_t *enclave, void *ptr);

参数：

• enclave：入参，安全环境上下文句柄。因不同平台共享内存模型不同，同时为了保持接口跨平台一致性，该参数仅在ARM平台被使用（该参数必须与调用cc_malloc_shared_memory接口时传入的enclave保持一致），SGX平台该入参会被忽略
• ptr：入参，cc_malloc_shared_memory接口返回的共享内存地址

返回值：

• CC_ERROR_BAD_PARAMETERS：入参非法
• CC_ERROR_INVALID_HANDLE：无效enclave或者传入的enclave与ptr所对应的enclave不匹配（仅在ARM平台生效，SGX平台会忽略enclave，故不会对enclave进行检查）
• CC_ERROR_NOT_IMPLEMENTED：该接口未实现
• CC_ERROR_SHARED_MEMORY_START_ADDR_INVALID：ptr不是cc_malloc_shared_memory接口返回的共享内存地址（仅在ARM平台生效）
• CC_ERROR_OUT_OF_MEMORY：内存不足（仅在ARM平台生效）
• CC_FAIL：一般性错误
• CC_SUCCESS：成功

cc_enclave_generate_random

随机数生成

功能：

用于在安全侧生成密码安全的随机数。

函数声明：

cc_enclave_result_t cc_enclave_generate_random(void *buffer, size_t size)

参数：

• buffer：入参，生成随机数的缓冲区
• size：入参，缓冲区的长度

返回值：

• CE_OK：认证信息验证成功
• CE_ERROR_INVALID_PARAMETER：输入参数有误
• CE_ERROR_OUT_OF_MEMORY：无可用内存

cc_enclave_seal_data

数据持久化

功能：

用于加密 enclave 内部数据，使数据可以在 enclave 外部持久化存储，由安全侧调用。

函数声明：

cc_enclave_result_t cc_enclave_seal_data(
            uint8_t *seal_data, 
            uint32_t seal_data_len,
            cc_enclave_sealed_data_t *sealed_data, 
            uint32_t sealed_data_len,
            uint8_t *additional_text, 
            uint32_t additional_text_len)

参数：

• seal_data：入参，需要加密的数据
• seal_data_len：入参，需要加密数据的长度
• sealed_data：出参，加密后的数据处理句柄
• sealed_data_len：出参，加密后的密文长度
• additional_text：入参，加密所需的附加消息
• additional_text_len：入参，附加消息长度

返回值：

• CE_SUCCESS：数据加密成功
• CE_ERROR_INVALID_PARAMETER：输入参数有误
• CE_ERROR_OUT_OF_MEMORY：无可用内存
• CC_ERROR_SHORT_BUFFER：传入的buffer过小
• CC_ERROR_GENERIC：底层硬件通用错误

cc_enclave_unseal_data

数据解密

功能：

用于解密 enclave 密封过的数据，用于将外部持久化数据重新导回 enclave 环境中，由安全侧调用。

函数声明：

cc_enclave_result_t cc_enclave_unseal_data(
            cc_enclave_sealed_data_t *sealed_data, 
            uint8_t *decrypted_data, 
            uint32_t *decrypted_data_len,    
            uint8_t *additional_text, 
            uint32_t *additional_text_len)

参数：

• sealed_data：入参，已加密数据的句柄
• decrypted_data：出参，解密之后的密文数据buffer
• decrypted_data_len：出参，解密后密文长度
• additional_text：出参，解密后附加消息
• additional_text_len：出参，解密后附加消息长度

返回值：

• CE_SUCCESS：数据解密成功
• CE_ERROR_INVALID_PARAMETER：输入参数有误
• CE_ERROR_OUT_OF_MEMORY：无可用内存
• CC_ERROR_SHORT_BUFFER：传入的buffer过小
• CC_ERROR_GENERIC：底层硬件通用错误

cc_enclave_get_sealed_data_size

获取加密数据的大小

功能：

用于 sealed_data 数据的大小，主要用于分配解密后的数据空间，由安全侧调用。

函数声明：

uint32_t cc_enclave_get_sealed_data_size(const uint32_t add_len, const uint32_t seal_data_len);

参数：

• add_len：入参，附加消息长度
• seal_data_len：入参，需要加密数据的长度

返回值：

• UINT32_MAX：参数错误或函数执行错误
• others：函数执行成功，返回值为当前 sealed_data 结构的大小

cc_enclave_get_encrypted_text_size

获取加密消息的长度

功能：

获取加密数数据中加密消息的长度，由安全侧调用。

函数声明：

uint32_t cc_enclave_get_encrypted_text_size(const cc_enclave_sealed_data_t *sealed_data);

参数：

• sealed_data：入参，加密数据的句柄

返回值：

• UINT32_MAX：参数错误或函数执行错误
• others：函数执行成功，返回值为当前 sealed_data 中加密消息的长度

cc_enclave_get_add_text_size

获取附加消息的长度

功能：

获取加密数数据中附加消息的长度，由安全侧调用。

函数声明：

uint32_t cc_enclave_get_add_text_size(const cc_enclave_sealed_data_t *sealed_data);

参数：

• sealed_data：入参，加密数据的句柄

返回值：

• UINT32_MAX：参数错误或函数执行错误
• others：函数执行成功，返回值为当前sealed_data中附加消息的长度

cc_enclave_memory_in_enclave

安全内存检查

功能：

用于校验指定长度的内存地址是否都属于安全侧内存，由安全侧调用。

函数声明：

bool cc_enclave_memory_in_enclave(const void *addr, size_t size)

参数：

• addr：入参，指定需要校验的内存地址
• size：入参，自内存地址起需要校验的长度

返回值：

• true：指定区域内存都在安全区范围内
• false：指定区域的内存有部分或者全部不在安全范围内

cc_enclave_memory_out_enclave

安全内存检查

功能：

用于校验指定长度的内存地址是否都属于非安全侧内存，由安全侧调用。

函数声明：

bool cc_enclave_memory_out_enclave(const void *addr, size_t size)

参数：

• addr：入参，指定需要校验的内存地址
• size：入参，自内存地址起需要校验的长度

返回值：

• true：指定区域内存都在非安全区
• false：指定区域的内存有部分或者全部在安全区

PrintInfo

消息打印

功能：

用于安全侧日志的打印，本接口输出安全侧用户想打印的信息，输入日志保存在非安全侧'/var/log/secgear/secgear.log'中。

函数声明：

void PrintInfo(int level, const char *fmt, ...);

参数：

• level：入参，日志打印等级，可选项为PRINT_ERROR, PRINT_WARNING, PRINT_STRACE, PRINT_DEBUG
• fmt: 入参，需要输出的字符串

返回值：

• 无

switchless

switchless 是对普通 ecall（REE调用TEE的接口） 的性能优化特性，有两级开关，可以通过如下方法开启。

switchless 总开关

通过 cc_enclave_create 函数的 enclave_features_t 参数配置switchless特性，开启总开关，详见switchless样例。 switchless特性的配置字段介绍如下，

  typedef struct {
  	uint32_t num_uworkers;
  	uint32_t num_tworkers;
  	uint32_t switchless_calls_pool_size;
  	uint32_t retries_before_fallback;
  	uint32_t retries_before_sleep;
  	uint32_t parameter_num;
  	uint32_t workers_policy;
  	uint32_t rollback_to_common;
  } cc_sl_config_t;

ecall 函数的开关

通过 transition_using_threads 关键字开启对应 ecall 的 switchless。

enclave {
    include "secgear_urts.h"
    from "secgear_tstdc.edl" import *;
    from "secgear_tswitchless.edl" import *;
    trusted {
        public int get_string([out, size=32]char *buf);
        public int get_string_switchless([out, size=32]char *buf) transition_using_threads;
    };
};

远程证明

远程证明提供接口如下, 调用方式参考远程证明样例和本地证明样例。

安全通道

安全通道以lib库方式提供，分为客户端、服务端host、服务端enclave三部分，分别由业务程序的客户端、服务端CA、服务端TA调用。

接口列表

注意事项

• 安全通道仅封装密钥协商过程、加解密接口，不建立网络连接，协商过程复用业务的网络连接。其中客户端和服务端的网络连接由业务建立和维护，在安全通道客户端和服务端初始化时传入消息发送钩子函数和网络连接指针。
• 客户端和服务端网络消息接收函数的读buffer长度要预留足够大，能够容纳 12320 字节的安全通道初始化消息。 详见安全通道样例。

开发工具

secGear 提供了一套工具集，方便用户开发应用程序。本章介绍相关工具及其使用方法。

代码生成工具

简介

secGear codegen 用于解析 EDL 文件生成中间 C 代码，即辅助生成安全测与非安全侧文件互相调用的代码。

secGear codegen 定义的 EDL 文件格式与 intel SGX SDK edger8r 相同，但是不支持 Intel 的完整语法定义：

• 只能在方法中使用 public，不加 public 的函数声明默认为 private
• 不支持从非安全侧到安全侧，以及安全侧到非安全侧的 Switchless Calls
• OCALL（Outside call) 不支持部分调用模式（如 cdecl，stdcall，fastcall）

EDL 文件语法为类 C 语言语法，这里主要描述与 C 语言的差异部分：

使用说明

命令格式

codegen 的命令格式如下：

codegen < --trustzone | --sgx > [--trusted-dir | --untrusted-dir | --trusted | --untrusted ] edlfile

参数说明

各参数含义如下：

示例

• 转译 helloworld.edl ，在 enclave-directory 下生成安全侧辅助代码，host-directory 下生成非安全辅助代码的命令示例如下：

$ codegen --sgx --trusted-dir enclave-directory --untrusted-dir host-directory helloworld.edl

• 转译 helloworld.edl ，在当前目录生成安全侧辅助代码，不生成非安全辅助代码的命令示例如下：

$ codegen --sgx --trusted helloworld.edl

• 转译 helloworld.edl ，在当前目录生成非安全侧辅助代码，不生成安全辅助代码的命令示例如下：

$ codegen --sgx --untrusted  helloworld.edl

• 转译 helloworld.edl ，在 当前目录生成安全侧和非安全侧辅助代码的命令示例如下：

$ codegen --sgx helloworld.edl

签名工具

简介

secGear sign_tool 是一款命令行工具，包含编译工具链和签名工具，用于 enclave 签名。sign_tool 有两种签名形式：

• 单步签名：仅适用于 debug 调试模式
• 两步签名：商用场景。需要从第三方平台或者独立的安全设备获取签名私钥，对 envlave 进行签名

使用指导

命令格式

sign_tool 包含 sign 指令（对 enclave 进行签名）和 digest 指令（生成摘要值）。命令格式为：

sign_tool.sh -d [sign | digest] -x -i -p -s [OPTIONS] –o

参数说明

单步签名

enclave 类型为 SGX，给 test.enclave 签名，输出签名文件 signed.enclave 的示例如下：

$ sign_tool.sh –d sign –x sgx –i test.enclave -k private_test.pem –o signed.enclave

两步签名

以 SGX 为例，两步签名的操作步骤如下：

1. 生成摘要值

   使用 sign_tool 签名，生成摘要值 digest.data 和临时中间文件 signdata（该文件在生成签名文件时使用，并在签名后自动删除）。参考命令如下：

   $ sign_tool.sh –d digest –x sgx –i input –o digest.data
   

2. 将 digest.data 发送至签名机构或平台，并获取对应签名。

3. 使用获取的签名生成签名后的动态库 signed.enclave。

   $ sign_tool.sh –d sign –x sgx–i input  –p pub.pem –s signature –o signed.enclave
   

说明：为发布 Intel SGX 支持的正式版本应用，需要申请 Intel 白名单。流程请参考 Intel 文档：https://software.intel.com/content/www/us/en/develop/download/overview-on-signing-and-whitelisting-for-intel-software-guard-extensions-enclaves.html

安全应用开发指南

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

下载样例

git clone https://gitee.com/openeuler/secGear.git

目录结构说明

cd examples/helloworld

#目录结构如下
├── helloworld
│   ├── CMakeLists.txt
│   ├── enclave
│   │   ├── CMakeLists.txt
│   │   ├── Enclave.config.xml
│   │   ├── Enclave.lds
│   │   ├── hello.c
│   │   ├── manifest.txt
│   │   └── config_cloud.ini
│   ├── helloworld.edl
│   └── host
│       ├── CMakeLists.txt
│       └── main.c

代码主体分为三块：

• 非安全侧程序（main.c）
• 非安全侧与安全侧调用接口头文件（helloworld.edl）
• 安全侧程序（hello.c）

准备工作

除以上三部分主体代码外，还有编译工程文件（CMakeLists.txt）、开发者证书（SGX的Enclave.config.xml/Enclave.lds，鲲鹏的manifest.txt/config_cloud.ini）。

说明:

• 鲲鹏开发者证书需要向华为业务负责人申请开发者证书。
• SGX以Debug模式调试，暂时不用申请。如需正式商用并且用intel的远程证明服务，需要向Intel申请License。

申请成功后会得到开发者证书相关文件，需要放置到代码目录相应位置。

开发步骤

基于secGear做机密计算应用拆分改造，类似于独立功能模块提取，识别敏感数据处理逻辑，提取成独立的lib库，部署在可信执行环境中，对非安全侧提供的接口定义在EDL文件中。

开发步骤如下图所示：

1. 开发非安全侧main函数及接口，管理enclave并调用安全侧函数。
2. 开发EDL文件（类似C语言头文件定义非安全侧与安全侧交互接口）
3. 开发安全侧接口实现
4. 调用代码生成工具，根据EDL自动生成非安全侧与安全侧交互源码，并分别编译到非安全侧与安全侧二进制文件中，非安全侧逻辑直接调用安全侧对应的接口即可，无需关心自动的生成的交互代码，降低开发成本。
5. 调用签名工具对安全侧二进制签名，实现安全侧程序可信启动。

编译运行

ARM环境

// clone secGear repository
git clone https://gitee.com/openeuler/secGear.git

// build secGear and examples
cd secGear
source environment
mkdir debug && cd debug && cmake -DENCLAVE=GP .. && make && sudo make install

// run helloworld
/vendor/bin/secgear_helloworld

x86环境

// clone secGear repository
git clone https://gitee.com/openeuler/secGear.git

// build secGear and examples
cd secGear
source /opt/intel/sgxsdk/environment && source environment
mkdir debug && cd debug && cmake .. && make && sudo make install

// run helloworld
./examples/helloworld/host/secgear_helloworld