WAMR sgx-ra 示例全解析：在 Intel SGX 中运行 iwasm 并基于 librats 完成远程证明

WAMR sgx-ra 示例全解析：在 Intel SGX 中运行 iwasm 并基于 librats 完成远程证明

【免费下载链接】fluent-bitFast and Lightweight Logs, Metrics and Traces processor for Linux, BSD, OSX and Windows项目地址: https://gitcode.com/GitHub_Trending/fl/fluent-bit

本指南以 WAMR（WebAssembly Micro Runtime）内置的samples/sgx-ra示例为对象，完整讲解如何在支持 Intel SGX 的处理器上，把 WASM 运行时 iwasm 放进安全飞地（Enclave）中运行，并借助 librats 库生成可被第三方验证的远程证明（Remote Attestation）证据。读者学完后将能够：独立完成 SGX SDK / DCAP / PCCS 全链路环境搭建，构建并运行 sgx-ra 示例，理解证据（Evidence）的生成与解析流程，以及在无 SGX 能力的平台上验证 Quote 并执行 Claims 校验。

示例概览：远程证明如何与 WAMR 结合

sgx-ra 是 WAMR 仓库中一个面向 Intel SGX 平台的示例程序，其核心目标是用 librats 在 SGX 环境中执行远程证明，并让 iwasm（WAMR 的运行时入口）在 Enclave 内部加载并运行一个 Wasm 应用。整个示例的目录结构如下（相对仓库根目录）：

• 示例主目录：lib/wasm-micro-runtime-WAMR-2.4.1/samples/sgx-ra
• Wasm 应用源码：samples/sgx-ra/wasm-app/main.c
• 构建脚本：samples/sgx-ra/CMakeLists.txt
• librats 封装层：core/iwasm/libraries/lib-rats

需要特别说明的是，该示例只能在支持 SGX 的处理器上构建与运行（可通过 Intel 官方支持的处理器列表确认），因为它依赖 SGX 提供的硬件可信执行环境。从构建脚本 CMakeLists.txt 可以看到，它通过WAMR_BUILD_PLATFORM "linux-sgx"指定了 SGX 平台，并开启WAMR_BUILD_LIB_RATS 1、WAMR_BUILD_LIBC_WASI 1、WAMR_BUILD_FAST_INTERP 1等特性开关，最终产物是两个关键文件：enclave.signed.so（签名后的 Enclave 镜像）与iwasm（运行在 Enclave 内的运行时）。

在架构层面，sgx-ra 把 WAMR 运行时整体编译进 SGX Enclave：Enclave 内部执行 Wasm 字节码解释与模块管理，Wasm 应用通过导入（native）函数调用 librats 的封装 API 来生成证据。librats 本身在 Enclave 内外都有一层桥接实现，这在后文会结合源码展开。

前置准备

硬件与系统前提

运行本示例的机器必须配备支持 Intel SGX 的 CPU，并在 BIOS/UEFI 中开启 SGX 与 DCAP 相关能力。示例文档明确要求 SGX-RA 至少安装以下组件：

• WASI-SDK，默认位于/opt/wasi-sdk（用于把 Wasm 应用编译为 wasm32 目标）；
• Intel SGX SDK与Intel SGX DCAP Library（提供 Enclave 开发与 Quote 生成能力）；
• Intel SGX SSL（为 Enclave 内提供 OpenSSL 兼容的加解密能力，librats 依赖它）；
• Node.js 与 Intel PCCS（缓存证明材料，可选但强烈建议）。

安装 WASI-SDK

Wasm 应用test.wasm需要通过 WASI-SDK 的 clang 交叉编译。在 wasm-app/CMakeLists.txt 中可以看到默认的 SDK 路径正是/opt/wasi-sdk（也可通过-DWASI_SDK_DIR覆盖），编译器为${WASI_SDK_DIR}/bin/clang，目标平台为wasm32。

安装 Intel SGX 依赖

以下命令是文档给出的 Ubuntu 20.04 环境安装示例。首先设置平台与版本变量：

# Set your platform, you can get the platforms list on # https://download.01.org/intel-sgx/latest/linux-latest/distro $ cd $HOME $ OS_PLATFORM=ubuntu20.04 $ OS_CODE_NAME=`lsb_release -sc` $ SGX_PLATFORM=$OS_PLATFORM-server $ SGX_RELEASE_VERSION=1.17 $ SGX_DRIVER_VERSION=1.41 $ SGX_SDK_VERSION=2.20.100.4

