Awesome
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 |
Secure Boot
On secure booted systems the imx_signed target should be used (instead of the unsigned imx one) with the relevant
HAB_KEYS set.
Kernel authentication
For an overview of the firmware authentication process please see https://github.com/transparency-dev/armored-witness/tree/main/docs/firmware_auth.md.
To maintain the chain of trust, the bootloader authenticates the kernel before executing it.
Firmware transparency
All ArmoredWitness firmware artefacts need to be added to a firmware transparency log, including the bootloader.
Production log
The release/ directory contains Cloud Build configs to build and release the
bootloader, and includes a step to add the release manifest to a log on GCP. See
more info in release/README.md.
Local log
The provided Makefile has support for maintaining a local firmware
transparency log on disk. This is intended to be used for development only.
In order to use this functionality, a log key pair can be generated with the following command:
$ go run github.com/transparency-dev/serverless-log/cmd/generate_keys@HEAD \
--key_name="DEV-Log" \
--out_priv=armored-witness-log.sec \
--out_pub=armored-witness-log.pub
Compiling
Download and install the latest TamaGo binary release.
Building the bootloader
Ensure the following environment variables are set:
| Variable | Description |
|---|---|
BOOT_PRIVATE_KEY | Path to bootloader firmware signing key. Used by the Makefile to sign the bootloader. |
OS_PUBLIC_KEY1 | Path to OS firmware verification key 1. Embedded into the bootloader to verify the OS at run-time. |
OS_PUBLIC_KEY2 | Path to OS firmware verification key 2. Embedded into the bootloader to verify the OS at run-time. |
LOG_PUBLIC_KEY | Path to log verification key. Embedded into the bootloader to verify at run-time that the OS is correctly logged. |
LOG_ORIGIN | FT log origin string. Embedded into the bootloader to verify OS firmware transparency. |
LOG_PRIVATE_KEY | Path to log signing key. Used by Makefile to add the new bootloader firmware to the local dev log. |
DEV_LOG_DIR | Path to directory in which to store the dev FT log files. |
Example compilation with embedded keys, ready for installation with the provision tool
# Variables as above already exported.
make imx manifest log_boot
The bootloader executable, armored-witness-boot.imx, is created in the current directory.
Firmware transparency artefacts will be written into ${DEV_LOG_DIR}.
Example compilation with embedded keys and secure boot
git clone https://github.com/transparency-dev/armored-witness-boot && cd armored-witness-boot
make OS_PUBLIC_KEY1=armored-witness-boot-1.pub OS_PUBLIC_KEY2=armored-witness-boot-2.pub HAB_KEYS=sb_keys imx_signed
Logging the Recovery image
Production log
The recovery/ directory contains Cloud Build configs to build and release the
recovery image, and includes a step to add the release manifest to a log on GCP.
See more info in recovery/README.md.
Local log
The Makefile has support for fetching and logging a released version of the
armory-ums recovery image, too.
Note that this uses docker under the covers.
Run:
make log_recovery
Encrypted RAM support
Only on i.MX6UL P/Ns, BEE=1 can be set to enable AES CTR encryption for all
external RAM using TamaGo bee package.
Installing
Installing the various firmware images onto the device can be accomplished using the provision tool.
LED status
The USB armory Mk II LEDs are used, in sequence, as follows:
| Boot sequence | Blue | White |
|---|---|---|
| 0. initialization | off | off |
| 1. boot media detected | on | off |
| 2. kernel verification complete | on | on |
| 3. jumping to kernel image | off | off |