Apache Teaclave 0.6.0 命令与 CLI 详解

目标：掌握 Teaclave 0.6.0 的 teaclave_cli 工具全部子命令、服务进程体系与构建系统命令，在 SGX 模拟模式下逐条实测通过。

Teaclave 平台的命令入口分为三层：面向用户的 teaclave_cli 文件加解密与认证校验工具、由构建系统产出的七个服务进程（通过命令行直接拉起）、以及驱动构建与测试的 cmake/make 命令体系。本文基于 legacy 分支 65886ec（2025-07-17，对应发布版 v0.6.0）在 Ubuntu 22.04 上的模拟模式构建产物逐条实测。

一、环境信息

项目	值
操作系统	Ubuntu 22.04（x86_64）
源码版本	legacy 分支 65886ec（2025-07-17）
平台版本号	0.6.0（CLI `--version` 实测输出）
构建模式	SGX 模拟模式（SGX_MODE=SW，-DSGX_SIM_MODE=ON）
产物路径	/root/teaclave/release（cli、services、bin、tests、tools）
Rust 工具链	rustc 1.66.0-nightly（5c8bff74b 2022-10-21）
SGX SDK	2.17.101.1（模拟库）

💡 技术拓展：Teaclave 的服务采用「不可信进程 + enclave 可信核心」双进程模型——命令行拉起的 teaclave_*_service 是普通 Linux 进程，负责 socket 监听与 TLS 终结；真正的业务逻辑跑在其加载的 *_enclave.signed.so 内（SGX 飞地）。模拟模式下 signed.so 中的完整性保护由 SDK 模拟层模拟，接口与硬件模式完全一致，因此命令体系也一致。

二、teaclave_cli 概览

2.1 获取与版本

teaclave_cli 由构建系统产出（make teaclave_cli 或全量构建），位于 release/cli/。实测版本输出：

$ /root/teaclave/release/cli/teaclave_cli --version
teaclave_cli 0.6.0

2.2 子命令清单

$ teaclave_cli --help
teaclave_cli 0.6.0
Teaclave command line tool.

USAGE:
    teaclave_cli <SUBCOMMAND>

FLAGS:
    -h, --help       Prints help information
    -V, --version    Prints version information

SUBCOMMANDS:
    attest     Display the attestation report of remote Teaclave services
    decrypt    Decrypt file
    encrypt    Encrypt file
    help       Prints this message or the help of the given subcommand(s)
    verify     Verify signatures of enclave info with auditors' public keys

四个业务子命令中，encrypt/decrypt 是纯本地操作（不依赖服务），verify 是纯本地签名校验，attest 需要连接远端服务。下面逐一详解。

三、encrypt 子命令详解

3.1 参数与帮助

$ teaclave_cli encrypt --help
teaclave_cli-encrypt 0.6.0
Encrypt file

USAGE:
    teaclave_cli encrypt [FLAGS] [OPTIONS] --algorithm <algorithm> --input-file <input-file>
                          --key <key> --output-file <output-file>

FLAGS:
    -h, --help          Prints help information
    -c, --print-cmac    Flag to print out CMAC
    -V, --version       Prints version information

OPTIONS:
    -a, --algorithm <algorithm>        Crypto algorithm, supported algorithms are "aes-gcm-128",
                                       "aes-gcm-256", "teaclave-file-128"
    -i, --input-file <input-file>      Path of input file
        --iv <iv>                      IV for AES keys in the hex format
    -k, --key <key>                    Key in the hex format
    -o, --output-file <output-file>    Path of output file

参数	说明	实测要点
--algorithm	加密算法	仅支持 aes-gcm-128、aes-gcm-256、teaclave-file-128 三种
--key	十六进制密钥	128 算法为 32 个 hex 字符（16 字节），256 算法为 64 个 hex 字符（32 字节），file-128 为 32 个 hex 字符
--iv	十六进制 IV	aes-gcm-128/256 必填（12 字节 = 24 个 hex 字符）；teaclave-file-128 不需要
--print-cmac	打印输出文件的 CMAC 认证值	用于跨通道校验数据完整性

3.2 AES-GCM-256 加密实测

$ printf "Teaclave on Ubuntu 22.04 机密计算实测\n" > u.txt
$ teaclave_cli encrypt --algorithm aes-gcm-256 \
    --input-file u.txt \
    --key 0000000000000000000000000000000000000000000000000000000000000002 \
    --iv 012345670123456701234567 \
    --output-file u.enc
