WAMR 飞地运行时实战:使用 rune 与 OCI Bundle 在 Intel SGX 中启动 WebAssembly 应用
WAMR 飞地运行时实战:使用 rune 与 OCI Bundle 在 Intel SGX 中启动 WebAssembly 应用
WebAssembly Micro Runtime(WAMR)不仅可以直接嵌入宿主程序,还可以作为 Inclavare Containers 体系中的「飞地运行时(enclave runtime)」,通过新型 OCI Runtime rune 把 .wasm/.aot 应用以容器化的方式直接运行在 Intel SGX 飞地内。本指南以仓库内 product-mini/platforms/linux-sgx/enclave-sample/App/wamr-bundle.md 为核心,完整讲解如何基于 Docker 镜像制作 WAMR 应用的 OCI Bundle、如何编写 config.json 规范文件、如何配置 rune 的飞地参数并最终以 rune run 启动 SGX 应用,同时结合仓库源码剖析 bundle 背后的 PAL 调用链与运行原理。
背景:WAMR 如何成为云原生生态中的 SGX 飞地运行时
在 enclave-sample/App/README.md 中可以看到,要让 rune(Inclavare Containers 提供的、用于在容器中通过硬件辅助飞地技术运行可信应用的新型 OCI Runtime)启动 WAMR,需要实现一个飞地运行时 PAL(Platform Abstraction Layer)来完成与 WAMR 的通信。这个被称为「WAMR enclave runtime」的形态,把 WAMR 带入了云原生生态:
- 宿主侧(untrusted):
libwamr-pal.so提供 PAL 接口,负责创建 SGX 飞地、读写 wasm 文件、通过 ECALL 下发命令; - 飞地侧(trusted):
enclave.signed.so内置 WAMR vmcore(libvmlib.a),真正执行 wasm 模块; - 应用入口:
.aot文件作为 Docker 镜像的 ENTRYPOINT,最终在 SGX 飞地中运行,获得硬件强制隔离与加密数据保护。
从源码结构看,整个链路被拆分为四段构建产物,缺一不可:
- WAMR vmcore(iwasm)与飞地镜像
enclave.signed.so; - PAL 动态库
libwamr-pal.so; - WAMR 应用(
test.aot等); - 承载以上文件的 WAMR Docker 镜像,再转换为 OCI Bundle。
下文将沿着 wamr-bundle 文档的主线,从 bundle 制作开始逐步展开。
一、创建 WAMR Application Bundle
rune 可以直接启动由 Docker 镜像转换而来的 OCI Bundle。如果本机安装了 Docker,可以使用 docker export 子命令,从已有的 WAMR 应用 Docker 镜像中导出一个 root filesystem,再组织成 bundle 目录结构。
# 创建最顶层的 bundle 目录
mkdir -p "$HOME/rune_workdir"
cd "$HOME/rune_workdir"
mkdir wamr-sgx-bundle
cd wamr-sgx-bundle
# 创建 rootfs 目录
mkdir rootfs
# 通过 Docker 将 WAMR 应用镜像导出到 rootfs 目录
docker export $(docker create ${wamr_application_image}) | sudo tar -C rootfs -xvf -
其中 ${wamr_application_image} 就是后面「构建 WAMR Docker 镜像」一节生成的镜像名(如 wamr-sgx-app)。docker export 只会导出容器的文件系统层,因此 rootfs 中应包含 /run/rune/ 下的 app(AoT 应用)以及飞地镜像 enclave.signed.so。后续所有飞地运行时需要的文件都在 rootfs 内解析,这也是 bundle 可以脱离 Docker 守护进程、被 rune 直接消费的原因。
注意:原文档中的
cd warmr-sgx-bundle为笔误,正确目录名是上一步创建的wamr-sgx-bundle,下文统一使用该名称。
二、生成并编辑 config.json 规范文件
rootfs 填充完毕后,还需要在 bundle 内生成符合 OCI Runtime Spec 格式的 config.json。rune 提供了与 runc 类似的 spec 命令,用于生成一个可编辑的模板文件:
rune spec
生成的 config.json 中各个字段的含义与 runc 生成的规范文件一致,均可参照 OCI 运行时规范(opencontainers/runtime-spec)中关于 process、annotations 等字段的说明进行编辑。接下来有两处必须修改。
1. 修改 process.args:将入口从 sh 换成目标应用
默认生成的 spec 中,process.args 指向 sh。要让目标应用在 WAMR 中运行,需要将入口改为目标应用路径;如果要在单个飞地中运行多个应用,则改为以逗号分隔的多个路径,例如 /run/rune/${wasm_app1.aot}、/run/rune/${wasm_app2.aot}……:
"process": {
"args": [
"/run/rune/${wasm_app}"
],
}
/run/rune/ 是约定俗成的应用挂载目录——在构建 Docker 镜像时,AoT 应用和飞地镜像都会被 COPY 进 /run/rune/(详见下文 Dockerfile),因此这里填写的路径必须与镜像内实际路径一致。
2. 配置 annotations:声明飞地类型与 PAL 运行时
随后在 config.json 中为飞地运行时增加如下注解:
"annotations": {
"enclave.type": "intelSgx",
"enclave.runtime.path": "/usr/lib/libwamr-pal.so",
"enclave.runtime.args": "debug"
}
三个字段的含义如下:
| 字段 | 作用 | 取值说明 |
|---|---|---|
enclave.type |
指定使用的飞地硬件类型 | 例如 intelSgx,表示 Intel SGX 硬件 |
enclave.runtime.path |
指定要启动的飞地运行时(PAL)路径 | 对于 WAMR 应用,必须指向 libwamr-pal.so,即构建产物拷贝到 /usr/lib 下的动态库 |
enclave.runtime.args |
指定传给飞地运行时的参数 | 多个参数以逗号分隔,例如 debug 用于开启调试模式 |
从实现看,这些注解与 App/pal_api.h 中定义的 PAL 属性一一对应:wamr_pal_attr_t 结构体包含 instance_dir(WAMR 实例目录,默认 ".")与 log_level(日志级别 0~5,默认 2),WAMR_PAL_ATTR_INITVAL 宏给出了二者的默认值。enclave.runtime.args=debug 即对应调试模式下更详细的日志输出。
三、运行 WAMR Application
假设已经完成上述 bundle 的准备工作,即可在 bundle 目录中执行容器:
cd "$HOME/rune_workdir/wamr-sgx-bundle"
sudo rune run wamr-sgx-app
rune run 会读取当前目录的 config.json,按 enclave.type 选择 SGX 硬件,加载 enclave.runtime.path 指定的 PAL 动态库,并把 process.args 中的应用路径交给 PAL 创建进程。此时 WAMR 应用即以 Intel SGX 飞地进程的形式运行,其代码与数据位于受硬件保护的可信内存(EPC)中。
四、把 Docker 镜像转换为 bundle 之前的完整构建链
wamr-bundle 文档假设「你已经有一个 OCI bundle」,而这个 bundle 的 rootfs 正是从 WAMR Docker 镜像导出的。要打通全流程,需要依次完成 enclave-sample/App/README.md 中的四步前置工作。
1. 构建 WAMR vmcore(iwasm)与飞地镜像
前置条件:安装 Intel SGX SDK(v2.8 或以上,建议安装到 /opt/intel/sgxsdk)。随后在 product-mini/platforms/linux-sgx 目录下编译 vmcore:
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 侧链接)。默认启用 fast interpreter、AOT、libc-builtin、libc-WASI 与 lib-pthread;如需 Fast JIT 可加 -DWAMR_BUILD_FAST_JIT=1。之后编译 enclave-sample:
cd enclave-sample
make
默认生成的飞地按「生产密钥签名 + 模拟模式」处理;可用 make SGX_DEBUG=1 构建调试飞地,用 make SGX_MODE=HW 构建硬件模式飞地。产物 enclave.signed.so 即后续 Docker 镜像与 bundle 消费的飞地镜像。
2. 构建并安装 WAMR enclave runtime 的 PAL
在 enclave-sample 目录内编译 PAL 动态库并安装到系统目录:
g++ -shared -fPIC -o libwamr-pal.so App/*.o libvmlib_untrusted.a -L/opt/intel/sgxsdk/lib64 -lsgx_urts -lpthread -lssl -lcrypto
cp ./libwamr-pal.so /usr/lib/libwamr-pal.so
注意链接选项会依据 Makefile 中的 SGX_MODE 变量在 sgx_urts 与 sgx_urts_sim 之间选择,若在模拟模式下构建应链入模拟库。安装路径 /usr/lib/libwamr-pal.so 必须与 config.json 中 enclave.runtime.path 的取值保持一致。
3. 构建 WAMR 应用
前置条件为 wasi-sdk(二进制安装于 /opt/wasi-sdk/bin/)与 wamrc AoT 编译器。将测试 C 程序编译为 .wasm 后,必须再生成 SGX 专用的 .aot 文件:
wamrc -sgx -o test.aot test.wasm
生成的 test.aot 就是 WAMR enclave runtime 启动的应用本体。-sgx 选项指示 wamrc 生成适配 SGX 环境的 AoT 文件,这是飞地场景下的关键差异点。
4. 构建 WAMR Docker 镜像
在 enclave-sample 目录下创建 Dockerfile(CentOS 与 Ubuntu 两种写法):
cat >Dockerfile <<EOF
FROM centos:8.1.1911
RUN mkdir -p /run/rune
WORKDIR /run/rune
COPY enclave.signed.so .
COPY test.aot app
#COPY ${wasm_app.aot} .
ENTRYPOINT ["/run/rune/app"]
EOF
Ubuntu 版仅更换基础镜像为 ubuntu:18.04,其余指令相同。其中 ${wasm_app.aot} 是希望额外运行的其他 WAMR 应用。构建镜像:
docker build . -t wamr-sgx-app
至此,docker export $(docker create wamr-sgx-app) 导出的 rootfs 中即包含 /run/rune/app 与 /run/rune/enclave.signed.so,与第一节 bundle 制作环节完全衔接。
5. 将 rune 集成到 Docker(可选路径)
若希望直接用 docker run --runtime=rune 而非手工打包 bundle,可以在 /etc/docker/daemon.json 中注册 rune:
{
"runtimes": {
"rune": {
"path": "/usr/local/bin/rune",
"runtimeArgs": []
}
}
}
重启 dockerd 后用 docker info | grep rune 验证,期望输出 Runtimes: rune runc。随后通过环境变量等价传递三个飞地参数:
docker run -it --rm --runtime=rune \
-e ENCLAVE_TYPE=intelSgx \
-e ENCLAVE_RUNTIME_PATH=/usr/lib/libwamr-pal.so \
-e ENCLAVE_RUNTIME_ARGS=debug \
wamr-sgx-app
这条路径与 wamr-bundle 文档中的 config.json annotations 完全对应,是同一组配置的两种表达形式。
五、源码级原理:bundle 中应用是如何被装进飞地的
wamr-bundle 文档只描述了 bundle 的静态组织方式,而「应用真正进入飞地」的动态过程由 App/App.cpp 与 Enclave/Enclave.cpp 协作完成,二者通过 Enclave/Enclave.edl 中定义的 ECALL/OCALL 通信。
PAL 接口与进程创建
App.cpp 实现了 PAL 接口(wamr_pal_init、wamr_pal_create_process、wamr_pal_exec、wamr_pal_kill、wamr_pal_destroy),并提供 pal_* 弱符号别名(__attribute__((weak, alias(...)))),方便 rune 以统一 PAL 名调用。从 wamr_pal_create_process 的实现可以推断:
- 它支持一次传入多个 wasm 文件(
wasm_files[16]数组),这正是文档中「一个飞地运行多应用」承诺的底层来源——每个文件独立完成读取、load_module、set_wasi_args、instantiate_module、app_instance_main的完整生命周期; - 标准 I/O 通过
wamr_stdio_fds_t重定向(stdin_fd/stdout_fd/stderr_fd,缺省 -1 时回落为 0/1/2),对应 WASI 参数传递; - 栈与堆默认分别为 64 KB 与 16 KB(
stack_size = 64 * 1024, heap_size = 16 * 1024),与iwasm命令行默认值一致。
ECALL 命令分发
飞地侧 ecall_handle_command 接收命令字与参数缓冲,按 EcallCmd 枚举分发:CMD_INIT_RUNTIME(wasm_runtime_full_init)、CMD_LOAD_MODULE(wasm_runtime_load)、CMD_INSTANTIATE_MODULE(wasm_runtime_instantiate)、CMD_EXEC_APP_MAIN(wasm_application_execute_main)、CMD_GET_EXCEPTION、CMD_UNLOAD_MODULE 与 CMD_DESTROY_RUNTIME 等,与 Enclave.cpp 中的 handle_cmd_* 一一对应。值得注意的安全设计:
- 模块与实例的指针不直接跨飞地边界传递,而是通过
HandleTableEntry句柄表(MAX_MODULES/MAX_INSTANCES上限 128,互斥锁保护)分配整数 ID,防止不可信侧直接操纵飞地内指针; - 所有传入缓冲均经
sgx_is_outside_enclave校验,确保 untrusted 内存与 trusted 内存边界清晰。
AoT 应用的飞地加载
handle_cmd_load_module 中通过 is_xip_file 检测 AoT 文件是否包含 XIP(Execute-In-Place)目标信息段(E_TYPE_XIP),若是则改用 os_mmap 映射可读可写可执行内存,直接就地执行,避免整文件拷贝,这是 SGX 场景下 AoT 应用的典型优化路径;非 XIP 文件则走常规的 wasm_runtime_malloc + wasm_runtime_load。
六、适用前提与限制
- 操作系统与 SGX 环境:构建 WAMR Docker 镜像需要 CentOS 8.1 或 Ubuntu 18.04-server;运行前需按 Intel SGX 官方安装指南装好 SGX 驱动、SDK 与 PSW。CentOS 8.1 下若仅安装 SGX PSW,可能缺少 UAE service 库,需手动安装
libsgx-uae-service-2.11.100.2-1.el8.x86_64.rpm。 - rune 的获取:最简单的安装方式是下载 Inclavare Containers 官方 release 的预编译二进制,并确保其位于
/usr/local/bin/rune(与 daemon.json 中的path一致)。 - 应用格式:飞地内运行的应用必须是
wamrc -sgx生成的 AoT 文件,而非原始.wasm;多应用支持依赖 PAL 的多文件加载能力,路径以/run/rune/为前缀组织。 - 密钥与签名:生产密钥签名、模拟/硬件模式的选择发生在构建阶段(
SGX_DEBUG、SGX_MODE),生成enclave.signed.so后再进入 bundle,运行期无法更改。
至此,从 Docker 镜像导出 rootfs、编写 config.json、配置飞地注解到 rune run 启动的完整流程已经打通:WAMR 应用在 Intel SGX 飞地中以硬件强制隔离的方式运行,而 OCI Bundle 这一标准载体让它无缝融入云原生容器生态。深入阅读 wamr-bundle.md、App/README.md 与 Enclave.cpp 源码,可以进一步掌握 PAL 适配细节与飞地侧安全边界设计。