github.com/transparency-dev/armored-witness-boot@v0.1.0/README.md (about) 1 # Introduction 2 3 TODO 4 5 ## Supported hardware 6 7 The following table summarizes currently supported SoCs and boards. 8 9 | SoC | Board | SoC package | Board package | 10 |--------------|---------------------------------------------------------------------|--------------------------------------------------------------------------|----------------------------------------------------------------------------------| 11 | 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) | 12 | 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) | 13 14 ## Secure Boot 15 16 On secure booted systems the `imx_signed` target should be used (instead of the unsigned `imx` one) with the relevant 17 [`HAB_KEYS`](https://github.com/usbarmory/usbarmory/wiki/Secure-boot-(Mk-II)) set. 18 19 ## Kernel authentication 20 21 For an overview of the firmware authentication process please see 22 <https://github.com/transparency-dev/armored-witness/tree/main/docs/firmware_auth.md>. 23 24 To maintain the chain of trust, the bootloader authenticates the kernel before 25 executing it. 26 27 ## Firmware transparency 28 29 All ArmoredWitness firmware artefacts need to be added to a firmware 30 transparency log, including the bootloader. 31 32 ### Production log 33 34 The `release/` directory contains Cloud Build configs to build and release the 35 bootloader, and includes a step to add the release manifest to a log on GCP. See 36 more info in `release/README.md`. 37 38 ### Local log 39 40 The provided `Makefile` has support for maintaining a local firmware 41 transparency log on disk. This is intended to be used for development only. 42 43 In order to use this functionality, a log key pair can be generated with the 44 following command: 45 46 ```bash 47 $ go run github.com/transparency-dev/serverless-log/cmd/generate_keys@HEAD \ 48 --key_name="DEV-Log" \ 49 --out_priv=armored-witness-log.sec \ 50 --out_pub=armored-witness-log.pub 51 ``` 52 53 ## Compiling 54 55 Download and install the 56 [latest TamaGo binary release](https://github.com/usbarmory/tamago-go/releases/latest). 57 58 ### Building the bootloader 59 60 Ensure the following environment variables are set: 61 62 | Variable | Description 63 |---------------------|------------ 64 | `BOOT_PRIVATE_KEY` | Path to bootloader firmware signing key. Used by the Makefile to sign the bootloader. 65 | `OS_PUBLIC_KEY1` | Path to OS firmware verification key 1. Embedded into the bootloader to verify the OS at run-time. 66 | `OS_PUBLIC_KEY2` | Path to OS firmware verification key 2. Embedded into the bootloader to verify the OS at run-time. 67 | `LOG_PUBLIC_KEY` | Path to log verification key. Embedded into the bootloader to verify at run-time that the OS is correctly logged. 68 | `LOG_ORIGIN` | FT log origin string. Embedded into the bootloader to verify OS firmware transparency. 69 | `LOG_PRIVATE_KEY` | Path to log signing key. Used by Makefile to add the new bootloader firmware to the local dev log. 70 | `DEV_LOG_DIR` | Path to directory in which to store the dev FT log files. 71 72 #### Example compilation with embedded keys, ready for installation with the `provision` tool 73 74 ```bash 75 # Variables as above already exported. 76 make imx manifest log_boot 77 ``` 78 79 The bootloader executable, `armored-witness-boot.imx`, is created in the current directory. 80 81 Firmware transparency artefacts will be written into `${DEV_LOG_DIR}`. 82 83 #### Example compilation with embedded keys and secure boot 84 85 ```bash 86 git clone https://github.com/transparency-dev/armored-witness-boot && cd armored-witness-boot 87 make OS_PUBLIC_KEY1=armored-witness-boot-1.pub OS_PUBLIC_KEY2=armored-witness-boot-2.pub HAB_KEYS=sb_keys imx_signed 88 ``` 89 90 ### Logging the Recovery image 91 92 #### Production log 93 94 The `recovery/` directory contains Cloud Build configs to build and release the 95 recovery image, and includes a step to add the release manifest to a log on GCP. 96 See more info in `recovery/README.md`. 97 98 #### Local log 99 100 The `Makefile` has support for fetching and logging a released version of the 101 armory-ums recovery image, too. 102 103 Note that this uses `docker` under the covers. 104 105 Run: 106 107 ```bash 108 make log_recovery 109 ``` 110 111 ### Encrypted RAM support 112 113 Only on i.MX6UL P/Ns, `BEE=1` can be set to enable AES CTR encryption for all 114 external RAM using TamaGo [bee package](https://pkg.go.dev/github.com/usbarmory/tamago/soc/nxp/bee). 115 116 ## Installing 117 118 Installing the various firmware images onto the device can be accomplished using the 119 [provision](https://github.com/transparency-dev/armored-witness/tree/main/cmd/provision) 120 tool. 121 122 ## LED status 123 124 The [USB armory Mk II](https://github.com/usbarmory/usbarmory/wiki) LEDs 125 are used, in sequence, as follows: 126 127 | Boot sequence | Blue | White | 128 |---------------------------------|------|-------| 129 | 0. initialization | off | off | 130 | 1. boot media detected | on | off | 131 | 2. kernel verification complete | on | on | 132 | 3. jumping to kernel image | off | off |