$ ls -l u.txt u.enc
-rw-r--r-- 1 root root 44 Oct 15 13:02 u.txt
-rw-r--r-- 1 root root 60 Oct 15 13:02 u.enc

44 字节明文加密后为 60 字节：密文在明文基础上追加 16 字节 GCM 认证标签。密钥与 IV 均为 hex 字符串，长度不符时命令直接报错退出。

3.3 AES-GCM-128 加密实测

$ teaclave_cli encrypt --algorithm aes-gcm-128 \
    --input-file plain.txt \
    --key 00000000000000000000000000000001 \
    --iv 123456781234567812345678 \
    --output-file plain128.enc

实测退出码 0。同一密钥派生逻辑下，128 位密钥只需 32 个 hex 字符。

3.4 teaclave-file-128 算法说明

teaclave-file-128 是 Teaclave 的保护文件格式（SGX protected filesystem，文件魔数 ELIF_XGS），密钥作为保护文件系统根密钥使用，无需 IV。平台内部为任务数据传输生成的 .enc 文件即该格式（实测 tests/fixtures 下的任务输入输出文件头均为 45 4c 49 46 5f 58 47 53）。

四、decrypt 子命令详解

4.1 AES-GCM 解密与还原验证

$ teaclave_cli decrypt --algorithm aes-gcm-256 \
    --input-file u.enc \
    --key 0000000000000000000000000000000000000000000000000000000000000002 \
    --iv 012345670123456701234567 \
    --output-file u.dec
$ cat u.dec
Teaclave on Ubuntu 22.04 机密计算实测

实测与原文件逐字节一致（含中文 UTF-8 内容）。

4.2 错误密钥的行为

$ teaclave_cli decrypt --algorithm aes-gcm-256 --input-file u.enc \
    --key 0000000000000000000000000000000000000000000000000000000000000009 \
    --iv 012345670123456701234567 --output-file /dev/null
Error: Aead open_in_place error

实测退出码 1：GCM 认证标签校验失败，输出文件不会被产出。该行为可用于解密前的完整性判断。

4.3 保护文件解密实测

解密 teaclave-file-128 保护文件时只需提供根密钥（无 IV）。实测解密平台任务输出文件（该密钥为执行服务在测试模式下使用的固定密钥）：

$ teaclave_cli decrypt --algorithm teaclave-file-128 \
    --input-file output_psi0.enc \
    --key 00000000000000000000000000000000 \
    --output-file psi0.result
$ cat psi0.result
0101010

需要注意：解密密钥必须与加密方一致，密钥不符时报 Error: MacMismatch 并以退出码 1 结束（实测）。生产部署中任务数据密钥由各数据方通过 register_input_file/register_output_file 注册，不存在固定密钥；测试模式（TEST_MODE=ON）下执行服务代码使用了固定全零密钥，属该分支的测试简化，不应在真实环境复用。

五、verify 子命令详解

5.1 背景：enclave_info 与多方审计

每个服务 enclave 的身份度量（mr_enclave/mr_signer）写入 release/services/enclave_info.toml，并由多名「审计者」用各自私钥签名。客户端用审计者公钥校验签名，确认所连服务的飞地身份是多方共同背书的，这是 Teaclave 远程认证链路的信任根。

构建产物自带三名示例审计者（release/services/auditors/）：

albus_dumbledore/  （albus_dumbledore.public.pem、albus_dumbledore.sign.sha256、私钥）
godzilla/
optimus_prime/

💡 技术拓展：Teaclave 的多审计者机制要求客户端预置审计者公钥集合，任何一方单独伪造 enclave_info 都无法通过校验；生产环境应将公钥集合固化在客户端发布物中，并用自家密钥替换示例审计者。构建产物目录中附带示例私钥（测试用），生产环境必须移除。

5.2 校验实测

$ cd /root/teaclave/release/services
$ teaclave_cli verify \
    --enclave-info enclave_info.toml \
    --public-keys auditors/albus_dumbledore/albus_dumbledore.public.pem \
                  auditors/godzilla/godzilla.public.pem \
                  auditors/optimus_prime/optimus_prime.public.pem \
    --signatures auditors/albus_dumbledore/albus_dumbledore.sign.sha256 \
                 auditors/godzilla/godzilla.sign.sha256 \
                 auditors/optimus_prime/optimus_prime.sign.sha256
Verify successfully.

实测退出码 0。--public-keys 与 --signatures 均接受多值（顺序对应）。

5.3 篡改检测实测

