# xtee-rust-sdk

**Repository Path**: openkylin/xtee-rust-sdk

## Basic Information

- **Project Name**: xtee-rust-sdk
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 5
- **Created**: 2026-04-13
- **Last Updated**: 2026-06-30

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# xtee-rust-sdk

`xtee-rust-sdk` 是 xTEE 的 Rust SDK 仓库，包含 TA/CA 开发所需的示例与组件。

## 仓库内容

- `examples/hello-world`：最小化 TA / 宿主（`host`）示例（运行与 ACL 部署见 [examples/hello-world/README.md](examples/hello-world/README.md)）
- `examples/hello-bjca`：BJCA 证书认证示例
- `examples/param`：参数传递示例
- `crates/xtee-utee`：TA 侧运行时与接口

## 运行说明

### CA 收集到 `out/`（所有 example 的 host）

在仓库根目录执行：

```bash
make -f Makefile.xkernel build-examples-out
# 或
./scripts/build-examples-host-out.sh
```

会在 **`out/`** 下扁平生成与各 `examples/*/host/Cargo.toml` 中 `[package].name` 同名的可执行文件（如 `out/hello_world`、`out/hello_bjca`、`out/param`、`out/hello_world_test`）。默认按本机 `rustc` host 编 CA；交叉编 aarch64 用 `make -f Makefile.xkernel build-examples-out-aarch64`。环境变量 `TARGET_HOST` / `CROSS_COMPILE_HOST` 见 `scripts/build-examples-host-out.sh` 与 `make -f Makefile.xkernel help-xkernel`。

### 向 x-kernel 的 `disk.img` 注入 TA 与 `vsock-manager`

先在各 example 下完成 TA 编译与签名（产物位于 `examples/*/ta/target/<triple>/release/<uuid>.ta`）。然后在仓库根目录：

```bash
export X_KERNEL_ROOT=/path/to/x-kernel
export VSOCK_MANAGER=/path/to/vsock-manager
make -f Makefile.xkernel deploy-xkernel
# 或
./scripts/deploy-xkernel-disk.sh
```

脚本会将 **所有** 已构建的 `examples/*/ta/target/*/release/*.ta` 拷入镜像内的 `tee/ta/`，并把 `vsock-manager` 拷到镜像根目录。挂载/卸载 `disk.img` 通常需要 **sudo**。

常用环境变量：

| 变量 | 说明 |
|------|------|
| `X_KERNEL_ROOT` | **必填**，x-kernel 仓库根路径 |
| `VSOCK_MANAGER` | **必填**，`vsock-manager` 二进制路径 |
| `DISK_IMG` | 可选，默认 `$X_KERNEL_ROOT/disk.img` |
| `MOUNT_POINT` | 可选，默认 `/mnt/xkernel-disk` |
| `TA_PATHS` | 可选，空格分隔的 `.ta` 列表；设置后不再自动扫描 `examples/` |
| `RUN_KERNEL` | 若设为 `1`，注入结束后在 `x-kernel` 下执行 `make run`（阻塞） |

**建议终端分工**：一个终端在 `x-kernel` 下长期运行 `make run`（或与 `RUN_KERNEL=1` 等价）；另一个终端在访客内先启动 `vsock-manager`，再运行 `out/` 下对应的 CA。

**tmux 联调**（`Makefile.xkernel`）：`make -f Makefile.xkernel tmux-xkernel` 默认会先执行 **`prep-xkernel-dev`**（各 example 的 `make ta`、`make sign`、再把 CA 收集到 `./out/`）。**`PREP_FOR_TMUX`** 控制 CA 体系：默认 **`native`**（本机 `rustc` host，与宿主机跑 `./out/<name>` 一致）；需要 aarch64 的 `out/` 可执行文件时用 **`PREP_FOR_TMUX=cross`**。仅全仓库 **BJCA** 签名时协商 **`SIGN_GOAL=sign_bjca`**（要求各 `ta/Makefile` 均有该目标，否则会跳过缺目标的 example）。跳过整套准备、直接起 tmux：**`SKIP_PREP=1`**。

`vsock-manager` 的实际运行与部署不在本仓库内完成，需要在 `x-kernel` 环境中操作。

在 `x-kernel` 环境中请按顺序启动：

1. 先运行 `vsock-manager`
2. 再运行 TA

## TA 编译后签名（xtee-sdk-cli）

本仓库使用 `xtee-sdk-cli` 在 TA 编译完成后执行签名，不在 `build.rs` 中做后置签名动作。

### tasign 安装说明

- 生产环境（使用 BJCA 证书）：

安装 tasign

```bash
# 编译链接时给出 BJCA 库目录（包含 libsvscc.so）
export BJCA_LIB_DIR=your-bjca-lib-path
export BJCA_LIB_NAME=svscc
# 运行时动态库搜索路径
export LD_LIBRARY_PATH=/data/work/x1/xtee-bjca:$LD_LIBRARY_PATH
cargo install tasign --features bjca --force
```

