armored-witness-boot

Introduction

TODO

Supported hardware

The following table summarizes currently supported SoCs and boards.

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:

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: