在 Intel SGX 中构建、移植与嵌入 WAMR(iwasm):完整实战指南
在 Intel SGX 中构建、移植与嵌入 WAMR(iwasm):完整实战指南
WAMR(WebAssembly Micro Runtime)是可以在 Linux SGX 可信执行环境中运行的轻量级 WebAssembly 运行时。本文以仓库中 linux_sgx.md 为核心脉络,系统讲解如何在 Intel SGX 环境下构建 WAMR vmcore(iwasm)、如何将 vmlib 移植进自定义 SGX Enclave、如何通过 ecall 命令封装嵌入 WAMR,并深入剖析 SGX Intel Protected File System(IPFS)的 WASI 文件系统映射与实战验证。读完本文,你将掌握从零搭建 WAMR+SGX 环境、配置 Fast JIT/AOT、移植 vmlib 到 Enclave、实现 ocall 日志输出,以及启用 IPFS 持久化加密文件的完整技术方案。
背景:为什么要在 SGX 中运行 WebAssembly
Intel SGX(Software Guard Extensions)通过 Enclave 机制在硬件层面为运行中的代码和数据提供机密性与完整性保护——即使操作系统或 Hypervisor 被攻破,Enclave 内的内存也无法被外部读取或篡改。而 WAMR 的 vmcore 可以完全运行在 Enclave 内部,让开发者在可信边界内执行不可信或敏感业务的 WebAssembly 模块。
WAMR 的 Linux SGX 平台实现位于仓库的 product-mini/platforms/linux-sgx,底层平台抽象(ocall、EDL 定义、线程/时间/文件封装)位于 core/shared/platform/linux-sgx。整个方案遵循 SGX 的经典双层结构:
- App(不可信区):运行在普通用户态,负责加载 Enclave、传入 WASM 文件数据;
- Enclave(可信区):运行 WAMR vmcore,实际执行 WASM 字节码/AOT 代码;
- ocall:Enclave 内部需要操作系统服务(文件、网络、时钟)时,通过 EDL 声明的 ocall 桥接到 App 侧实现。
从 CMakeLists.txt 可以看出,该平台默认启用 fast interpreter、AOT、libc-builtin、libc-WASI 和 lib-pthread,并默认将 WAMR_BUILD_TARGET 设为 X86_64(64 位平台)。
构建 WAMR vmcore(iwasm)for Linux SGX
前置依赖
- 安装 Intel SGX SDK,要求 v2.8 或更高版本(AOT 支持依赖新版 SDK);
- 官方推荐将 SDK 安装到
/opt/intel/sgxsdk(enclave-sample 的 Makefile 中SGX_SDK ?= /opt/intel/sgxsdk也印证了这一点,可通过命令行变量覆盖)。
标准构建流程
source <SGX_SDK dir>/environment
cd product-mini/platforms/linux-sgx/
mkdir build && cd build
cmake ..
make
构建会产出两个 SGX 应用所需的静态库:
- libvmlib.a:供 Enclave(可信)部分链接;
- libvmlib_untrusted.a:供 App(不可信)部分链接。
从 CMakeLists.txt 的源码可以看到,libvmlib.a 由 runtime_lib.cmake 收集的运行时源文件编译而成,而 libvmlib_untrusted.a 则是通过自定义命令将 PLATFORM_SHARED_SOURCE_UNTRUSTED 指定的 untrusted 目录下的文件(file.c、pthread.c、signal.c、socket.c、time.c)单独编译打包,专门用于 App 侧 ocall 实现。
启用 Fast JIT
默认构建只开启 fast interpreter 与 AOT。如果需要 Fast JIT(在 SGX 内直接生成并执行本地代码,进一步提升热点代码执行性能),使用:
mkdir build && cd build
cmake .. -DWAMR_BUILD_FAST_JIT=1
make
vmcore 的 cmake 构建配置项
WAMR 的 vmcore 提供了大量可通过 cmake 开关配置的特性,详细说明见 build_wamr.md。在 Linux SGX 平台默认启用的关键开关如下(可在 CMakeLists.txt 中逐项核对默认值):
| cmake 开关 | 默认值 | 作用 |
|---|---|---|
WAMR_BUILD_INTERP |
1 | 启用 WASM 解释器 |
WAMR_BUILD_FAST_INTERP |
1 | 启用 fast interpreter(比经典解释器快约 2 倍,但为容纳预编译代码多占约 2 倍内存,见 build_wamr.md) |
WAMR_BUILD_AOT |
1 | 启用 AOT(Ahead-Of-Time 编译执行) |
WAMR_BUILD_JIT |
0 | LLVM JIT,默认关闭 |
WAMR_BUILD_FAST_JIT |
0 | Fast JIT,默认关闭,需显式 -DWAMR_BUILD_FAST_JIT=1 |
WAMR_BUILD_LIBC_BUILTIN |
1 | 内置精简 libc 子集 |
WAMR_BUILD_LIBC_WASI |
1 | WASI libc 子集 |
WAMR_BUILD_LIB_PTHREAD |
1 | lib-pthread 支持(多线程) |
WAMR_BUILD_MULTI_MODULE |
0 | 多模块依赖 |
WAMR_BUILD_SIMD |
0(64 位下默认 1) | SIMD 支持 |
WAMR_BUILD_SGX_IPFS |
0 | SGX Intel Protected File System,可选启用 |
构建并运行 enclave-sample
vmcore 构建完成后,进入示例工程编译 SGX 应用:
source <SGX_SDK dir>/environment
cd enclave-sample
make
默认生成的 SGX 应用假定使用 production key 签名并在 simulation(模拟)模式下运行,可通过 make 变量覆盖默认设置:
make SGX_DEBUG=1:构建带调试信息的 Enclave(对应SGX_COMMON_CFLAGS += -O0 -g);make SGX_MODE=HW:构建运行在硬件 SGX 平台上的 Enclave。
这些变量定义在 Makefile 顶部:SGX_MODE ?= SIM、SGX_ARCH ?= x64、SGX_DEBUG ?= 0。注意 SGX_DEBUG 与 SGX_PRERELEASE 不能同时为 1;在 SGX_MODE=HW 且非 debug 的 Release 模式下,make 会要求你先用 sgx_sign 用自己的签名密钥对 enclave.so 签名后才能运行。
构建完成后生成二进制 iwasm,运行方式:
source <SGX_SDK dir>/environment
iwasm [-options] wasm_file [args...]
# 或 AOT 文件:
iwasm [-options] aot_file [args...]
Minimal 构建:精简 ocall 的轻量版本
libc-WASI 与 lib-pthread 特性需要大量的 ocall(可从 sgx_wamr.edl 中看到一长串 ocall_* 声明)。如果你的应用不需要这么多 ocall,可以使用 minimal 版本:
# 用 minimal 版本替换构建文件
cd product-mini/platforms/linux-sgx/
cp CMakeLists_minimal.txt CMakeLists.txt
cp enclave-sample/Makefile_minimal enclave-sample/Makefile
cp enclave-sample/Enclave/Enclave_minimal.edl enclave-sample/Enclave/Enclave.edl
# 然后按上面的构建流程继续
对比 CMakeLists_minimal.txt 与完整版 CMakeLists.txt 可以发现,minimal 版默认关闭了 WAMR_BUILD_LIBC_WASI(置 0)与 WAMR_BUILD_LIB_PTHREAD(置 0),其余解释器、AOT、libc-builtin 保持默认启用,从而大幅减少 ocall 面与攻击面。
将 WAMR vmcore 移植到自定义 SGX 应用
enclave-sample 演示了如何把 vmlib 的 Enclave 部分与 App 部分嵌入一个 SGX 应用。要将 WAMR vmcore 移植到自己的 SGX 应用,需要完成以下步骤:
Step 1:在 EDL 文件中导入 sgx_wamr.edl 与 sgx_pthread.edl
在 Enclave.edl 中加入:
from "sgx_pthread.edl" import *;
from "sgx_wamr.edl" import *;
此步骤在 minimal 版本中不需要。
sgx_wamr.edl 位于 ${WAMR_ROOT}/core/shared/platform/linux-sgx,因此在用 sgx_edger8r 从 Enclave.edl 生成 Enclave_u.c 与 Enclave_t.c 时,必须把它加入搜索路径:
@cd App && $(SGX_EDGER8R) --untrusted ../Enclave/Enclave.edl \
--search-path ../Enclave \
--search-path $(SGX_SDK)/include \
--search-path $(WAMR_ROOT)/core/shared/platform/linux-sgx
@cd Enclave && $(SGX_EDGER8R) --trusted ../Enclave/Enclave.edl \
--search-path ../Enclave \
--search-path $(SGX_SDK)/include \
--search-path $(WAMR_ROOT)/core/shared/platform/linux-sgx
在 enclave-sample 的 Makefile 中,Enclave_Edl_Search_Path 正是这样配置的。sgx_wamr.edl 内部声明了文件、时钟、线程、socket 等全部 ocall 接口,这些接口的 App 侧实现由 libvmlib_untrusted.a(对应 untrusted 目录)提供。
Step 2:链接静态库与 SGX pthread 库
将 libvmlib.a 链接进 Enclave 部分,libvmlib_untrusted.a 链接进 App 部分:
Enclave_Link_Flags := ... libvmlib.a ...
App_Link_Flags := ... libvmlib_untrusted.a ...
同时将 SGX pthread 库链接到 Enclave 部分(多线程支持):
Enclave_Link_Flags := ... -lsgx_pthread ...
libvmlib_untrusted.a与 SGX pthread 库在 minimal 版本中均不需要。
enclave-sample 的 Makefile 中 App_Link_Flags := $(SGX_COMMON_CFLAGS) libvmlib_untrusted.a -L$(SGX_LIBRARY_PATH) -l$(Urts_Library_Name) -lpthread 即为此处示例,而 Enclave 的 -lsgx_pthread 位于其链接组内。
Step 3:配置 Enclave 头文件搜索路径
将 WAMR 头文件目录与 SGX SDK 头文件目录加入 Enclave_Include_Paths:
Enclave_Include_Paths := ... -I$(WAMR_ROOT)/core/iwasm/include \
-I$(WAMR_ROOT)/core/shared/utils \
-I$(WAMR_ROOT)/core/shared/platform/linux-sgx \
-I$(SGX_SDK)/include \
-I$(SGX_SDK)/include/tlibc \
-I$(SGX_SDK)/include/stlport
这与 enclave-sample 中 Enclave_Include_Paths 的写法一致,其中 core/iwasm/include 提供 wasm_export.h 等公共 API 头文件。
Step 4:在 Enclave 配置文件中预留 AOT 与多线程所需资源
在 Enclave.config.xml 中配置保留内存与线程槽,以支持 WAMR AOT 和多线程:
<ReservedMemMaxSize>0x400000</ReservedMemMaxSize>
<ReservedMemExecutable>1</ReservedMemExecutable>
<TCSNum>10</TCSNum>
ReservedMemMaxSize:Enclave 保留内存最大值,AOT/JIT 生成的代码需要可执行保留内存;ReservedMemExecutable:设为 1 使保留内存可执行;TCSNum:线程控制结构(Thread Control Structure)数量,决定 Enclave 并发线程上限,多线程 WASM 应用需要调大。
Step 5:实现 ocall_print 以支持日志输出
Enclave 内的 os_printf() 需要输出到宿主终端,因此在 Enclave.edl 中声明 untrusted 接口:
untrusted {
void ocall_print([in, string]const char* str);
};
在 App 侧实现:
void
ocall_print(const char* str)
{
printf("%s", str);
}
在 Enclave 侧注册打印函数(在 Enclave 初始化时调用):
#include "wasm_export.h"
#include "bh_platform.h"
extern "C" {
typedef void (*os_print_function_t)(const char* message);
extern void os_set_print_function(os_print_function_t pf);
void
enclave_print(const char *message)
{
ocall_print(message);
}
}
// 在 Enclave 初始化开始处:
os_set_print_function(enclave_print);
其中 os_set_print_function 声明于 bh_platform.h(WAMR 平台抽象层),其定义位于 core/shared/platform/linux-sgx/sgx_platform.c。
在 SGX 中嵌入 WAMR vmcore
嵌入 WAMR vmcore 的标准方式是直接调用 vmcore 导出的 API,详见 embed_wamr.md。enclave-sample 的 Enclave.cpp 提供了 ecall_iwasm_main() 示例,演示如何用 wasm 文件缓冲区调用 wasm 应用的 main 函数:
void
ecall_iwasm_main(uint8_t *wasm_file_buf, uint32_t wasm_file_size);
此外,enclave-sample 还封装了一个 ecall 函数,用于接收 App 发往 Enclave 的命令,并在 Enclave 内调用对应的 WAMR vmcore API 处理。命令枚举与对应 API 如下:
typedef enum EcallCmd {
CMD_INIT_RUNTIME = 0, /* wasm_runtime_init/full_init() */
CMD_LOAD_MODULE, /* wasm_runtime_load() */
CMD_INSTANTIATE_MODULE, /* wasm_runtime_instantiate() */
CMD_LOOKUP_FUNCTION, /* wasm_runtime_lookup_function() */
CMD_CREATE_EXEC_ENV, /* wasm_runtime_create_exec_env() */
CMD_CALL_WASM, /* wasm_runtime_call_wasm */
CMD_EXEC_APP_FUNC, /* wasm_application_execute_func() */
CMD_EXEC_APP_MAIN, /* wasm_application_execute_main() */
CMD_GET_EXCEPTION, /* wasm_runtime_get_exception() */
CMD_DEINSTANTIATE_MODULE, /* wasm_runtime_deinstantiate() */
CMD_UNLOAD_MODULE, /* wasm_runtime_unload() */
CMD_DESTROY_RUNTIME, /* wasm_runtime_destroy() */
CMD_SET_WASI_ARGS, /* wasm_runtime_set_wasi_args() */
CMD_SET_LOG_LEVEL, /* bh_log_set_verbose_level() */
};
这套命令封装覆盖了一个 WASM 模块从初始化、加载、实例化、查找函数、执行、异常获取到销毁的完整生命周期,对应关系可以直接在 wasm_export.h 中查到同名 API。这种"App 通过 ecall 发命令、Enclave 内调用 vmcore API"的架构,把不可信的 App 与可信的运行时执行彻底隔离。
SGX Intel Protected File System(IPFS)支持
Intel SGX 提供了 Intel Protected File System Library(IPFS),用于在 Enclave 内部创建、操作和删除文件。WAMR 将 IPFS 映射到与文件交互相关的 WASI 函数上,为 Enclave 中托管的 WebAssembly 应用提供具备机密性与完整性的无缝持久化能力。
SGX IPFS 是可选特性,启用它需要满足以下条件:
- 执行
cmake时设置标志WAMR_BUILD_SGX_IPFS=1; - Enclave 必须链接可信 IPFS 库(
-lsgx_tprotected_fs); - Enclave 外的应用必须链接不可信 IPFS 库(
-lsgx_uprotected_fs); - EDL 文件必须包含导入语句:
from "sgx_tprotected_fs.edl" import *;
在 enclave-sample 工程中,设置 WAMR_BUILD_SGX_IPFS=1 后,cmake 会自动完成这些改动——从 CMakeLists.txt 可以看到,它通过 sed 将 Enclave.edl 中的 WASM_ENABLE_SGX_IPFS 宏和 Makefile 中的 WAMR_BUILD_SGX_IPFS 变量置为 1,进而启用 -lsgx_tprotected_fs 与 -lsgx_uprotected_fs 链接。
验证 IPFS 生效
运行 samples/file 中的 file WebAssembly 应用即可观察 IPFS 的使用。启用 SGX IPFS 后,该示例会生成一个加密的文本文件(而 Linux/POSIX 下是明文文件)。注意运行 file 示例时需要传 --dir=. 参数允许访问当前目录。
WASI/POSIX 到 IPFS 的映射
由于 IPFS 是 WASI/POSIX 的子集,缺失的实现需要模拟。下表总结了 WASI 到 POSIX 和 IPFS 的映射关系:
| WASI | POSIX | IPFS |
|---|---|---|
fd_read |
readv |
sgx_fread |
fd_write |
writev |
sgx_fwrite |
fd_close |
close |
sgx_fclose |
path_open |
openat |
sgx_fopen |
fd_datasync |
fsync |
sgx_fflush |
fd_tell |
lseek |
sgx_ftell |
fd_filestat_set_size |
ftruncate |
不支持收缩文件,也不模拟;扩展文件用 sgx_fseek/sgx_ftell/sgx_fwrite 模拟 |
fd_seek |
lseek |
POSIX 与 IPFS 行为不同,用 sgx_fseek/sgx_ftell/sgx_fwrite 模拟 |
fd_pwrite |
pwrite |
不支持,用 sgx_fseek/sgx_ftell/sgx_fwrite 模拟 |
fd_pread |
pread |
不支持,用 sgx_fseek/sgx_ftell/sgx_fread 模拟 |
fd_allocate |
posix_fallocate |
不支持,用 sgx_fseek/sgx_ftell/sgx_fwrite/sgx_fflush 模拟 |
这些模拟逻辑在 sgx_ipfs.c 中实现:文件通过 HashMap(ipfs_file_list)维护 fd 与 IPFS 文件指针的映射(fd2file),SGX 错误码通过 convert_sgx_errno 转换为 POSIX errno(例如文件名被篡改的 SGX_ERROR_FILE_NAME_MISMATCH 映射为 EIO,替换攻击防护可见一斑),扩展文件时使用 32KB 的 zeroes_padding 零填充缓冲。
性能开销与限制
Twine(WAMR 在 Intel SGX 上支持 WASI 的早期学术适配)通过多个基准评估了 IPFS 经 WASI 函数带来的性能开销。SGX IPFS 的威胁模型与局限性可参考 Intel 官方文档(可在 SGX SDK 安装目录的文档中查阅)。
其他注意事项
AOT 文件需加 -sgx 标志生成
为 SGX 平台生成 AOT 文件时,必须使用 -sgx 选项:
wamrc -sgx -o test.aot test.wasm
没有该标志生成的 AOT 文件无法在 SGX Enclave 内运行。
Enclave 堆大小与内存不足异常
Enclave 的默认最大堆大小为 16 MB,执行某些负载时可能不够。当抛出以下异常时:
Exception: fail to enlarge memory.
或
Exception: allocate memory failed.
需要修改 Enclave/Enclave.config.xml 中默认的 16 MB 堆大小配置:
<HeapMaxSize>0x1000000</HeapMaxSize>
将 0x1000000 调大(例如 0x4000000 对应 64 MB)即可容纳更大工作负载。另外在 CMakeLists.txt 中还可以看到,启用 WAMR_BUILD_SPEC_TEST 时,cmake 会自动把 ReservedMemMaxSize 从 0x1000000 提升到 0x8000000,用于规格测试的大内存场景。
小结
本文完整梳理了 WAMR 在 Linux SGX 上的三条主线:构建(cmake 配置 fast interpreter/AOT/Fast JIT,产出 libvmlib.a 与 libvmlib_untrusted.a)、移植(EDL 导入、静态库链接、头文件路径、Enclave 资源预留、ocall_print 日志桥接)与嵌入(ecall 命令封装驱动 vmcore API 生命周期)。SGX IPFS 则让 WASI 文件操作在 Enclave 中获得加密持久化能力,为机密计算场景下的数据落盘提供了可落地的方案。相关示例与源码均可继续在仓库的 product-mini/platforms/linux-sgx、core/shared/platform/linux-sgx 与 samples/file 目录中深入研读。