Home
tamago | https://github.com/usbarmory/tamago
Copyright (c) WithSecure Corporation
https://foundry.withsecure.com
TamaGo is a framework that enables compilation and execution of unencumbered Go applications on bare metal AMD64/ARM/RISC-V processors.
The projects spawns from the desire of reducing the attack surface of embedded systems firmware by removing any runtime dependency on C code and Operating Systems.
The TamaGo framework consists of the following components:
-
A modified Go distribution which extends
GOOSsupport to thetamagotarget, allowing bare metal execution. -
Go packages for SoC driver support.
-
Go packages for board support.
The modifications are minimal against the original Go compiler, runtime and the target application (one import required), with a clean separation from other architectures.
Strong emphasis is placed on code re-use from existing architectures already included within the standard Go runtime, see Internals.
The modifications maintain complete standard library support.
Such aspects are motivated by the desire of providing a framework that allows secure Go firmware development on embedded systems.
The current release for the TamaGo modified Go distribution is
tamago1.23.4,
which adds
GOOS=tamago support to go1.23.4.
Binary releases for amd64 and armv7l Linux hosts are available.
The main documentation can be found in this wiki.
The package API documentation can be found on pkg.go.dev.
The following table summarizes currently supported ARM SoCs and boards
(GOOS=tamago GOARCH=arm).
| SoC | Board | SoC package | Board package |
|---|---|---|---|
| NXP i.MX6ULZ/i.MX6UL | USB armory Mk II | imx6ul | usbarmory/mk2 |
| NXP i.MX6ULL/i.MX6UL | USB armory Mk II LAN | imx6ul | usbarmory/mk2 |
| NXP i.MX6ULL/i.MX6ULZ | MCIMX6ULL-EVK | imx6ul | mx6ullevk |
| Broadcom BCM2835 | Raspberry Pi Zero | bcm2835 | pi/pizero |
| Broadcom BCM2835 | Raspberry Pi 1 Model A+ | bcm2835 | pi/pi1 |
| Broadcom BCM2835 | Raspberry Pi 1 Model B+ | bcm2835 | pi/pi1 |
| Broadcom BCM2836 | Raspberry Pi 2 Model B | bcm2835 | pi/pi2 |
The following table summarizes currently supported RISC-V SoCs and boards
(GOOS=tamago GOARCH=riscv64).
| SoC | Board | SoC package | Board package |
|---|---|---|---|
| SiFive FU540 | QEMU sifive_u | fu540 | qemu/sifive_u |
The support for an actual target is work-in-progress, the testing environment is supported and all Go standard library packages are supported and tested using original distribution tests.
The execution of programs compiled with GOOS=tamago can also take place in
user space by importing any package that implements the required
runtime changes
with OS supervision instead of bare metal drivers.
Compiling and running Go programs in user space as GOOS=tamago provides the
benefit of system call isolation as the executable cannot leverage on the Go
runtime to directly access OS resources, this results in:
- isolation from OS file system, through in-memory emulated disk
- isolation from OS networking, see net.SocketFunc
- API for custom networking, rng, time handlers
The following table summarizes currently available userspace support:
| Operating System | GOARCH |
Runtime packages |
|---|---|---|
| Linux | amd64,arm,riscv64 | linux |
| Linux | amd64,arm,riscv64 | testing¹ |
| GoTEE | arm,riscv64 | applet |
¹ Used to run standard distribution tests
Go applications are simply required to import, the relevant board package to ensure that hardware initialization and runtime support takes place:
import (
// Example for USB armory Mk II
_ "github.com/usbarmory/tamago/board/usbarmory/mk2"
)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
Go applications can be compiled with the compiler built in the previous step, with the addition of a few flags/variables:
# Example for USB armory Mk II
GOOS=tamago GOARM=7 GOARCH=arm ${TAMAGO} build -ldflags "-T 0x80010000 -R 0x1000" main.go
# Example for QEMU RISC-V sifive_u
GOOS=tamago GOARCH=riscv64 ${TAMAGO} build -ldflags "-T 0x80010000 -R 0x1000" main.go
# Example for Linux userspace
GOOS=tamago ${TAMAGO} build main.go
See the respective board package README file for compilation information for each specific target.
See the respective board package README file for execution and debugging information for each specific target (real or emulated).
The example application provides sample driver usage and instructions for native as well as emulated execution.
An emulated run of the example application can be launched as follows:
git clone https://github.com/usbarmory/tamago-example
cd tamago-example && make qemu
- GoKey - the bare metal Go smartcard
- GoTEE - Go Trusted Execution Environment
- ArmoredWitness - cross-ecosystem witness network
- armory-drive - USB encrypted drive
- armory-ums - USB Mass Storage firmware
- armory-boot - primary bootloader
- tamago-example - TamaGo example application
- imx-usbserial - i.MX Serial over USB driver
- imx-usbnet - i.MX Ethernet over USB driver
- imx-enet - i.MX Ethernet driver
Andrea Barisani
[email protected] | [email protected]
Andrej Rosano
[email protected] | [email protected]
tamago | https://github.com/usbarmory/tamago
Copyright (c) WithSecure Corporation
This project is distributed under the BSD-style license found in the LICENSE file.
The TamaGo logo is adapted from the Go gopher designed by Renee French and licensed under the Creative Commons 3.0 Attributions license. Go Gopher vector illustration by Hugo Arganda.