安装编译依赖，并把系统默认 python 指向 python3：

$ sudo apt-get update $ sudo apt-get install -y build-essential ocaml automake autoconf libtool wget python3 libssl-dev dkms zip cmake $ sudo update-alternatives --install /usr/bin/python python /usr/bin/python3 1

安装 SGX 内核驱动（DCAP 驱动，用于支持 ECDSA 引证）：

$ wget https://download.01.org/intel-sgx/sgx-dcap/$SGX_RELEASE_VERSION/linux/distro/$SGX_PLATFORM/sgx_linux_x64_driver_$SGX_DRIVER_VERSION.bin $ chmod +x sgx_linux_x64_driver_$SGX_DRIVER_VERSION.bin $ sudo ./sgx_linux_x64_driver_$SGX_DRIVER_VERSION.bin

安装 SGX SDK（安装到/opt/intel前缀，示例构建脚本默认从/opt/intel/sgxsdk读取）：

$ wget https://download.01.org/intel-sgx/sgx-dcap/$SGX_RELEASE_VERSION/linux/distro/$SGX_PLATFORM/sgx_linux_x64_sdk_$SGX_SDK_VERSION.bin $ chmod +x sgx_linux_x64_sdk_$SGX_SDK_VERSION.bin $ sudo ./sgx_linux_x64_sdk_$SGX_SDK_VERSION.bin --prefix /opt/intel

通过 apt 仓库安装 SGX DCAP 运行库（EPID、Quote 生成/校验、默认 QPL 等）：

$ echo "deb [arch=amd64] https://download.01.org/intel-sgx/sgx_repo/ubuntu $OS_CODE_NAME main" | sudo tee /etc/apt/sources.list.d/intel-sgx.list $ wget -O - https://download.01.org/intel-sgx/sgx_repo/ubuntu/intel-sgx-deb.key | sudo apt-key add $ sudo apt-get update $ sudo apt-get install -y libsgx-epid libsgx-quote-ex libsgx-dcap-ql libsgx-enclave-common-dev libsgx-dcap-ql-dev libsgx-dcap-default-qpl-dev libsgx-dcap-quote-verify-dev

安装 SGX SSL 库（librats 在 Enclave 内做哈希、签名与 TLS 相关运算时需要）：

$ git clone https://github.com/intel/linux-sgx.git $ cd linux-sgx && make preparation $ sudo cp external/toolset/$OS_PLATFORM/* /usr/local/bin $ # Verify that the paths are correctly set $ which ar as ld objcopy objdump ranlib $ cd ../ $ git clone https://github.com/intel/intel-sgx-ssl.git $ wget https://www.openssl.org/source/openssl-1.1.1v.tar.gz -O intel-sgx-ssl/openssl_source/openssl-1.1.1v.tar.gz $ cd intel-sgx-ssl/Linux $ source /opt/intel/sgxsdk/environment $ make all $ sudo make install

（可选）授权普通用户访问 SGX 平台

默认情况下 Enclave 必须以 root 权限启动。如果希望普通用户也能运行，可以把用户加入sgx_prv组：

sudo usermod -a -G sgx_prv <username>

配置 Intel PCS 与 PCCS

Intel DCAP 需要连接 Intel Provisioning Certification Service（Intel PCS）下载当前机器的证明材料（attestation collateral），例如 PCK 证书链、QE 身份信息等。为避免每次证明都与云端通信，一般会在本地部署一个缓存服务 Intel PCCS（Provisioning Certification Caching Service），DCAP 与 PCCS 之间通过 HTTPS 交互。

订阅 Intel PCS Web 服务

Intel SGX DCAP 需要免费订阅 Intel PCS 服务。在 Intel SGX Software Services 门户完成订阅流程后，会获得主密钥（primary key）与备用密钥（secondary key），请妥善保存——后续配置 PCCS 时需要填入其一。

安装并配置 Intel PCCS

首先安装 Node.js（PCCS 是 Node.js 服务）与 PCCS 软件包：

$ sudo apt install -y curl cracklib-runtime $ curl -fsSL https://deb.nodesource.com/setup_20.x | sudo -E bash - && sudo apt-get install -y nodejs $ sudo apt-get install -y sgx-dcap-pccs

安装过程会运行 PCCS 配置脚本，并依次提出若干问题，回答要点如下：

Do you want to configure PCCS now? (Y/N)

回答Y。

Set HTTPS listening port [8081] (1024-65535)

