jiggoha / armored-witness-os

ArmoredWitness Trusted OS

Introduction

TODO

Supported hardware

The following table summarizes currently supported SoCs and boards.

SoC	Board	SoC package	Board package
NXP i.MX6UL	USB armory Mk II LAN	imx6ul	usbarmory/mk2
NXP i.MX6ULL	USB armory Mk II	imx6ul	usbarmory/mk2

Purpose

This trusted OS is a TamaGo unikernel intended to run on the board(s) listed above in the TrustZone Secure World system mode, to be used in conjuction with the counterpart witness trusted applet unikernel running in the Secure World user mode.

The GoTEE syscall interface is implemented for communication between the Trusted OS and Trusted Applet.

The trusted OS can be also executed under QEMU emulation, including networking support (requires a tap0 device routing the Trusted Applet IP address).

⚠️ emulated runs perform partial tests due to lack of full hardware support by QEMU.

make DEBUG=1 make qemu
...
00:00:00 tamago/arm • TEE security monitor (Secure World system/monitor)
00:00:00 SM applet verification
00:00:01 SM applet verified
00:00:01 SM loaded applet addr:0x90000000 entry:0x9007751c size:14228514
00:00:01 SM starting mode:USR sp:0xa0000000 pc:0x9007751c ns:false
00:00:02 tamago/arm • TEE user applet
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
00:00:02 TA requesting SM status
00:00:02 ----------------------------------------------------------- Trusted OS ----
00:00:02 Secure Boot ............: false
00:00:02 Runtime ................: tamago/arm
00:00:02 Link ...................: false
00:00:02 TA starting ssh server (SHA256:eeMIwwN/zw1ov1BvO6sW3wtYi463sq+oLgKhmAew1WE) at 10.0.0.1:22

Trusted OS signing

To maintain the chain of trust the Trusted OS must be signed, to this end the OS_PRIVATE_KEY1 and OS_PRIVATE_KEY2 environment variables must be set to the path of either signify or minisign siging keys, while compiling.

Example key generation (signify, called signify-openbsd on some OS):

signify -G -p armored-witness-os-1.pub -s armored-witness-os-1.sec
signify -G -p armored-witness-os-2.pub -s armored-witness-os-2.sec

Example key generation (minisign):

minisign -G -p armored-witness-os-1.pub -s armored-witness-os-1.sec
minisign -G -p armored-witness-os-2.pub -s armored-witness-os-2.sec

Trusted Applet authentication

To maintain the chain of trust the OS performs trusted applet authentication before loading it, to this end the APPLET_PUBLIC_KEY environment variable must be set to the path of either signify or minisign keys, while compiling.

Example key generation (signify):

signify -G -p armored-witness.pub -s armored-witness.sec

Example key generation (minisign):

minisign -G -p armored-witness.pub -s armored-witness.sec

Building the compiler

Build the TamaGo compiler (or use the latest binary release):

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

Building and executing on ARM targets

Build the example trusted applet and kernel executables as follows:

make trusted_os

Final executables are created in the bin subdirectory, trusted_os.elf should be used for loading through armored-witness-boot.

The following targets are available:

TARGET	Board	Executing and debugging
usbarmory	UA-MKII-LAN	usbarmory/mk2

The targets support native (see relevant documentation links in the table above) as well as emulated execution (e.g. make qemu).

Debugging

An optional Serial over USB console can be used to access Trusted OS and Trusted Applet logs, it can be enabled when compiling with the DEBUG environment variable set:

make DEBUG=1 trusted_os

The Serial over USB console can be accessed from a Linux host as follows:

picocom -b 115200 -eb /dev/ttyACM0 --imap lfcrlf

QEMU

The Trusted OS image can be executed under emulation as follows:

make qemu

The emulation run network connectivity should be configured as follows (Linux example with tap0):

ip addr add 10.0.0.2/24 dev tap0
ip link set tap0 up
ip tuntap add dev tap0 mode tap group <your user group>

The emulated target can be debugged with GDB using make qemu-gdb, this will make qemu waiting for a GDB connection that can be launched as follows:

arm-none-eabi-gdb -ex "target remote 127.0.0.1:1234" example

Breakpoints can be set in the usual way:

b ecdsa.GenerateKey
continue

Trusted Applet installation

TODO

LED status

The USB armory Mk II LEDs are used, in sequence, as follows:

Boot sequence	Blue	White
0. initialization	off	off
1. trusted applet verified	off	on
2. trusted applet execution	on	on