将 enclave_info.toml 中任一 mr_enclave 首字符改动后保存为 /tmp/enclave_info_tampered.toml，用与 5.2 节相同的三名审计者公钥与签名重新校验：

$ teaclave_cli verify --enclave-info /tmp/enclave_info_tampered.toml \
    --public-keys auditors/albus_dumbledore/albus_dumbledore.public.pem \
                  auditors/godzilla/godzilla.public.pem \
                  auditors/optimus_prime/optimus_prime.public.pem \
    --signatures auditors/albus_dumbledore/albus_dumbledore.sign.sha256 \
                 auditors/godzilla/godzilla.sign.sha256 \
                 auditors/optimus_prime/optimus_prime.sign.sha256
Error: Failed to verify signatures.

实测退出码 1。单个字符的篡改即导致全部签名校验失败。

六、attest 子命令详解

attest 用于向运行中的 Teaclave 服务发起远程认证报告查询（--address 服务地址、--as-ca-cert 认证服务根证书）。

实测行为（模拟模式）：

$ teaclave_cli attest --address localhost:7777 --as-ca-cert config/keys/ias_root_ca_cert.pem
thread 'main' panicked at 'index out of bounds: the len is 0 but the index is 0', attestation/src/report.rs:526:60

模拟模式未接入真实认证服务（EPID/DCAP），认证报告生成为空导致进程异常终止，属预期边界：该子命令仅能在 SGX 硬件模式且配置了 IAS/DCA 认证服务的部署中使用。模拟模式下的服务身份校验退化为 verify 对 enclave_info 的本地校验（第五章），两种模式的信任模型差异参见《Apache Teaclave 0.6.0 机密计算场景进阶实战详解》。

七、服务进程与端口清单

全量构建后在 release/services/ 下产出七个服务进程，均以命令行直接拉起（无配置文件参数，配置经环境变量与 runtime.config.toml 定位）。实测监听端口：

进程	监听端口	角色
teaclave_authentication_service	7776 / 17776	用户注册与登录（对外 7776，服务间 17776）
teaclave_storage_service	17778	键值存储（任务与函数元数据）
teaclave_access_control_service	17779	访问控制策略判定
teaclave_management_service	17777	函数/任务/数据元数据管理
teaclave_scheduler_service	17780	任务调度队列
teaclave_frontend_service	7777	用户唯一入口（注册函数、创建与调用任务）
teaclave_execution_service	无监听端口	执行器：从调度器拉取任务，在 enclave 内执行

实测启动顺序（与仓库功能测试脚本一致）：

source /opt/sgxsdk/environment
export TEACLAVE_PROJECT_ROOT=/root/teaclave
export SGX_MODE=SW
export RUST_LOG=info
export AS_SPID="00000000000000000000000000000000"
export AS_KEY="00000000000000000000000000000000"
export AS_ALGO="sgx_epid"
export AS_URL="https://api.trustedservices.intel.com:443"

cd /root/teaclave/release/services
nohup ./teaclave_authentication_service > /tmp/auth.log 2>&1 &
nohup ./teaclave_storage_service > /tmp/storage.log 2>&1 &
nohup ./teaclave_access_control_service > /tmp/ac.log 2>&1 &
sleep 6
nohup ./teaclave_management_service > /tmp/mgmt.log 2>&1 &
nohup ./teaclave_scheduler_service > /tmp/sched.log 2>&1 &
sleep 6
nohup ./teaclave_frontend_service > /tmp/frontend.log 2>&1 &
nohup ./teaclave_execution_service > /tmp/exec.log 2>&1 &
sleep 5
ss -tln | grep -E ":(7776|7777|17776|17777|17778|17779|17780) "

实测七个端口全部监听。AS_* 四个变量在模拟模式下为占位值（认证被禁用，任意值可过），硬件模式下填入 Intel 认证服务的真实凭据。

另有 release/bin/teaclave_execution_service_libos（LibOS 执行器变体，用于非 SGX 环境的执行服务）与 release/tools/teaclave_sgx_tool（enclave 签名信息查询工具）。

7.1 运行期环境变量

变量	作用	实测取值
SGX_MODE	enclave 运行模式	SW（模拟）/ HW（硬件）
SGX_SDK	SDK 路径（environment 脚本导出）	/opt/sgxsdk
TEACLAVE_PROJECT_ROOT	定位 config 与 release 产物	/root/teaclave
TEACLAVE_LOG	服务日志等级	info / debug
AS_SPID / AS_KEY / AS_ALGO / AS_URL	远程认证四要素	模拟模式任意占位值