接受默认监听端口8081。

Set the PCCS service to accept local connections only? [Y] (Y/N)

回答N。我们需要 PCCS 接受来自其他系统的连接（例如后续用PCKIDRetrievalTool从本机以外的节点上报 collateral）。

Set your Intel PCS API key (Press ENTER to skip)

输入上一步从 Intel PCS 订阅获得的主密钥或备用密钥。

Choose caching fill method : [LAZY] (LAZY/OFFLINE/REQ)

回答REQ。这会把缓存服务置于"按需请求"模式，即收到 provisioning 请求时才去 Intel PCS 拉取对应主机的证明材料。

Set PCCS server administrator password: Re-enter administrator password: Set PCCS server user password: Re-enter user password:

为 PCCS 服务器设置管理员密码与用户密码（两组，共四个输入）。

Do you want to generate insecure HTTPS key and cert for PCCS service? [Y] (Y/N)

回答Y。测试环境使用自签名证书即可。

将当前平台的 SGX collateral 导入 PCCS

PCCS 就绪后，使用工具PCKIDRetrievalTool获取当前机器的证明材料并上报给 PCCS：

$ sudo apt-get install -y sgx-pck-id-retrieval-tool

修改其配置文件/opt/intel/sgx-pck-id-retrieval-tool/network_setting.conf：

• 将PCCS_URL改为你的缓存服务地址；
• 取消注释user_token参数，并填入配置 PCCS 时创建的用户密码；
• 设置proxy_type以适配你的网络环境（多数情况下为direct）；
• 确保USE_SECURE_CERT为FALSE（测试环境使用自签名证书）。

保存后运行：

$ sudo PCKIDRetrievalTool Intel(R) Software Guard Extensions PCK Cert ID Retrieval Tool Version 1.17.100.4 Registration status has been set to completed status. the data has been sent to cache server successfully and pckid_retrieval.csv has been generated successfully!

运行过程中可能出现一些警告，但只要数据成功写入缓存服务器，通常就意味着 collateral 上报成功。可以通过下面的命令验证 PCCS 中是否已存入证明材料：

curl -k https://localhost:8081/sgx/certification/v3/qe/identity

正常应输出一段包含证明材料的 JSON。

运行时配置

修改/etc/sgx_default_qcnl.conf：

• 将PCCS_URL设置为 PCCS 服务器的地址；
• 将USE_SECURE_CERT设为FALSE（自签名证书场景）。

完成以上步骤后，当前系统即可运行 Intel SGX 工作负载并生成用于远程证明的证据（evidence）。

构建并运行示例

构建命令

$ mkdir build && cd build $ cmake .. $ make $ # run the sample $ ./iwasm wasm-app/test.wasm

构建系统源码解析

构建过程由 samples/sgx-ra/CMakeLists.txt 驱动，其关键点包括：

• 通过runtime_lib.cmake编译 WAMR 运行时为静态库vmlib，供 Enclave 内部链接；同时用add_custom_command单独编译不受信任侧（untrusted）的桥接代码生成libvmlib_untrusted.a。
• 通过sed命令自动把product-mini/platforms/linux-sgx/enclave-sample/Enclave/Enclave.edl中的WASM_ENABLE_LIB_RATS置为 1，并同步修改 enclave-sample/Makefile 中的WAMR_BUILD_LIB_RATS = 1，从而把 librats 编译进 Enclave。
• iwasm目标调用make -C enclave-sample SGX_MODE=HW SGX_DEBUG=1，在硬件模式下编译并签名 Enclave，最终把enclave.signed.so与iwasm复制到构建目录。

从 enclave-sample/Makefile 可以看出 Enclave 侧会链接一组 librats 组件：attester（attester_nullattester、attester_sgx_ecdsa、attester_sgx_la）、verifier（verifier_nullverifier、verifier_sgx_la、verifier_sgx_ecdsa_qve）、cbor、rats_lib与 SGX SSL 加密封装等；不受信任侧则链接-lrats_u -lsgx_dcap_ql -lsgx_dcap_quoteverify -lsgx_ukey_exchange -lsgx_usgxssl，完成 Quote 生成与校验的系统调用桥接。

Wasm 应用源码解析

Wasm 应用 wasm-app/main.c 的完整执行流程为：

