github.com/transparency-dev/armored-witness-applet@v0.1.1/README.md (about) 1 # ArmoredWitness Applet 2 3 This repo contains code for a GoTEE Trusted Applet which implements 4 a witness. It's intended to be used with the Trusted OS found at 5 https://github.com/transparency-dev/armored-witness-os. 6 7 ## Introduction 8 9 TODO. 10 11 ## Supported hardware 12 13 The following table summarizes currently supported SoCs and boards. 14 15 | SoC | Board | SoC package | Board package | 16 |--------------|---------------------------------------------------------------------|--------------------------------------------------------------------------|----------------------------------------------------------------------------------| 17 | NXP i.MX6UL | [USB armory Mk II LAN](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) | 18 | NXP i.MX6ULL | [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) | 19 20 The GoTEE [syscall](https://github.com/usbarmory/GoTEE/blob/master/syscall/syscall.go) 21 interface is implemented for communication between the Trusted OS and Trusted 22 Applet. 23 24 When launched, the witness applet is reachable via SSH through the first 25 Ethernet port. 26 27 ```none 28 $ ssh ta@10.0.0.1 29 30 date (time in RFC339 format)? # show/change runtime date and time 31 dns <fqdn> # resolve domain (requires routing) 32 exit, quit # close session 33 hab <hex SRK hash> # secure boot activation (*irreversible*) 34 help # this help 35 led (white|blue|yellow|green) (on|off) # LED control 36 mmc <hex offset> <size> # MMC card read 37 reboot # reset device 38 stack # stack trace of current goroutine 39 stackall # stack trace of all goroutines 40 status # status information 41 42 > 43 ``` 44 45 The witness can be also executed under QEMU emulation, including networking 46 support (requires a `tap0` device routing the Trusted Applet IP address), 47 through `armored-witness-os`. 48 49 > :warning: emulated runs perform partial tests due to lack of full hardware 50 > support by QEMU. 51 52 ```none 53 make DEBUG=1 trusted_os && make qemu 54 ... 55 00:00:00 tamago/arm • TEE security monitor (Secure World system/monitor) 56 00:00:00 SM applet verification 57 00:00:01 SM applet verified 58 00:00:01 SM loaded applet addr:0x90000000 entry:0x9007751c size:14228514 59 00:00:01 SM starting mode:USR sp:0xa0000000 pc:0x9007751c ns:false 60 00:00:02 tamago/arm • TEE user applet 61 00:00:02 TA MAC:1a:55:89:a2:69:41 IP:10.0.0.1 GW:10.0.0.2 DNS:8.8.8.8:53 62 00:00:02 TA requesting SM status 63 00:00:02 ----------------------------------------------------------- Trusted OS ---- 64 00:00:02 Secure Boot ............: false 65 00:00:02 Runtime ................: tamago/arm 66 00:00:02 Link ...................: false 67 00:00:02 TA starting ssh server (SHA256:eeMIwwN/zw1ov1BvO6sW3wtYi463sq+oLgKhmAew1WE) at 10.0.0.1:22 68 ``` 69 70 ## Trusted Applet authentication 71 72 To maintain the chain of trust the Trusted Applet must be signed and logged. 73 To this end, two [note](https://pkg.go.dev/golang.org/x/mod/sumdb/note) signing keys 74 must be generated. 75 76 ```bash 77 $ go run github.com/transparency-dev/serverless-log/cmd/generate_keys@HEAD \ 78 --key_name="DEV-TrustedApplet" \ 79 --out_priv=armored-witness-applet.sec \ 80 --out_pub=armored-witness-applet.pub 81 ``` 82 83 The corresponding public key files will be built into the Trusted OS to verify the Applet. 84 85 ## Firmware transparency 86 87 All ArmoredWitness firmware artefacts need to be added to a firmware transparency log. 88 89 The provided `Makefile` has support for maintaining a local firmware transparency 90 log on disk. This is intended to be used for development only. 91 92 In order to use this functionality, a log key pair can be generated with the 93 following command: 94 95 ```bash 96 $ go run github.com/transparency-dev/serverless-log/cmd/generate_keys@HEAD \ 97 --key_name="DEV-Log" \ 98 --out_priv=armored-witness-log.sec \ 99 --out_pub=armored-witness-log.pub 100 ``` 101 102 ## Building and executing on ARM targets 103 104 Download and install the 105 [latest TamaGo binary release](https://github.com/usbarmory/tamago-go/releases/latest). 106 107 ### Building the applet 108 109 Ensure the following environment variables are set: 110 111 | Variable | Description 112 |-------------------------|------------ 113 | `APPLET_PRIVATE_KEY1` | Path to Trusted Applet firmware signing key. Used by the Makefile to sign the applet. 114 | `LOG_PRIVATE_KEY` | Path to log signing key. Used by Makefile to add the new applet firmware to the local dev log. 115 | `LOG_ORIGIN` | FT log origin string. Used by Makefile to update the local dev log. 116 | `DEV_LOG_DIR` | Path to directory in which to store the dev FT log files. 117 118 The applet firmware image can then be built, signed, and logged with the following command: 119 120 ```bash 121 make trusted_applet log_applet 122 ``` 123 124 Final executables are created in the `bin` subdirectory, `trusted_applet.elf` 125 should be used for loading through `armored-witness-os`. 126 127 Firmware transparency artefacts will be written into `${DEV_LOG_DIR}`. 128 129 ### Encrypted RAM support 130 131 Only on i.MX6UL P/Ns, the `BEE` environment variable must be set to match 132 `armored-witness-boot` and `armored-witness-os` compilation options in case AES 133 CTR encryption for all external RAM, using TamaGo 134 [bee package](https://pkg.go.dev/github.com/usbarmory/tamago/soc/nxp/bee), 135 is configured at boot. 136 137 The following targets are available: 138 139 | `TARGET` | Board | Executing and debugging | 140 |-------------|------------------|----------------------------------------------------------------------------------------------------------| 141 | `usbarmory` | UA-MKII-LAN | [usbarmory/mk2](https://github.com/usbarmory/tamago/tree/master/board/usbarmory) | 142 143 The targets support native (see relevant documentation links in the table above) 144 as well as emulated execution (e.g. `make qemu`). 145 146 ### Debugging 147 148 An optional Serial over USB console can be used to access Trusted OS and 149 Trusted Applet logs, it can be enabled when compiling with the `DEBUG` 150 environment variable set: 151 152 ```bash 153 make DEBUG=1 trusted_applet log_applet 154 ``` 155 156 The Serial over USB console can be accessed from a Linux host as follows: 157 158 ```bash 159 picocom -b 115200 -eb /dev/ttyACM0 --imap lfcrlf 160 ``` 161 162 ## Trusted Applet installation 163 164 Installing the various firmware images onto the device can be accomplished using the 165 [provision tool](https://github.com/transparency-dev/armored-witness/tree/main/cmd/provision). 166 167 ## LED status 168 169 The [USB armory Mk II](https://github.com/usbarmory/usbarmory/wiki) LEDs 170 are used, in sequence, as follows: 171 172 | Boot sequence | Blue | White | 173 |---------------------------------|------|-------| 174 | 0. initialization | off | off | 175 | 1. trusted applet verified | off | on | 176 | 2. trusted applet execution | on | on | 177