Files
op-tee-test/docs/05-BOARD-ACTIONS.md
ssw 60b6fa6f7b vault: 设备绑定密钥 + 密封存储(宿主 16 用例 / QEMU VAULT_ALL_OK / 签名验收通过)
- src/vault-core: no_std 密码学核心(HKDF 派生、AES-256-GCM、两条水位线防回滚)
- src/ta-vault / src/ca-vault: TA 薄壳与 selftest 客户端
- build/p1_vault_qemu.sh: QEMU 全链,判据 VAULT_ALL_OK
- build/p2_ta_keys_qemu.sh: TA 公钥编进 tee.bin,默认密钥签的被拒
- build/gen_ta_keys.sh: 自建签名密钥
- docs/07-VAULT-TA.md: 设计 + 已验证/未验证清单
- CLAUDE.md 雷区 11-16:user_ta_header、嵌套 workspace、ARCH=arm、SIGPIPE、TA_PUBLIC_KEY、heredoc 变量
2026-10-28 14:37:04 +08:00

269 lines
12 KiB
Markdown
Raw Permalink Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 05 · 上板动作清单(Zynq-7015 / ACZ7015)
> 目标:把已经**在 QEMU 上验证过**的 OP-TEE 4.11 + Rust TA 搬到真实 Zynq-7015 板子上。
> 状态:QEMU 侧已完成(见 `02-P0-RESULTS.md`);**板级动作全部未执行**。
> 本文只写「在板子上要做什么、按什么顺序、怎么判断成功」;原理与设计见 `01/03/04`。
---
## 0. 先决条件(不满足就别开工)
| # | 项 | 状态 | 说明 |
|---|---|---|---|
| 0.1 | **选哪块板** | ⚠️ 待定 | `192.168.1.233` 是**生产网关**(board-agent + EasyTier + 公网入口),团队红线写明不要碰;`192.168.1.234` 的 SD 卡已坏(`mmc error -110` × 206、`/` 只读)。**建议:新板或修好卡的 .234** |
| 0.2 | **内核源码 + DTS** | ❌ 未确认 | 板上是 `4.14.0-xilinx #52` 自编内核(2023-07)。**拿不到源码这条路直接断**:开 OP-TEE 必须重编内核;`.config` 可从 `/proc/config.gz` 反推,DTS 拿不到就只能重写 |
| 0.3 | 串口 | 需确认 | 115200 8N1,能看 U-Boot / 内核日志(板上 TTL 排针) |
| 0.4 | JTAG | 可选但强烈建议 | 6 针焊盘需自焊排针;FSBL 阶段调 OP-TEE 基本离不开 |
| 0.5 | 完整备份 | **必须** | 至少备份:QSPI 内容、SD 卡全盘、`/lib/firmware/*`、`/etc/init.d/{xdma,gateway}`、`/boot`。OP-TEE 改动会动到启动链,没有备份就没有回滚 |
| 0.6 | `PLATFORM_FLAVOR` 核对 | 待做 | `plat-zynq7k` 默认 flavor 是 `zc702`,本板是 ACZ7015,**UART 基址/内存布局必须核**(见 §3.1) |
记录一份板子现状(改动前跑一遍,留底):
```sh
uname -a; cat /proc/cmdline; cat /proc/device-tree/model; echo
grep -E "^MemTotal|^Hardware" /proc/meminfo /proc/cpuinfo
cat /proc/iomem | head -40 # 看 reserved-memory 与 amba_pl 占位
zcat /proc/config.gz | grep -E "CONFIG_(TEE|OPTEE|ARM_LPAE|STRICT_DEVMEM)"
ls /dev/tee* 2>/dev/null || echo NO_TEE # 期望:现在没有
busybox devmem 0xF8000530 # IDCODE,0x0373B093 = XC7Z015
busybox devmem 0xF8000430 # TZ_DDR_RAM 当前值(改之前记下来)
```
---
## 1. 阶段 P1 · 让 OP-TEE 在安全世界跑起来
### 1.1 关键前提:A9 没有虚拟化扩展
Zynq-7000 的 Cortex-A9 **没有 ARMv7 VE**(无 HYP 模式、无 KVM),但**有 TrustZone**。
所以这里走的是 **OP-TEE 自己当 secure monitor**(Monitor 模式),**不需要 ATF** ——
这点和 QEMU 那套(ATF 当 BL1/BL2/BL31、BL32=OP-TEE)**完全不同,别照搬 QEMU 的启动链**。
### 1.2 两条启动集成路线
| 路线 | 做法 | 优点 | 代价 |
|---|---|---|---|
| **A(推荐)** | 改 FSBL:初始化 DDR/时钟后,把 `tee.bin` 载入 TZDRAM,切到 Monitor 模式跳过去 | 最干净,OP-TEE 拿到完整控制权;和后续 secure boot 链一致 | 要动 FSBL(Xilinx SDK/Vitis 里改 `fsbl` 源码),要改 bootgen 的 `.bif` |
| B(过渡) | U-Boot 里 `bootm` 加载 OP-TEE 镜像后再起内核 | 不动 FSBL,试错快 | U-Boot 已跑过一段,TCB 变大;只适合先验证能不能跑 |
先按 **B 验证可行性**,确认 OP-TEE 能在本板跑通,再改 A 固化。
### 1.3 编译(在 Linux 构建机上,不是板子上)
```sh
export CROSS_COMPILE=arm-linux-gnueabihf-
cd optee_os
make -j$(nproc) PLATFORM=zynq7k CFG_ARM32_core=y O=out/zynq7k
# 产物:out/zynq7k/core/tee.bin、tee-raw.bin、tee-header_v2.bin / tee-pager_v2.bin / tee-pageable_v2.bin
# 同时产出 TA dev kit:out/zynq7k/export-ta_arm32
```
已验证的事实(QEMU 阶段):**`PLATFORM=zynq7k` 能编过**,产出 `tee.bin` 391 KB
(仓库里的 `artifacts/tee-zynq7k.bin` 就是这个)。`plat-zynq7k/conf.mk` 已经强制了:
`CFG_ARM32_core=y`、`CFG_GIC=y`、`CFG_CDNS_UART=y`、双核、`CFG_PL310`、A9 的 NMFI workaround、
`CFG_BOOT_SECONDARY_REQUEST`(CPU1 启动机制已存在,**不需要自己写 `plat_cpu_on`**)。
### 1.4 三个必须核对的板级参数
| 参数 | 在哪 | 核对方法 |
|---|---|---|
| **UART 基址** | `plat-zynq7k/platform_config.h` + `PLATFORM_FLAVOR` | 本板串口接在 PS UART0(`0xE0000000`) 还是 UART1(`0xE0001000`)?看 `dmesg \| grep -i uart` 或 `/proc/device-tree/amba/serial@*`。**错了就完全没有输出**(QEMU 阶段就是被类似问题坑了半天) |
| **TZDRAM 地址/大小** | `platform_config.h` 的 `TZDRAM_BASE/SIZE`、`SHMEM_BASE/SIZE` | 默认值面向 zc702(1GB 板),本板只有 **512MB**,必须重算(见 §2) |
| **GIC 型号/基址** | `CFG_GIC` 相关 | Zynq 是 PL390/GIC-400 兼容,`0xF8F00100`(CPU IF)/`0xF8F01000`(Dist),与 zc702 一致,一般不用改 |
### 1.5 判定成功
串口(**secure 侧**,如果板上只接了一个串口就注意:OP-TEE 的 console 走它自己配的 UART,
QEMU 上就是第二个串口 —— 板子上如果只有一个串口,`CFG_CDNS_UART` 指的那个口就是唯一输出,
别再犯「以为它死了其实在看别的口」的错):
```
I/TC: OP-TEE version: 4.11.0 ...
I/TC: Primary CPU initializing
I/TC: Primary CPU switching to normal world boot
```
看到最后一行 = secure monitor 正常交棒回正常世界。
---
## 2. 阶段 P2 · 内存划分(最容易一次搞死板子的一步)
### 2.1 三处必须一致
DDR 安全区要被**三个地方**同时认可,缺一处就是「Linux 起不来」或「安全区形同虚设」:
1. **硬件**:`TZ_DDR_RAM`(`0xF8000430`,Zynq-7000 上每 bit 管 64 MB)
2. **OP-TEE**:`TZDRAM_BASE/SIZE`
3. **Linux DT**:`reserved-memory` 里对应节点(`no-map`)
### 2.2 本板已有的占位,绝对不能压
```
0x01800000 PL ring / KTB1 ← .233/.234 上已有,踩过就卡死
0x01840000 PL ring 2
0x01880000 DEK 发布区(DEK2 / RDEK)
```
历史上就是因为 PL ring 地址没落进 DTB 保留区,板子被内核内存踩到直接卡死。
**新划的安全区必须与上面三块、以及 DT 里所有 `reserved-memory` 无交集。**
建议候选:`0x1C000000 - 0x20000000`(64 MB),落地前用
`cat /proc/iomem` 逐段比一遍。
### 2.3 操作顺序(顺序错了很难回滚)
```
① 先只改 DT 的 reserved-memory(不动 TZ_DDR_RAM)→ 起一次
期望:MemTotal 从 ~509 MB 掉到 ~445 MB,系统正常
② 再让 OP-TEE 用这块(TZDRAM_BASE 指向它)→ 起一次
③ 最后把 TZ_DDR_RAM 的对应 bit 置为 secure → 起一次
④ 三步都过,才去谈业务
```
⚠️ **`TZ_DDR_RAM` 的置位极性必须按 UG1019 §3 复核**(哪位对应哪段、0/1 谁是 secure)。
写错的现象是「Linux 起不来」或「安全区没生效」,而且从现象反推极其困难 ——
改之前把 `busybox devmem 0xF8000430` 原值记下来。
### 2.4 判定成功
```sh
grep MemTotal /proc/meminfo # 少了约 64 MB
dmesg | grep -i "reserved" # 能看到 op-tee 的 reserved 段
# OP-TEE 侧:启动日志里 TEE_RAM / TZDRAM 地址与预期一致
```
---
## 3. 阶段 P3 · 内核 + 用户态
### 3.1 内核
```sh
# 在拿到的 4.14 内核源码上
CONFIG_TEE=y
CONFIG_OPTEE=y
CONFIG_OPTEE_SHM_NUM_PRIV_POOLS=1 # 视版本
CONFIG_STRICT_DEVMEM=y # 建议同时开,堵 /dev/mem
```
`make olddefconfig` 之后**务必 `grep '^CONFIG_OPTEE=y' .config` 确认** ——
merge_config 之后静默落回 `# CONFIG_OPTEE is not set` 是常见事故(QEMU 阶段踩过)。
### 3.2 设备树:optee 节点**必须带 interrupts**
```dts
firmware {
optee {
compatible = "linaro,optee-tz";
method = "smc";
interrupts = <0 35 4>; /* 具体 SPI 号按本板空闲中断选 */
interrupt-parent = <&intc>;
};
};
```
> **这是 QEMU 阶段最贵的一课**:只写 `compatible` + `method` 时,驱动会报
> `optee: error -ENXIO: IRQ index 0 not found`,`/dev/tee0` 根本不出现。
> 原因是 OP-TEE 4.x 默认开 async notif,Linux 驱动因此强制要求中断。
> 板上同理,别以为「Zynq 不一样」。
### 3.3 用户态
```sh
# 交叉编译(同一套命令,换 TA dev kit 目录即可)
make -C optee_client CROSS_COMPILE=arm-linux-gnueabihf-
make -C optee_client/tee-supplicant CC=arm-linux-gnueabihf-gcc LD=arm-linux-gnueabihf-gcc \
CROSS_COMPILE=arm-linux-gnueabihf- LDFLAGS="-L<client>/out/libteec"
```
板子上:
```sh
cp libteec.so* /usr/lib/ && ldconfig
cp tee-supplicant /usr/bin/
cp xxx.ta /lib/optee_armtz/<uuid>.ta
tee-supplicant -d /dev/teepriv0 & # 常驻,建议做成 systemd 服务
ls /dev/tee0 /dev/teepriv0 # 期望出现
```
### 3.4 判定成功
```sh
optee_examples/hello_world # 或本仓库的 hello_ca
# 期望:能打开 session、调用 TA、拿回结果
```
---
## 4. 阶段 P4 · Rust TA 上板
**代码一行都不用改**(QEMU 上跑的就是 armv7):
```sh
export TA_DEV_KIT_DIR=<optee_os>/out/zynq7k/export-ta_arm32
export CARGO_TARGET_ARM_UNKNOWN_LINUX_GNUEABIHF_LINKER=arm-linux-gnueabihf-gcc
export CC_arm_unknown_linux_gnueabihf=arm-linux-gnueabihf-gcc
export RUSTUP_TOOLCHAIN=nightly-2026-08-05 # 以 SDK rust-toolchain.toml 为准
# TA 必须作为 teaclave-sdk/examples/ta workspace 的成员
printf '{\n__elf_phdr_info;\ntrace_ext_prefix;\ntrace_level;\nta_head;\n};\n' > examples/ta/dyn_list
cargo build -p hello_rust-rs-ta --target arm-unknown-linux-gnueabihf --release
python3 $TA_DEV_KIT_DIR/scripts/sign_encrypt.py sign-enc --uuid <UUID> \
--in <elf> --out hello_rust.ta --key $TA_DEV_KIT_DIR/keys/default_ta.pem
```
> ⚠️ `default_ta.pem` 只是**开发用**签名密钥。量产必须换成自己的,且**私钥不进仓库**。
> 更关键:真要做安全启动,TA 签名公钥得编进 `tee.bin`(`CFG_...`/`ta_pub_key.c`),
> 否则攻击者可以换 TA。
上板判定:`hello_ca` 打印 `INC_VALUE: 41 -> 42` / `ALL OK`(和 QEMU 输出一模一样)。
---
## 5. 阶段 P5 · 把 DEK 下沉进 TA(这一步才有业务价值)
现状(`.233` 上实测):`provision_dek.sh` 把「DEK」经 `/dev/mem` 写进 DDR `0x1FF80000`,
再让**不可信的宿主**通过 PCIe C2H DMA 取走。方向是反的 —— 等于把钥匙快递给小偷。
正确形态:
```
[容器/宿主] 只发「加密这段数据」的请求
↓
[TA] 持有 K_device(= HKDF(K_seed, Device DNA ‖ eFuse USER)),永不导出
↓
[PL 安全岛] 密钥寄存器 write-only、AES-GCM 流水线、单调计数器
```
关键点:
- **K_tpm 现在是全舰队共享**(同一份 BOOT.bin → 同一把),单机失守等于全舰队 DEK 可解
→ 用 Device DNA 派生每机唯一 `K_device`,不改硬件、不多烧一位 eFuse
- **明文镜像副本必须先清干净**:`.234` 的 SD 卡上躺着两份明文签名 `BOOT.BIN`,
里面 `K_tpm` 是裸的 —— eFuse 花的钱被一个 647 KB 的文件抵掉了
- **L3 启动链是真空档**:`uEnv.txt` 用 `bootz` 起 kernel,不验签。
OP-TEE 再好也管不了「内核被换掉」这件事(见 `03-TRUST-CHAIN.md`)
---
## 6. 验收清单
- [ ] `PLATFORM=zynq7k` 编出 `tee.bin`,串口看到 `OP-TEE version: 4.11.0`
- [ ] `I/TC: Primary CPU switching to normal world boot` 后内核正常启动
- [ ] `MemTotal` 减少量 = 安全区大小,且与 DT `reserved-memory` 一致
- [ ] `dmesg | grep optee` 出现 `initialized driver`,`/dev/tee0` + `/dev/teepriv0` 存在
- [ ] `tee-supplicant` 常驻,无反复退出
- [ ] Rust CA 调 Rust TA 返回 `INC_VALUE: 41 -> 42`
- [ ] `tee-supplicant` 重启后 TA 仍可加载(安全存储路径通)
- [ ] 断电重启 3 次,以上全部复现(不是偶然)
- [ ] 原有业务(`board-agent` / EasyTier / PL 逻辑)没被破坏
## 7. 风险与回滚
| 风险 | 触发条件 | 回滚 |
|---|---|---|
| 板子起不来 | TZ_DDR_RAM 写错 / TZDRAM 与保留区重叠 | 还原 QSPI 镜像 + SD 备份;JTAG 重新下载 FSBL |
| OP-TEE 无输出 | UART 基址错 / flavor 不对 | 换 flavor 或改 `platform_config.h` 重编 |
| `/dev/tee0` 不出现 | DT 缺 `interrupts`(最容易) | 按 §3.2 补 |
| 内核 panic 在 reserved-memory | 与 `0x0180_0000` 系列冲突 | 改地址,别硬顶 |
| **eFuse 不可逆** | 烧 `AES_ONLY` / `JTAG_DIS` | **没有回滚**。所有 eFuse 动作必须排在 L3 验签补完之后,且先留一台不烧的样机 |