1. 调用librats_collect(&evidence_json, buffer)生成证据 JSON。其中buffer是应用自带的非对称随机串（示例中为"This is a sample."），它会被拼入用户数据（user_data），防止 Quote 被重放。
2. 调用librats_parse_evidence(evidence_json, evidence)把证据 JSON 解析为结构化的rats_sgx_evidence_t。
3. 用hex_dump打印 Quote、User Data、MRENCLAVE、MRSIGNER，以及产品 ID、安全版本、Attribute flags 等字段。
4. 调用librats_verify(evidence_json, evidence->user_data)在本地完成 Quote 签名验证，成功则打印Evidence is trusted.。
5. 最后通过librats_dispose_evidence_json释放证据 JSON 内存。

其中librats_*系列 API 由 lib_rats_wrapper.h 以宏的形式提供（自动补充长度参数），并在 lib_rats_wrapper.c 中以 WAMR native 函数方式注册给 Wasm 模块调用，签名分别为librats_collect ("(**~)i")、librats_verify ("(*~*~)i")、librats_parse_evidence ("(*~*~)i")、librats_dispose_evidence_json ("(i)")。

值得关注的是librats_collect_wrapper内部的计算逻辑：它先用 SHA256 对 Wasm 模块本身做哈希（wasm_runtime_get_module_hash），再与用户提供的buffer拼接后做第二次 SHA256，得到最终的user_data：

user_data = SHA256(sha256(wasm_module) || buffer)

这保证了 user_data 同时绑定"运行中的 Wasm 模块内容"与"本次请求的随机串"，是远程证明中防止模块被篡改、防止重放攻击的关键设计。证据 JSON 由 librats 的librats_collect_evidence_to_json生成，其中包含sgx_ecdsa类型的 Quote 及其长度。

预期输出与错误码

运行./iwasm wasm-app/test.wasm后，程序会以 JSON 形式打印证据，并输出消息：

Evidence is trusted.

如果验证出现问题，错误码会以0xeXXX的形式体现，对应的错误原因定义在 Intel SGX Data Center Attestation Primitives 的sgx_ql_lib_common.h头文件中（SGX_QL_*系列错误码）。此外，main.c 中还有一处实现细节提醒：如果希望把rats_sgx_evidence_t直接声明在栈上，需要把CMakeLists.txt中CMAKE_EXE_LINKER_FLAGS的栈大小至少调整为 51200；示例默认使用malloc分配以避免栈溢出。

在非 SGX 平台上验证 Quote

在 Intel SGX 平台上生成的 Quote，也可以在不支持 SGX 的系统（例如不同 CPU 架构的云服务器）上进行验证。这种场景常见于云端机密计算部署：证明方在 SGX 主机上生成证据，验证方在普通节点上做验签与 Claims 比对。

安装验证所需的 SGX 库

在非 SGX 平台上安装 Quote 验证所需的 DCAP 库子集：

$ OS_CODE_NAME=`lsb_release -sc` # install SGX DCAP Library $ echo "deb [arch=amd64] https://download.01.org/intel-sgx/sgx_repo/ubuntu $OS_CODE_NAME main" | sudo tee /etc/apt/sources.list.d/intel-sgx.list $ wget -O - https://download.01.org/intel-sgx/sgx_repo/ubuntu/intel-sgx-deb.key | sudo apt-key add $ sudo apt-get update $ sudo apt-get install -y libsgx-quote-ex libsgx-dcap-ql libsgx-dcap-quote-verify libsgx-dcap-default-qpl

配置 PCCS 与运行时

• PCCS 配置：按照前文《安装并配置 Intel PCCS》一节步骤操作；
• 运行时配置：按照前文《运行时配置》一节步骤操作（修改/etc/sgx_default_qcnl.conf）。

将全部 SGX collateral 导入 PCCS

与单机场景不同，验证方需要把所有可能出现在 Quote 中的 SGX CPU collateral提前配置进 PCCS，使用 Intel 提供的 PCCS 管理工具PccsAdminTool：

# Set up the Intel PCCS administration tool $ git clone https://github.com/intel/SGXDataCenterAttestationPrimitives.git $ cd SGXDataCenterAttestationPrimitives/tools/PccsAdminTool $ sudo apt-get install -y python3 python3-pip $ pip3 install -r requirements.txt # Configuring the Intel PCCS. Input the PCS/PCCS password as requested. # 1. Get registration data from PCCS service ./pccsadmin.py get # 2. Fetch platform collateral data from Intel PCS based on the registration data ./pccsadmin.py fetch # 3. Put platform collateral data or appraisal policy files to PCCS cache db ./pccsadmin.py put # 4. Request PCCS to refresh certificates or collateral in cache database ./pccsadmin.py refresh