安装 xtee-sdk-cli

```bash
cargo install xtee-sdk-cli --force
```

- 测试环境（使用 TEST 证书）：

```bash
cargo install tasign --force
```

- 在 examples 目录执行：
`make all`
- 在仓库根目录执行：
  - `cargo run -p xtee-sdk-cli -- build-and-sign-ta --manifest-path examples/hello-world/ta/Cargo.toml`
- 在 `examples/hello-world` 目录执行（使用默认 `ta/Cargo.toml`）：
  - `cargo run -p xtee-sdk-cli -- build-and-sign-ta`
- `xtee-sdk-cli` 会按 TA target 自动选择 `OBJCOPY=<target>-objcopy`（如 `aarch64-linux-musl-objcopy`、`x86_64-linux-musl-objcopy`），请确保对应工具在 `PATH` 中。
- 默认输出路径：若不传 `--out`，签名产物输出到输入 ELF 同目录（`<elf_dir>/<uuid>.ta`）。
- 链模式通过受限枚举参数指定：
  - `--chain-mode ca-intermediate-leaf`（默认）
  - `--chain-mode ca-leaf`

### 指定 target 编译并签名

可以在执行时覆盖 target：

```bash
cd /data/work/x1/xtee-rust-sdk/examples/hello-world
make all CARGO_BUILD_TARGET=x86_64-unknown-linux-musl
```

或只跑签名流程：

```bash
make ta_sign CARGO_BUILD_TARGET=x86_64-unknown-linux-musl
```

也可以直接调用 `xtee-sdk-cli` 并显式传 `--target`：

```bash
cargo run -p xtee-sdk-cli -- build-and-sign-ta \
  --manifest-path examples/hello-world/ta/Cargo.toml \
  --target x86_64-unknown-linux-musl
```

## TA

实现原理、`xtee_ta!` 用法、`TaConfig::emit_main_entry` 与 `user_ta_header.rs` 说明见 **[docs/ta.md](docs/ta.md)**。

### TA 的 `main.rs` 里如何定义 `main`

默认推荐保持 `emit_main_entry=true`，此时 `main.rs` 不要再手写 `fn main`，只需在 `xtee_ta! { ... }` 之后、文件末尾 `include!(concat!(env!("OUT_DIR"), "/user_ta_header.rs"))`，由生成入口调用 `TAManager::new(Ta, uuid).run_ta()`。如果要自定义初始化或错误处理，请在 `build.rs` 将 `TaConfig` 设为 `emit_main_entry(false)`，再在 `main.rs` 自己实现 `fn main`；两种方式不要同时启用。

## Host Android 交叉编译与签名

Host（CA）支持 Android aarch64 交叉编译和 CA 签名，使用 NDK r29 和 `cargo-ndk`。

### 系统要求

- **NDK r29**（设置 `ANDROID_NDK_HOME` 环境变量）
  ```bash
  # 从 Android 官方下载
  wget https://dl.google.com/android/repository/android-ndk-r29-linux.zip
  unzip android-ndk-r29-linux.zip
  ```
  或通过 Android Studio 的 SDK Manager 安装，NDK 位于 `~/Android/Sdk/ndk/29.x.x/`。
- **cargo-ndk**：`cargo install cargo-ndk`
- **tasign-tool**：`cargo install tasign --force`
- **CMake 3.16+**（Android 交叉编译建议 3.22+）

### 编译单个示例

```bash
# 设置 NDK 路径
export ANDROID_NDK_HOME=/path/to/android-ndk-r29

# 进入示例的 host 目录
cd examples/hello-world/host

# 编译 Android aarch64 版本
make android

# 编译 + strip + 签名
make android-sign
```

可用的 Make 目标：

| 目标 | 说明 |
|------|------|
| `android` | 使用 cargo-ndk 编译 Android arm64-v8a 版本 |
| `android-strip` | 使用 NDK llvm-objcopy 剥离符号 |
| `android-sign` | 编译 + 剥离 + CA 签名 + 验证 |

编译产物位于 `target/aarch64-linux-android/release/`。

### AOSP 预编译部署

将签名后的 CA 二进制复制到 AOSP 源码树的预编译目录下，并编写对应的 `Android.bp`：

```bp
cc_prebuilt_binary {
    name: "hello-world-ca",
    srcs: ["hello_world"],
    vendor: true,
    strip: {
        none: true,
    },
    shared_libs: ["libc", "libdl"],
}
```

> `strip: { none: true }` 用于保留 `.ta_signature` ELF 段，AOSP 默认 strip 会移除该段。
>
> Rust 编写的 CA 通过 `xtee-teec` crate 静态链接 TEE Client 功能，不需要依赖 `libcc_teec.so`。

然后在产品的 `device.mk` 中添加：

```makefile
PRODUCT_PACKAGES += hello-world-ca
```