usbarmory/GoTEE
GitHub: usbarmory/GoTEE
GoTEE 是一个基于 Go 语言的裸机可信执行环境框架，通过在 ARM TrustZone 和 RISC-V 平台上并发运行 TamaGo unikernel 来实现隔离的可信 OS 与可信应用执行。
Stars: 152 | Forks: 13
# 简介
[GoTEE](https://github.com/usbarmory/GoTEE) 框架实现了在特权和非特权模式下并发实例化基于 [TamaGo](https://github.com/usbarmory/tamago) 的 unikernel，它们通过 monitor 模式和自定义系统调用进行交互。
凭借这些功能，GoTEE 实现了基于 [TamaGo](https://github.com/usbarmory/tamago) 的可信执行环境（TEE），将 Go 的内存安全性、便利性和强大功能带入了 ARM TrustZone Secure World 或 RISC-V Supervisor Execution Environment 中的裸机执行环境。
GoTEE 可以监管实现了 GoTEE API 的纯 Go、Rust 或 C 编写的独立可信小应用程序（Trusted Applet），以及任何能够在 ARM TrustZone Normal World 或 RISC-V S-mode 下运行的操作系统（例如 Linux）。
# 功能
* 用于 ARM User 模式、TrustZone Normal World 或 RISC-V Supervisor Mode 的[隔离执行上下文](https://github.com/usbarmory/GoTEE/wiki/Trusted-OS-and-Applet-execution)
* [用于故障检测的机会性软锁步](https://github.com/usbarmory/GoTEE/wiki/Examples#opportunistic-soft-lockstep)
* [用于实现可信 OS 的 API](https://github.com/usbarmory/GoTEE/wiki/System-Calls#gotee-system-calls)（系统调用、JSON-RPC 和异常处理程序）
# 文档
[](https://pkg.go.dev/github.com/usbarmory/GoTEE)
包含教程的主要文档可以在[项目 wiki](https://github.com/usbarmory/GoTEE/wiki) 中找到。
Package API 文档可以在 [pkg.go.dev](https://pkg.go.dev/github.com/usbarmory/GoTEE) 上找到。
# 支持的硬件
下表总结了目前支持的 SoC 和开发板。
| SoC | Board | SoC package | Board package |
|--------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|---------------------------------------------------------------------------|--------------------------------------------------------------------------------------|
| NXP i.MX6ULZ | [USB armory Mk II](https://github.com/usbarmory/usbarmory/wiki) | [imx6ul](https://github.com/usbarmory/tamago/tree/master/soc/nxp/imx6ul) | [usbarmory/mk2](https://github.com/usbarmory/tamago/tree/master/board/usbarmory) |
| NXP i.MX6ULL | [MCIMX6ULL-EVK](https://www.nxp.com/design/development-boards/i-mx-evaluation-and-development-boards/evaluation-kit-for-the-i-mx-6ull-and-6ulz-applications-processor:MCIMX6ULL-EVK) | [imx6ul](https://github.com/usbarmory/tamago/tree/master/soc/nxp/imx6ul) | [mx6ullevk](https://github.com/usbarmory/tamago/tree/master/board/nxp/mx6ullevk) |
| SiFive FU540 | [QEMU sifive_u](https://www.qemu.org/docs/master/system/riscv/sifive_u.html) | [fu540](https://github.com/usbarmory/tamago/tree/master/soc/sifive/fu540) | [qemu/sifive_u](https://github.com/usbarmory/tamago/tree/master/board/qemu/sifive_u) |
# 示例应用程序
在 TEE 术语中，特权 unikernel 通常被称为可信 OS（Trusted OS），而非特权 unikernel 则代表可信小应用程序（Trusted Applet）。
GoTEE [示例](https://github.com/usbarmory/GoTEE-example) 演示了分别作为可信 OS、可信小应用程序和主 OS 的 Go unikernel 的并发操作。
示例中的可信 OS/小应用程序组合对在不同特权级别下并发执行的三个 [TamaGo](https://github.com/usbarmory/tamago) unikernel 进行了基础测试：
* 可信 OS（ARM：TZ Secure World system mode，RISC-V：M-mode）
* 可信小应用程序（ARM：TZ Secure World user mode，RISC-V：S-mode）
* 主 OS（ARM：TZ Normal World system mode，RISC-V：S-mode）
主 OS 通过 monitor 调用交还控制权。
可信小应用程序休眠 5 秒后尝试读取可信 OS 的内存，这会触发一个异常，监管程序将处理该异常并终止可信小应用程序。
GoTEE [系统调用](https://github.com/usbarmory/GoTEE/blob/master/syscall/syscall.go) 接口用于实现可信 OS 和可信小应用程序之间的通信。
当在 [USB armory Mk II](https://github.com/usbarmory/usbarmory/wiki) 上启动时，可以通过 SSH 经由 [Ethernet over USB](https://github.com/usbarmory/usbarmory/wiki/Host-communication)（ECM 协议，支持 Linux 和 macOS 主机）访问该示例应用程序：
```
$ ssh gotee@10.0.0.1
tamago/arm • TEE security monitor (Secure World system/monitor)
allgptr # memory forensics of applet goroutines
csl # show config security levels (CSL)
csl # set config security level (CSL)
dbg # show ARM debug permissions
exit, quit # close session
gotee # TrustZone example w/ TamaGo unikernels
help # this help
linux # boot NonSecure USB armory Debian base image
lockstep # tandem applet example w/ fault injection
peek # memory display (use with caution)
poke # memory write (use with caution)
reboot # reset device
sa # show security access (SA)
sa # set security access (SA)
stack # stack trace of current goroutine
stackall # stack trace of all goroutines
>
```
可以使用 `gotee` 命令启动该示例，该命令会生成两次主 OS，以演示在使用真实硬件外设时，应用 TrustZone 限制前后的行为差异。
此外，可以使用 `linux` 命令将 [USB armory Debian 基础镜像](https://github.com/usbarmory/usbarmory-debian-base_image) 作为非安全主 OS 启动。
该示例也可以在 QEMU 模拟环境下执行。
```
make qemu
...
> gotee
00:00:00 tamago/arm • TEE security monitor (Secure World system/monitor)
00:00:00 SM loaded applet addr:0x9c000000 entry:0x9c072740 size:4940275
00:00:00 SM loaded kernel addr:0x80000000 entry:0x8007100c size:4577643
00:00:00 SM waiting for applet and kernel
00:00:00 SM starting mode:USR sp:0x9e000000 pc:0x9c072740 ns:false
00:00:00 SM starting mode:SYS sp:0x00000000 pc:0x8007100c ns:true
00:00:00 tamago/arm (go1.19.1) • TEE user applet
00:00:00 tamago/arm (go1.19.1) • system/supervisor (Non-secure)
00:00:00 supervisor is about to yield back
00:00:00 SM stopped mode:SYS sp:0x8146bf54 lr:0x801937a4 pc:0x80193884 ns:true err:exit
00:00:00 applet obtained 16 random bytes from monitor: b4cc4764dd30291a52545b182313003c
00:00:00 applet requests echo via RPC: hello
00:00:00 applet received echo via RPC: hello
00:00:00 applet will sleep for 5 seconds
00:00:01 applet says 1 mississippi
...
00:00:05 applet says 5 mississippi
00:00:05 applet is about to read secure memory at 0x98010000
00:00:05 r0:98010000 r1:9c8240c0 r2:98010000 r3:00000000
00:00:05 r4:00000000 r5:00000000 r6:00000000 r7:9c86bec8
00:00:05 r8:00000007 r9:0000003d r10:9c8020f0 r11:9c342f41 cpsr:600001d7 (ABT)
00:00:05 r12:00000061 sp:9c86bf08 lr:9c1b1be8 pc:9c011330 spsr:600001d0 (USR)
00:00:05 SM stopped mode:USR sp:0x9c86bf08 lr:0x9c1b1be8 pc:0x9c011330 ns:false err:ABT
```
# 构建编译器
构建 [TamaGo 编译器](https://github.com/usbarmory/tamago-go)（或使用[最新的二进制发布版本](https://github.com/usbarmory/tamago-go/releases/latest)）：
```
wget https://github.com/usbarmory/tamago-go/archive/refs/tags/latest.zip
unzip latest.zip
cd tamago-go-latest/src && ./all.bash
cd ../bin && export TAMAGO=`pwd`/go
```
# 在 ARM 平台上构建和执行
按如下方式构建示例可信小应用程序和内核可执行文件：
```
git clone https://github.com/usbarmory/GoTEE-example
cd GoTEE-example && export TARGET=usbarmory && make nonsecure_os_go && make trusted_applet_go && make trusted_os
```
最终的可执行文件将创建在 `bin` 子目录中，在进行原生执行时应使用 `trusted_os_usbarmory.imx`。
以下 target 可用：
| `TARGET` | Board | Executing and debugging |
|-------------|------------------|----------------------------------------------------------------------------------------------------------|
| `usbarmory` | USB armory Mk II | [usbarmory](https://github.com/usbarmory/tamago/tree/master/board/usbarmory#executing-and-debugging) |
这些 target 支持原生执行（请参阅上表中的相关文档链接）以及模拟执行（例如 `make qemu`）。
# 在 RISC-V 平台上构建和执行
按如下方式构建示例可信小应用程序和内核可执行文件：
```
git clone https://github.com/usbarmory/GoTEE-example
cd GoTEE-example && export TARGET=sifive_u && make nonsecure_os_go && make trusted_applet_go && make trusted_os
```
最终的可执行文件将创建在 `bin` 子目录中。
可用的 target：
| `TARGET` | Board | Executing and debugging |
|-------------|------------------|----------------------------------------------------------------------------------------------------------|
| `sifive_u` | QEMU sifive_u | [sifive_u](https://github.com/usbarmory/tamago/tree/master/board/qemu/sifive_u#executing-and-debugging) |
该 target 目前仅经过模拟执行测试（例如 `make qemu`）。
# 使用 GoTEE 的应用程序
* [ArmoredWitness](https://github.com/transparency-dev/armored-witness) - 跨生态系统见证网络
# 作者
Andrea Barisani
andrea@inversepath.com
Andrej Rosano
andrej@inversepath.com
# 许可证
GoTEE | https://github.com/usbarmory/GoTEE
Copyright (c) The GoTEE authors. All Rights Reserved.
这些源文件采用在 [LICENSE](https://github.com/usbarmory/GoTEE/blob/master/LICENSE) 文件中找到的 BSD 风格许可证进行分发。
# 功能
* 用于 ARM User 模式、TrustZone Normal World 或 RISC-V Supervisor Mode 的[隔离执行上下文](https://github.com/usbarmory/GoTEE/wiki/Trusted-OS-and-Applet-execution)
* [用于故障检测的机会性软锁步](https://github.com/usbarmory/GoTEE/wiki/Examples#opportunistic-soft-lockstep)
* [用于实现可信 OS 的 API](https://github.com/usbarmory/GoTEE/wiki/System-Calls#gotee-system-calls)（系统调用、JSON-RPC 和异常处理程序）
# 文档
[](https://pkg.go.dev/github.com/usbarmory/GoTEE)
包含教程的主要文档可以在[项目 wiki](https://github.com/usbarmory/GoTEE/wiki) 中找到。
Package API 文档可以在 [pkg.go.dev](https://pkg.go.dev/github.com/usbarmory/GoTEE) 上找到。
# 支持的硬件
下表总结了目前支持的 SoC 和开发板。
| SoC | Board | SoC package | Board package |
|--------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|---------------------------------------------------------------------------|--------------------------------------------------------------------------------------|
| NXP i.MX6ULZ | [USB armory Mk II](https://github.com/usbarmory/usbarmory/wiki) | [imx6ul](https://github.com/usbarmory/tamago/tree/master/soc/nxp/imx6ul) | [usbarmory/mk2](https://github.com/usbarmory/tamago/tree/master/board/usbarmory) |
| NXP i.MX6ULL | [MCIMX6ULL-EVK](https://www.nxp.com/design/development-boards/i-mx-evaluation-and-development-boards/evaluation-kit-for-the-i-mx-6ull-and-6ulz-applications-processor:MCIMX6ULL-EVK) | [imx6ul](https://github.com/usbarmory/tamago/tree/master/soc/nxp/imx6ul) | [mx6ullevk](https://github.com/usbarmory/tamago/tree/master/board/nxp/mx6ullevk) |
| SiFive FU540 | [QEMU sifive_u](https://www.qemu.org/docs/master/system/riscv/sifive_u.html) | [fu540](https://github.com/usbarmory/tamago/tree/master/soc/sifive/fu540) | [qemu/sifive_u](https://github.com/usbarmory/tamago/tree/master/board/qemu/sifive_u) |
# 示例应用程序
在 TEE 术语中，特权 unikernel 通常被称为可信 OS（Trusted OS），而非特权 unikernel 则代表可信小应用程序（Trusted Applet）。
GoTEE [示例](https://github.com/usbarmory/GoTEE-example) 演示了分别作为可信 OS、可信小应用程序和主 OS 的 Go unikernel 的并发操作。
示例中的可信 OS/小应用程序组合对在不同特权级别下并发执行的三个 [TamaGo](https://github.com/usbarmory/tamago) unikernel 进行了基础测试：
* 可信 OS（ARM：TZ Secure World system mode，RISC-V：M-mode）
* 可信小应用程序（ARM：TZ Secure World user mode，RISC-V：S-mode）
* 主 OS（ARM：TZ Normal World system mode，RISC-V：S-mode）
主 OS 通过 monitor 调用交还控制权。
可信小应用程序休眠 5 秒后尝试读取可信 OS 的内存，这会触发一个异常，监管程序将处理该异常并终止可信小应用程序。
GoTEE [系统调用](https://github.com/usbarmory/GoTEE/blob/master/syscall/syscall.go) 接口用于实现可信 OS 和可信小应用程序之间的通信。
当在 [USB armory Mk II](https://github.com/usbarmory/usbarmory/wiki) 上启动时，可以通过 SSH 经由 [Ethernet over USB](https://github.com/usbarmory/usbarmory/wiki/Host-communication)（ECM 协议，支持 Linux 和 macOS 主机）访问该示例应用程序：
```
$ ssh gotee@10.0.0.1
tamago/arm • TEE security monitor (Secure World system/monitor)
allgptr # memory forensics of applet goroutines
csl # show config security levels (CSL)
csl 标签：ARM TrustZone, EVTX分析, Go, RISC-V, Ruby工具, TEE, Unikernel, 可信执行环境, 底层开发, 日志审计, 身份验证强制