文章目录
参考文献
- helloworld README 文档
- API reference and supported libraries
- Build and Sign an Enclave
- Build options for using Open Enclave SDK libraries
- Open Enclave SDK CMake Package
- tee-internal-core-api-specification
- Open Enclave edger8r
helloworld 代码解读
代码运行环境： windows 10
代码目录结构
调用流程
1. 首先定义 host 和 enclave 之间相互调用的函数
定义见 helloworld.edl
enclave {
from "openenclave/edl/syscall.edl" import *;
from "platform.edl" import *;
trusted {
public void enclave_helloworld();
};
untrusted {
void host_helloworld();
};
};
其中 public void enclave_helloworld() 是 enclave 向 host 暴露的接口。 void host_helloworld(); 是 enclave 向 host 返回数据的回调函数。
2. 实现 enclave 端的 enclave_helloworld() 逻辑
见 helloworld/enclave/enc.c 中代码。
// 导入 enclave 库， 完整的 enclave 库见【API reference and supported libraries】
// 此示例中包含 stdio.h 头文件，因为我们调用 CRT 函数 fprintf 在屏幕上打印消息。
// 但是，此函数依赖于内核在屏幕上打印消息，因此此代码无法在安全区本身内执行。
// 相反，这个函数将调用转交给主机，以代表enclave执行调用。
#include <stdio.h>
// 导入在构建过程中生成的受信任的helloworld头文件。
// 该文件是通过针对 helloworld.edl 文件调用sdk工具oeedger8r生成的。
#include "helloworld_t.h"
// 这是主机调用的函数。它在 enclave 中打印一条信息，然后再回调到主机中打印一条信息。
void enclave_helloworld()
{
// 打印一个来自 enclave 的信息。
// 注意，不是直接调用fprintf，而是将调用转交到host，并从那里调用fprintf。
// 这是因为fprintf函数不是enclave的一部分，因为它需要内核的支持。
fprintf(stdout, "Hello world from the enclave\n");
// Call back into the host
oe_result_t result = host_helloworld();
if (result != OE_OK) // 验证是否成功
{
fprintf(stderr, "Call to host_helloworld failed: result=%u (%s)\n", result,
oe_result_str(result));
}
}
3. 实现 host 端的 host_helloworld() 逻辑
代码见 helloworld/host/host.c。
// 包括本文件中使用的Open Enclave函数的头，（例如oe_terminate_enclave）。
#include <openenclave/host.h>
// 包括标准的CRT库。与 enclave 实现不同的是，enclave 实现包括一个特殊的 enclave 版本的 stdio 库，该库将API传递给主机。
// 而 host 不受保护，所以使用所有正常的C库和函数。
#include <stdio.h>
// Include the untrusted helloworld header that is generated
// during the build. This file is generated by calling the
// sdk tool oeedger8r against the helloworld.edl file.
#include "helloworld_u.h"
// 这是 enclave 调用的实际的 host 函数。该函数在 helloworld.edl 文件中定义，并在这里实现。
void host_helloworld()
{
fprintf(stdout, "Enclave called into host to print: Hello World!\n");
}
// host 是创建和调用enclave的应用程序，所以host是一个正常的C可执行文件，有一个标准的主函数。
int main(int argc, const char* argv[])
{
oe_result_t result;
int ret = 1;
oe_enclave_t* enclave = NULL;
if (argc != 2)
{
fprintf(stderr, "Usage: %s enclave_image_path\n", argv[0]);
goto exit;
}
// 1. 通过调用oe_create_helloworld_enclave来创建一个enclave，该enclave的签名库文件的路径刚好作为第一个参数传递给启动应用程序。
// oe_create_helloworld_enclave函数是由oeedger8r生成的，默认名字方式是oe_create_[xxxx]_enclave，其中xxx是 EDL文件的名称。该函数创建了一个enclave 镜像供主机进程使用。
// 该函数功能包括：
// (1). 分配 enclave 地址空间。
// (2). 从enclave 库文件中加载 enclave 代码和数据到它的地址空间。
// (3). 设置enclave环境，包括enclave堆和每个enclave线程的数据结构。
// (4). 测量产生的enclave身份，并确保它与enclave签名相匹配。
// (5). 初始化 "enclave"，使其准备好从主机上调用。
// 2. OE_ENCLAVE_FLAG_DEBUG标志允许在没有签署enclave二进制的情况下创建enclave。
// 它还允许开发人员调试进程并获得对enclave内存的访问。这意味着**不要发送带有OE_ENCLAVE_FLAG_DEBUG的代码**，因为它是不安全的。它所提供的是更容易开发你的enclave的能力。
// 在你运送代码之前，你需要为enclave可执行文件准备一个适当的代码签名故事。
// 一些较新的英特尔SGX平台允许使用自签名的证书，但一些较老的英特尔SGX平台要求英特尔对你的enclave可执行文件进行签名。
// 3. 在成功创建后，该函数会返回一个不透明的enclave句柄，用于今后对enclae的任何操作。
result = oe_create_helloworld_enclave(
argv[1], OE_ENCLAVE_TYPE_AUTO, OE_ENCLAVE_FLAG_DEBUG, NULL, 0, &enclave);
if (result != OE_OK)
{
fprintf(stderr, "oe_create_helloworld_enclave(): result=%u (%s)\n", result, oe_result_str(result));
goto exit;
}
// 调用了从helloworld.edl文件中生成的主机marshaling函数。它处理任何参数的代码，并在enclave本身中调用该函数。
// 在这个例子中，没有任何实际的函数参数。
// 同时，尽管函数enclave_helloworld()是一个无效的返回类型，但marshaling代码本身可能会失败，所以需要验证与之相关的返回代码。
// 如果enclave_helloworld()要返回一个值，这将作为一个out参数传回来。
// Open Enclave处理host模式和enclave模式之间的所有上下文切换。
result = enclave_helloworld(enclave);
if (result != OE_OK)
{
fprintf(stderr, "calling into enclave_helloworld failed: result=%u (%s)\n", result, oe_result_str(result));
goto exit;
}
ret = 0;
exit:
// 终止enclave并释放与之相关的所有资源。
if (enclave)
oe_terminate_enclave(enclave);
return ret;
}
4. 编译 enclave 应用程序
4.1 使用 oeedger8r 编译 helloworld.edl 的 untrusted 部分，生成 host 端的相关文件
oeedger8r --search-path c:\openenclave\include --search-path c:\openenclave\include\openenclave\edl\sgx ..\helloworld.edl --untrusted
| file | description |
|---|---|
| host/helloworld_args.h | 所有函数的参数定义 |
| host/helloworld_u.c | 包含 "enclave_helloworld() "函数，该函数具有调用 enclave 版本的 "enclave_helloworld() "函数的 marshaling 代码。 |
| host/helloworld_u.h | `enclave_helloworld()'函数的函数原型 |
Open Enclave edger8r 的说明文档在这儿。
4.2 编译
与英特尔SGX SDK一样，Open Enclave SDK目前只支持构建单一的二进制 enclave 。与英特尔SGX SDK一样，这些二进制文件也必须用一组特定的包含物和构建标志来构建。
为了简化指定正确构建参数的过程，Open Enclave SDK提供了一套pkg-config设置：
- Building enclave or host binary
- Using GCC or Clang build tools
- Compiling C or C++ code
具体的语法是：
oe<enclave|host>-<gcc|g++|clang|clang++>
helloworld 编译方法如下：
$(CC) -g -c $(CFLAGS) -DOE_API_VERSION=2 enc.c -o enc.o
$(CC) -g -c $(CFLAGS) -DOE_API_VERSION=2 helloworld_t.c -o helloworld_t.o
$(CC) -o helloworldenc helloworld_t.o enc.o $(LDFLAGS) $(CRYPTO_LDFLAGS)
4.3 签名 enclave 程序
在运行SGX enclave 之前，需要为 enclave 指定定义 enclave 应如何加载的属性。这些属性与签名密钥一起，定义了用于验证和密封操作的 enclave 身份。
使用 essign 的 SDK 工具对 encalve 库进行签名。
oesign sign -e helloworldenc -c helloworld.conf -k private.pem
enclave 的签名证书必须是 3072-bit RSA keys with exponent 3。
密钥生成方法如下：
openssl genrsa -out myprivate.pem -3 3072
签名的配置文件在 helloworld.conf。该文件定义了enclave的配置。
必选项：
- Debug: enclave 是否可以以 debug 模式加载
- NumTCS：要在 enclave 中分配的线程控制结构（TCS）的数量。这决定了在 enclave 中可以执行的最大并发线程数。
- NumStackPages：为 enclave 中每个线程分配的堆栈页数。
- NumHeapPages：为 enclave 分配的作为堆内存的页数。
上述4个属性也将反映在产生的 enclave 的UniqueID（MRENCLAVE）中。此外，以下两个属性是由开发者定义的，并直接映射到以下SGX身份属性。
- ProductID：产品标识（ISVPRODID），供开发者区分以相同MRSIGNER值签署的不同 enclave。
- SecurityVersion：enclave 的安全版本号（ISVSVN），它可以用来防止对密封密钥的回滚攻击。每当对 enclave 代码进行安全修复时，这个值都应该被递增。
可选项：
-
Linux, PSW >= 2.14.1
-
CreateZeroBaseEnclave：是否应该用基础地址0x0创建 enclave ？默认为0。
-
StartAddress：当 enclave 基址为0x0（CreateZeroBaseEnclave=1）时， enclave 镜像将在此地址创建。该值需要与OE_PAGE_SIZE（0x1000）对齐，并大于mmap最小地址（/proc/sys/vm/mmap_min_addr）。
基于0的 enclave 在访问0页时保证了NullPointerException行为。依赖于这种行为的应用程序现在可以在 enclave 内运行（例如，.NET运行时）。
-
-
指定额外的密钥共享和分离（KSS）身份属性（for SGX enclave only）
- FamilyID：开发者可以指定产品系列标识（SGX的ISVFAMILYID），将不同的 enclave 组合在一个共同的标识下，如包括几个 enclave 应用程序的应用套件的标识。
- ExtendedProductID：扩展的产品标识（SGX的ISVEXTPRODID）值，当16位的产品标识被证明过于局限时，开发者可以将其作为enclave的128位全球唯一标识。更多细节，请参见《英特尔软件》的表37-19。
比如：FamilyID=47183823-2574-4bfd-b411-99ed177d3e43 ExtendedProductID=2768c720-1e28-11eb-adc1-0242ac120002
-
SGX2 机器
- CapturePFGPExceptions：是否应该启用(1)或不启用(0) enclave 内异常处理程序来捕获#PF和#GP异常（SGX2特性，默认值：0）。
上述所有设置可以通过宏定义（OE_SET_ENCLAVE_SGX2 或OE_SET_ENCLAVE_SGX）来进行设置。
OE_SET_ENCLAVE_SGX2 支持 KSS 设置。
OE_SET_ENCLAVE_SGX2(
1, /* ProductID */
1, /* SecurityVersion */
({0x47, 0x18, 0x38, 0x23, 0x25, 0x74, 0x4b, 0xfd, 0xb4, 0x11, 0x99, 0xed, 0x17, 0x7d, 0x3e, 0x43}), /* ExtendedProductID */
({0x27, 0x68, 0xc7, 0x20, 0x1e, 0x28, 0x11, 0xeb, 0xad, 0xc1, 0x02, 0x42, 0xac, 0x12, 0x00, 0x02}), /* FamilyID */
true, /* Debug */
true, /* CapturePFGPExceptions */
true /* RequireKSS */
false, /* CreateZeroBaseEnclave */
0, /* StartAddress */
1024, /* NumHeapPages */
1024, /* NumStackPages */
1); /* NumTCS */
OE_SET_ENCLAVE_SGX设置下，允许在调试模式下运行enclave，而不用先签署它。在这种情况下，enclave 被视为具有标准签名者ID（MRSIGNER）的值。
OE_SET_ENCLAVE_SGX(
1, /* ProductID */
1, /* SecurityVersion */
1, /* Debug */
1024, /* NumHeapPages: heap size in units of 4KB pages */
1024, /* NumStackPages: stack size, in units of 4KB pages */
1); /* NumTCS */
如果是 OP-TEE （ARM TrustZone），则使用sign.py对其进行签名。具体用法参考Signing an OP-TEE Enclave。
总结
更多关于Intel TEE API的操作参考 tee-internal-core-api-specification
5. 编译 host 端应用程序
5.1 使用 oeedger8r 编译 helloworld.edl 的 trusted 部分，生成 enclave 端的相关文件
oeedger8r --search-path c:\openenclave\include --search-path c:\openenclave\include\openenclave\edl\sgx ..\helloworld.edl --trusted
| file | description |
|---|---|
| enclave/helloworld_args.h | 所有函数的参数定义 |
| enclave/helloworld_t.c | 包含 "host_helloworld() "函数，其中包含调用 host 的 "host_helloworld() "函数的 marshaling 代码。 |
| enclave/helloworld_t.h | host_helloworld()函数的函数原型 |
6. helloworld 调用流程
ninja 编译过程
ninja run 过程
