github.com/usbarmory/GoTEE@v0.0.0-20240405084336-c52770d9fcdb/README.md (about) 1 Introduction 2 ============ 3 4 The [GoTEE](https://github.com/usbarmory/GoTEE) framework implements concurrent instantiation of 5 [TamaGo](https://github.com/usbarmory/tamago) based unikernels in 6 privileged and unprivileged modes, interacting with each other through monitor 7 mode and custom system calls. 8 9 With these capabilities GoTEE implements a 10 [TamaGo](https://github.com/usbarmory/tamago) based Trusted Execution 11 Environments (TEE), bringing Go memory safety, convenience and capabilities to 12 bare metal execution within ARM TrustZone Secure World or RISC-V Supervisor 13 Execution Environments. 14 15 GoTEE can supervise pure Go, Rust or C based freestanding Trusted Applets, 16 implementing the GoTEE API, as well as any operating system capable of running 17 in ARM TrustZone Normal World or RISC-V S-mode such as Linux. 18 19 <img src="https://github.com/usbarmory/GoTEE/wiki/images/diagram.jpg" width="350"> 20 21 Documentation 22 ============= 23 24 The main documentation, which includes a tutorial, can be found on the 25 [project wiki](https://github.com/usbarmory/GoTEE/wiki). 26 27 The package API documentation can be found on 28 [pkg.go.dev](https://pkg.go.dev/github.com/usbarmory/GoTEE). 29 30 Supported hardware 31 ================== 32 33 The following table summarizes currently supported SoCs and boards. 34 35 | SoC | Board | SoC package | Board package | 36 |--------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|---------------------------------------------------------------------------|--------------------------------------------------------------------------------------| 37 | 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) | 38 | 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) | 39 | 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) | 40 41 Example application 42 =================== 43 44 In TEE nomenclature, the privileged unikernel is commonly referred to as 45 Trusted OS, while the unprivileged one represents a Trusted Applet. 46 47 The GoTEE [example](https://github.com/usbarmory/GoTEE-example) 48 demonstrate concurrent operation of Go unikernels acting as Trusted OS, 49 Trusted Applet and Main OS. 50 51 > :warning: the Main OS can be any "rich" OS (e.g. Linux), TamaGo is simply 52 > used for a self-contained example. The same applies to the Trusted Applet 53 > which can be any bare metal application capable of running in user mode and 54 > implementing GoTEE API, such as freestanding C or Rust programs. 55 > 56 > A Rust [example](https://github.com/usbarmory/GoTEE-example/tree/master/trusted_applet_rust) 57 > can be used replacing `trusted_applet_go` with `trusted_applet_rust` when building. 58 59 The example trusted OS/applet combination performs basic testing of concurrent 60 execution of three [TamaGo](https://github.com/usbarmory/tamago) 61 unikernels at different privilege levels: 62 63 * Trusted OS (ARM: TZ Secure World system mode, RISC-V: M-mode) 64 * Trusted Applet (ARM: TZ Secure World user mode, RISC-V: S-mode) 65 * Main OS (ARM: TZ Normal World system mode, RISC-V: S-mode) 66 67 The Main OS yields back with a monitor call. 68 69 The Trusted Applet sleeps for 5 seconds before attempting to read Trusted OS 70 memory, which triggers an exception handled by the supervisor which terminates 71 the Trusted Applet. 72 73 The GoTEE [syscall](https://github.com/usbarmory/GoTEE/blob/master/syscall/syscall.go) 74 interface is implemented for communication between the Trusted OS and Trusted 75 Applet. 76 77 When launched on the [USB armory Mk II](https://github.com/usbarmory/usbarmory/wiki), 78 the example application is reachable via SSH through 79 [Ethernet over USB](https://github.com/usbarmory/usbarmory/wiki/Host-communication) 80 (ECM protocol, supported on Linux and macOS hosts): 81 82 ``` 83 $ ssh gotee@10.0.0.1 84 tamago/arm • TEE security monitor (Secure World system/monitor) 85 86 allgptr # memory forensics of applet goroutines 87 csl # show config security levels (CSL) 88 csl <periph> <slave> <hex csl> # set config security level (CSL) 89 dbg # show ARM debug permissions 90 exit, quit # close session 91 gotee # TrustZone example w/ TamaGo unikernels 92 help # this help 93 linux <uSD|eMMC> # boot NonSecure USB armory Debian base image 94 peek <hex offset> <size> # memory display (use with caution) 95 poke <hex offset> <hex value> # memory write (use with caution) 96 reboot # reset device 97 sa # show security access (SA) 98 sa <id> <secure|nonsecure> # set security access (SA) 99 stack # stack trace of current goroutine 100 stackall # stack trace of all goroutines 101 102 > 103 ``` 104 105 The example can be launched with the `gotee` command which spawns the Main OS 106 twice to demonstrate behaviour before and after TrustZone restrictions are in 107 effect using real hardware peripherals. 108 109 Additionally the `linux` command can be used to spawn the 110 [USB armory Debian base image](https://github.com/usbarmory/usbarmory-debian-base_image) 111 as Non-secure main OS. 112 113 > :warning: only USB armory Debian base image releases >= 20211129 are 114 > supported for Non-secure operation. 115 116  117 118 The example can be also executed under QEMU emulation. 119 120 > :warning: emulated runs perform partial tests due to lack of full 121 > TrustZone/PMP support by QEMU. 122 123 ``` 124 make qemu 125 ... 126 > gotee 127 00:00:00 tamago/arm • TEE security monitor (Secure World system/monitor) 128 00:00:00 SM loaded applet addr:0x9c000000 entry:0x9c072740 size:4940275 129 00:00:00 SM loaded kernel addr:0x80000000 entry:0x8007100c size:4577643 130 00:00:00 SM waiting for applet and kernel 131 00:00:00 SM starting mode:USR sp:0x9e000000 pc:0x9c072740 ns:false 132 00:00:00 SM starting mode:SYS sp:0x00000000 pc:0x8007100c ns:true 133 00:00:00 tamago/arm (go1.19.1) • TEE user applet 134 00:00:00 tamago/arm (go1.19.1) • system/supervisor (Non-secure) 135 00:00:00 supervisor is about to yield back 136 00:00:00 SM stopped mode:SYS sp:0x8146bf54 lr:0x801937a4 pc:0x80193884 ns:true err:exit 137 00:00:00 applet obtained 16 random bytes from monitor: b4cc4764dd30291a52545b182313003c 138 00:00:00 applet requests echo via RPC: hello 139 00:00:00 applet received echo via RPC: hello 140 00:00:00 applet will sleep for 5 seconds 141 00:00:01 applet says 1 mississippi 142 ... 143 00:00:05 applet says 5 mississippi 144 00:00:05 applet is about to read secure memory at 0x98010000 145 00:00:05 r0:98010000 r1:9c8240c0 r2:98010000 r3:00000000 146 00:00:05 r4:00000000 r5:00000000 r6:00000000 r7:9c86bec8 147 00:00:05 r8:00000007 r9:0000003d r10:9c8020f0 r11:9c342f41 cpsr:600001d7 (ABT) 148 00:00:05 r12:00000061 sp:9c86bf08 lr:9c1b1be8 pc:9c011330 spsr:600001d0 (USR) 149 00:00:05 SM stopped mode:USR sp:0x9c86bf08 lr:0x9c1b1be8 pc:0x9c011330 ns:false err:ABT 150 ``` 151 152 Building the compiler 153 ===================== 154 155 Build the [TamaGo compiler](https://github.com/usbarmory/tamago-go) 156 (or use the [latest binary release](https://github.com/usbarmory/tamago-go/releases/latest)): 157 158 ``` 159 wget https://github.com/usbarmory/tamago-go/archive/refs/tags/latest.zip 160 unzip latest.zip 161 cd tamago-go-latest/src && ./all.bash 162 cd ../bin && export TAMAGO=`pwd`/go 163 ``` 164 165 Building and executing on ARM targets 166 ===================================== 167 168 Build the example trusted applet and kernel executables as follows: 169 170 ``` 171 git clone https://github.com/usbarmory/GoTEE-example 172 cd GoTEE-example && export TARGET=usbarmory && make nonsecure_os_go && make trusted_applet_go && make trusted_os 173 ``` 174 175 > :warning: replace `trusted_applet_go` with `trusted_applet_rust` for a Rust 176 > TA example, this requires Rust nightly and the `armv7a-none-eabi` toolchain. 177 178 Final executables are created in the `bin` subdirectory, 179 `trusted_os_usbarmory.imx` should be used for native execution. 180 181 The following targets are available: 182 183 | `TARGET` | Board | Executing and debugging | 184 |-------------|------------------|----------------------------------------------------------------------------------------------------------| 185 | `usbarmory` | USB armory Mk II | [usbarmory](https://github.com/usbarmory/tamago/tree/master/board/usbarmory#executing-and-debugging) | 186 187 The targets support native (see relevant documentation links in the table above) 188 as well as emulated execution (e.g. `make qemu`). 189 190 Building and executing on RISC-V targets 191 ======================================== 192 193 Build the example trusted applet and kernel executables as follows: 194 195 ``` 196 git clone https://github.com/usbarmory/GoTEE-example 197 cd GoTEE-example && export TARGET=sifive_u && make nonsecure_os_go && make trusted_applet_go && make trusted_os 198 ``` 199 200 > :warning: replace `trusted_applet_go` with `trusted_applet_rust` for a Rust 201 > TA example, this requires Rust nightly and the `riscv64gc-unknown-none-elf` 202 > toolchain. 203 204 Final executables are created in the `bin` subdirectory. 205 206 Available targets: 207 208 | `TARGET` | Board | Executing and debugging | 209 |-------------|------------------|----------------------------------------------------------------------------------------------------------| 210 | `sifive_u` | QEMU sifive_u | [sifive_u](https://github.com/usbarmory/tamago/tree/master/board/qemu/sifive_u#executing-and-debugging) | 211 212 The target has only been tested with emulated execution (e.g. `make qemu`) 213 214 Authors 215 ======= 216 217 Andrea Barisani 218 andrea.barisani@withsecure.com | andrea@inversepath.com 219 220 Andrej Rosano 221 andrej.rosano@withsecure.com | andrej@inversepath.com 222 223 License 224 ======= 225 226 GoTEE | https://github.com/usbarmory/GoTEE 227 Copyright (c) WithSecure Corporation 228 229 These source files are distributed under the BSD-style license found in the 230 [LICENSE](https://github.com/usbarmory/GoTEE/blob/master/LICENSE) file.