github.com/google/trillian-examples@v0.0.0-20240520080811-0d40d35cef0e/binary_transparency/firmware/devices/usbarmory/bootloader/README.md (about)

     1  > The contents of this directory are modified versions of the original which can
     2  > be found here: https://github.com/usbarmory/armory-boot
     3  
     4  Introduction
     5  ============
     6  
     7  This [TamaGo](https://github.com/usbarmory/tamago) based unikernel
     8  acts as a primary boot loader for the [USB armory Mk II](https://github.com/usbarmory/usbarmory/wiki),
     9  allowing boot of kernel images (e.g. Linux) from either the eMMC card or an
    10  external microSD card.
    11  
    12  Compiling
    13  =========
    14  
    15  Build the [TamaGo compiler](https://github.com/usbarmory/tamago-go)
    16  (or use the [latest binary release](https://github.com/usbarmory/tamago-go/releases/latest)):
    17  
    18  ```
    19  git clone https://github.com/usbarmory/tamago-go -b latest
    20  cd tamago-go/src && ./all.bash
    21  cd ../bin && export TAMAGO=`pwd`/go
    22  ```
    23  
    24  The `BOOT` environment variable must be set to either `uSD` or `eMMC` to
    25  configure the bootloader media for `/boot/armory-boot.conf`, as well as kernel
    26  images, location.
    27  
    28  The `START` environment variable must be set to the offset of the first valid
    29  ext4 partition where `/boot/armory-boot.conf` is located (typically 5242880 for
    30  USB armory Mk II default pre-compiled images).
    31  
    32  The `CONSOLE` environment variable may be set to `on` to enable serial
    33  logging when a [debug accessory](https://github.com/usbarmory/usbarmory/tree/master/hardware/mark-two-debug-accessory)
    34  is connected.
    35  
    36  Build the `armory-boot.imx` application executable:
    37  
    38  ```
    39  git clone https://github.com/usbarmory/armory-boot && cd armory-boot
    40  make CROSS_COMPILE=arm-none-eabi- imx BOOT=uSD START=5242880
    41  ```
    42  
    43  Installing
    44  ==========
    45  
    46  The `armory-boot.imx` file can be flashed on the internal eMMC card or an
    47  external micro SD card as shown in [these instructions](https://github.com/usbarmory/usbarmory/wiki/Boot-Modes-(Mk-II)#flashing-imx-native-images).
    48  
    49  Configuration
    50  =============
    51  
    52  The bootloader expects a single configuration file to read information on the
    53  image and parameters to boot.
    54  
    55  The bootloader is configured via a single configuration file, and can boot either
    56   an ARM kernel image or an ELF unikernel (e.g.
    57  [tamago-example](https://github.com/usbarmory/tamago-example)).
    58  The required elements in the configuration file differ depending on the type of
    59  image being loaded, examples for both are given below.
    60  
    61  It is an error specify both unikernel and kernel config parameters in the same
    62  configuration file.
    63  
    64  Linux kernel boot
    65  -----------------
    66  
    67  To load a Linux kernel, the bootloader requires that you provide the paths to
    68  the kernel image and the Device Tree Blob file, along with their respective
    69  SHA256 hashes for validation, as well as the kernel command line.
    70  
    71  Example `/boot/armory-boot.conf` configuration file for loading a Linux kernel:
    72  
    73  ```
    74  {
    75    "kernel": [
    76      "/boot/zImage-5.4.51-0-usbarmory",
    77      "aceb3514d5ba6ac591a7d5f2cad680e83a9f848d19763563da8024f003e927c7"
    78    ],
    79    "dtb": [
    80      "/boot/imx6ulz-usbarmory-default-5.4.51-0.dtb",
    81      "60d4fe465ef60042293f5723bf4a001d8e75f26e517af2b55e6efaef9c0db1f6"
    82    ],
    83    "cmdline": "console=ttymxc1,115200 root=/dev/mmcblk1p1 rootwait rw"
    84  }
    85  ```
    86  
    87  TamaGo unikernel boot
    88  ---------------------
    89  
    90  > :warning: this is currently experimental, and requires that the HW RNG is
    91  > not reinitialised.
    92  
    93  To load a TamaGo unikernel, the bootloader only needs the path to the ELF
    94  binary along with its SHA256 hash for validation.
    95  
    96  Example `/boot/armory-boot.conf` configuration file for loading a TamaGo
    97  unikernel:
    98  
    99  ```
   100  {
   101    "unikernel": [
   102      "/boot/tamago-example",
   103      "e6de9214249dd7989b4056372424e84b273ff4e5d2410fa12ac230ddaf22690a"
   104    ]
   105  }
   106  ```
   107  
   108  Secure Boot
   109  ===========
   110  
   111  On secure booted systems the `imx_signed` target should be used instead with the relevant
   112  [`HAB_KEYS`](https://github.com/usbarmory/usbarmory/wiki/Secure-boot-(Mk-II)) set.
   113  
   114  Additionally, to maintain the chain of trust, the `PUBLIC_KEY` environment
   115  variable must be set with either a [signify](https://man.openbsd.org/signify)
   116  or [minisign](https://jedisct1.github.io/minisign/) public key to enable
   117  configuration file signature verification.
   118  
   119  Example key generation (signify):
   120  
   121  ```
   122  signify -G -p armory-boot.pub -s armory-boot.sec
   123  ```
   124  
   125  Example key generation (minisign):
   126  
   127  ```
   128  minisign -G -p armory-boot.pub -s armory-boot.sec
   129  ```
   130  
   131  Compilation with embedded key:
   132  
   133  ```
   134  make CROSS_COMPILE=arm-none-eabi- imx_signed BOOT=uSD START=5242880 PUBLIC_KEY=<last line of armory-boot.pub> HAB_KEYS=<path>
   135  ```
   136  
   137  When `armory-boot` is compiled with the `PUBLIC_KEY` variable, a signature for
   138  the configuration file must be created in `/boot/armory-boot.conf.sig` using
   139  with the corresponding secret key.
   140  
   141  Example signature generation (signify):
   142  
   143  ```
   144  signify -S -s armory-boot.sec -m armory-boot.conf -x armory-boot.conf.sig
   145  ```
   146  
   147  Example signature generation (minisign):
   148  
   149  ```
   150  minisign -S -s armory-boot.sec -m armory-boot.conf -x armory-boot.conf.sig
   151  ```
   152  
   153  LED status
   154  ==========
   155  
   156  The [USB armory Mk II](https://github.com/usbarmory/usbarmory/wiki) LEDs
   157  are used, in sequence, as follows:
   158  
   159  | Boot sequence                   | Blue | White |
   160  |---------------------------------|------|-------|
   161  | 0. initialization               | off  | off   |
   162  | 1. boot media detected          | on   | off   |
   163  | 2. kernel verification complete | on   | on    |
   164  | 3. jumping to kernel image      | off  | off   |
   165  
   166  Authors
   167  =======
   168  
   169  Andrea Barisani
   170  andrea.barisani@f-secure.com | andrea@inversepath.com
   171  
   172  License
   173  =======
   174  
   175  armory-boot | https://github.com/usbarmory/armory-boot
   176  Copyright (c) F-Secure Corporation
   177  
   178  These source files are distributed under the BSD-style license found in the
   179  [LICENSE](https://github.com/usbarmory/armory-boot/blob/master/LICENSE) file.