八、构建系统命令详解

8.1 CMake 配置选项

选项	默认值	说明
SGX_SIM_MODE	OFF	ON 时以 SGX_MODE=SW 构建（无硬件验证路径）
TEST_MODE	OFF	ON 时编译功能测试、集成测试与测试固件
OFFLINE	OFF	ON 时 cargo 以 --offline 运行，使用本地预取依赖
GIT_SUBMODULE	ON	配置时自动同步 third_party 子模块
EXECUTOR_BUILTIN	ON	内置 Rust 函数执行器
EXECUTOR_WAMR	ON	WAMR WASM 解释器执行器
EXECUTOR_MESAPY	OFF	MesaPy（Python）执行器，需额外构建
CMAKE_C/CXX_COMPILER	系统默认	实测 Ubuntu 22.04 需指定 gcc-9/g++-9

💡 技术拓展：三个执行器对应三类函数载荷——Builtin 执行器运行编译进 enclave 的 Rust 原生函数（echo、PSI、GBDT 训练等）；WAMR 执行器在 enclave 内用 WASM 解释器执行用户上传的 wasm 载荷；MesaPy 执行器运行 Python 载荷。legacy 分支默认只启用前两者，MESAPY 需手动开启并额外编译 MesaPy 解释器。

8.2 常用 make 目标

命令	作用	实测结果
make prep	生成 cmake_tomls 工作区（cargo 清单）	产出 unix_app、sgx_untrusted_app、sgx_trusted_lib、sgx_untrusted_lib 四个工作区
make -j12	全量构建	退出码 0，release 目录 3.9 GB
make teaclave_cli	仅构建 CLI 工具	退出码 0
make run-unit-tests	运行 enclave 单元测试	192 tested, 192 passed, 0 failed
make run-functional-tests	运行功能测试（自动拉起全部服务）	54 用例全部 ok，端到端通过
make run-integration-tests	运行集成测试	构建脚本提供该目标（TEST_MODE=ON 产物），本文未单独实测
make clean	清理构建产物	保留源码

8.3 依赖预取与离线构建

多目标并行构建时多个 cargo 进程会争抢同一 git 依赖数据库，实测建议先串行预取再离线构建：

cd /root/teaclave/build/cmake_tomls
cargo fetch --manifest-path unix_app/Cargo.toml
cargo fetch --manifest-path sgx_untrusted_app/Cargo.toml
cargo fetch --manifest-path sgx_trusted_lib/Cargo.toml

随后以 -DOFFLINE=ON 配置并构建。若 fetch 报 object not found（依赖 incubator-teaclave-crates 固定提交 9ca099ca），需按安装指南重建 cargo git 数据库。

九、FAQ

Q1：encrypt 报 IV 长度错误？ aes-gcm 的 IV 为 12 字节（24 个 hex 字符）。常见错误是取了 16 字节 AES 块长度的 IV。

Q2：decrypt 报 Error: MacMismatch？ teaclave-file-128 保护文件密钥与加密方不一致。测试模式下执行服务用固定全零根密钥；生产模式下应使用自己注册输出文件时提交的密钥。

Q3：attest 子命令 panic？ 模拟模式的预期边界，认证报告链路未启用。用 verify 做本地 enclave 身份校验，或在硬件模式部署后使用。

Q4：服务启动后端口未监听？ 按顺序依赖启动：authentication/storage/access_control 三服务先就绪，再起 management/scheduler，最后起 frontend/execution。查看对应 /tmp/*.log 中的报错（常见为 SGX_SDK 环境未 source 或 SGX_MODE 未导出）。

Q5：为什么 CLI 二进制有 100 MB？ 默认 debug 构建含完整符号信息；发布场景可用 release profile 重新编译（产物体积与运行性能均显著优化）。

十、参考链接

teaclave_cli 源码：https://github.com/apache/incubator-teaclave/blob/legacy/cli/src/main.rs
构建系统文档：https://github.com/apache/incubator-teaclave/blob/legacy/docs/build-system.md
Teaclave 加密模块：https://github.com/apache/incubator-teaclave/blob/legacy/crypto/src/lib.rs
审计者与 enclave_info 机制：https://github.com/apache/incubator-teaclave/blob/legacy/docs/mutual-attestation.md
本文配套安装指南：《Ubuntu 22.04 安装 Apache Teaclave 指南》《CentOS 8 安装 Apache Teaclave 指南》