四个子命令构成一个完整的数据流：从 PCCS 取注册数据（get）→ 依据注册数据向 Intel PCS 拉取 collateral（fetch）→ 写入 PCCS 缓存库（put）→ 刷新缓存（refresh）。

执行验证

在非 SGX 平台上有两种验证途径：

1. 通过 Wasm 应用验证：修改 Wasm 应用，对预先计算好的 Quote 调用librats_verify进行验证；
2. 直接使用 librats 库：如果非 SGX 平台并不需要执行 WebAssembly 代码（即不使用 WAMR），可以直接调用底层 librats 库完成验证，示例代码位于 samples/sgx-ra/non-sgx-verify 目录。

non-sgx-verify 目录下提供了使用 C# 作为托管语言的验证示例（csharp/Program.cs），其验证思路非常清晰：

• 解析 librats 输出的证据 JSON（{"type":"sgx_ecdsa","report_base64":"...","report_len":...}）；
• 按照 SGX_report_body_t结构在字节流中的固定偏移读取字段：MRENCLAVE（0x70）、MRSIGNER（0xB0）、Product ID（0x130）、Security Version（0x132）、User Data（0x170）；
• 按user_data = SHA256(SHA256(wasm文件内容) || nonce)重新计算 user_data 并与之比对；
• 通过 P/Invoke 调用/usr/local/lib/librats/librats_lib.so中的librats_verify_evidence_from_json完成 Quote 签名验证。

这个示例还展示了应用侧 Claims 校验的完整写法，即验证方需要提前持有期望的 MRENCLAVE / MRSIGNER / 安全版本 / 产品 ID 等参考值并逐一比对。

Claims 校验

运行时完成 Quote 签名验证后，应用还必须检查 Quote 中嵌入的其他 Claims，确保其与预期值一致。Intel 的《Data Center Attestation Primitives: Library API》文档第 3.8 节《Enclave Identity Checking》定义了需要检查的 Claims，摘要如下：

• Enclave 身份检查：检查MRENCLAVE（Enclave 身份哈希），或检查MRSIGNER与product id（软件提供方身份）；
• 验证 Attributes：生产环境的 Enclave 不应把Debug标志置为 1；
• 验证 SSA Frame 扩展特性集；
• 验证 Enclave 的 ISV_SVN 安全版本：每当 Enclave 发布安全更新时，ISV_SVN 应相应递增以反映更高的安全等级；
• 验证 ReportData 包含预期值：ReportData 既可以携带 Enclave 提供的特定数据，也可以存放随 Quote 一起提供的大块数据的哈希。注意，Quote 签名验证本身就保证了 ReportData（以及 REPORT body 其余部分）的完整性。

在 lib_rats_common.h 中可以找到对应的属性位定义：SGX_FLAGS_INITTED（0x001）、SGX_FLAGS_DEBUG（0x002）、SGX_FLAGS_MODE64BIT（0x004）、SGX_FLAGS_PROVISION_KEY（0x010）、SGX_FLAGS_EINITTOKEN_KEY（0x020）、SGX_FLAGS_KSS（0x080）、SGX_FLAGS_AEX_NOTIFY（0x400）。main.c 中打印证据字段时正是逐一与这些掩码做与运算来解读 Attributes。

进一步阅读与排错建议

• 若 Quote 验证返回0xeXXX错误，优先对照sgx_ql_lib_common.h中的SGX_QL_*错误码定位原因（常见于 PCCS 地址配置错误、证书不受信任、collateral 未就绪等）；
• 相关底层实现可继续阅读本仓库内的 lib_rats_wrapper.c、lib_rats_common.h 以及 enclave-sample/Makefile；
• 关于 Intel SGX 的安装、DCAP 库 API（ECDSA Quote 生成与校验）、多包平台远程证明、PCCS 管理工具的使用等，可参考 Intel 官方随 SGX DCAP 发行版附带的《Intel SGX Software Installation Guide For Linux OS》《Intel SGX ECDSA QuoteLibReference DCAP API》《Remote Attestation for Multi-Package Platforms using Intel SGX DCAP》以及PccsAdminTool/README文档。

【免费下载链接】fluent-bitFast and Lightweight Logs, Metrics and Traces processor for Linux, BSD, OSX and Windows项目地址: https://gitcode.com/GitHub_Trending/fl/fluent-bit