github.com/transparency-dev/armored-witness-applet@v0.1.1/README.md (about)

     1  # ArmoredWitness Applet
     2  
     3  This repo contains code for a GoTEE Trusted Applet which implements
     4  a witness. It's intended to be used with the Trusted OS found at
     5  https://github.com/transparency-dev/armored-witness-os.
     6  
     7  ## Introduction
     8  
     9  TODO.
    10  
    11  ## Supported hardware
    12  
    13  The following table summarizes currently supported SoCs and boards.
    14  
    15  | SoC          | Board                                                               | SoC package                                                              | Board package                                                                    |
    16  |--------------|---------------------------------------------------------------------|--------------------------------------------------------------------------|----------------------------------------------------------------------------------|
    17  | 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) |
    18  | 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) |
    19  
    20  The GoTEE [syscall](https://github.com/usbarmory/GoTEE/blob/master/syscall/syscall.go)
    21  interface is implemented for communication between the Trusted OS and Trusted
    22  Applet.
    23  
    24  When launched, the witness applet is reachable via SSH through the first
    25  Ethernet port.
    26  
    27  ```none
    28  $ ssh ta@10.0.0.1
    29  
    30  date            (time in RFC339 format)?                 # show/change runtime date and time
    31  dns             <fqdn>                                   # resolve domain (requires routing)
    32  exit, quit                                               # close session
    33  hab             <hex SRK hash>                           # secure boot activation (*irreversible*)
    34  help                                                     # this help
    35  led             (white|blue|yellow|green) (on|off)       # LED control
    36  mmc             <hex offset> <size>                      # MMC card read
    37  reboot                                                   # reset device
    38  stack                                                    # stack trace of current goroutine
    39  stackall                                                 # stack trace of all goroutines
    40  status                                                   # status information
    41  
    42  >
    43  ```
    44  
    45  The witness can be also executed under QEMU emulation, including networking
    46  support (requires a `tap0` device routing the Trusted Applet IP address),
    47  through `armored-witness-os`.
    48  
    49  > :warning: emulated runs perform partial tests due to lack of full hardware
    50  > support by QEMU.
    51  
    52  ```none
    53  make DEBUG=1 trusted_os && make qemu
    54  ...
    55  00:00:00 tamago/arm • TEE security monitor (Secure World system/monitor)
    56  00:00:00 SM applet verification
    57  00:00:01 SM applet verified
    58  00:00:01 SM loaded applet addr:0x90000000 entry:0x9007751c size:14228514
    59  00:00:01 SM starting mode:USR sp:0xa0000000 pc:0x9007751c ns:false
    60  00:00:02 tamago/arm • TEE user applet
    61  00:00:02 TA MAC:1a:55:89:a2:69:41 IP:10.0.0.1 GW:10.0.0.2 DNS:8.8.8.8:53
    62  00:00:02 TA requesting SM status
    63  00:00:02 ----------------------------------------------------------- Trusted OS ----
    64  00:00:02 Secure Boot ............: false
    65  00:00:02 Runtime ................: tamago/arm
    66  00:00:02 Link ...................: false
    67  00:00:02 TA starting ssh server (SHA256:eeMIwwN/zw1ov1BvO6sW3wtYi463sq+oLgKhmAew1WE) at 10.0.0.1:22
    68  ```
    69  
    70  ## Trusted Applet authentication
    71  
    72  To maintain the chain of trust the Trusted Applet must be signed and logged.
    73  To this end, two [note](https://pkg.go.dev/golang.org/x/mod/sumdb/note) signing keys
    74  must be generated.
    75  
    76  ```bash
    77  $ go run github.com/transparency-dev/serverless-log/cmd/generate_keys@HEAD \
    78    --key_name="DEV-TrustedApplet" \
    79    --out_priv=armored-witness-applet.sec \
    80    --out_pub=armored-witness-applet.pub
    81  ```
    82  
    83  The corresponding public key files will be built into the Trusted OS to verify the Applet.
    84  
    85  ## Firmware transparency
    86  
    87  All ArmoredWitness firmware artefacts need to be added to a firmware transparency log.
    88  
    89  The provided `Makefile` has support for maintaining a local firmware transparency
    90  log on disk. This is intended to be used for development only.
    91  
    92  In order to use this functionality, a log key pair can be generated with the
    93  following command:
    94  
    95  ```bash
    96  $ go run github.com/transparency-dev/serverless-log/cmd/generate_keys@HEAD \
    97    --key_name="DEV-Log" \
    98    --out_priv=armored-witness-log.sec \
    99    --out_pub=armored-witness-log.pub
   100  ```
   101  
   102  ## Building and executing on ARM targets
   103  
   104  Download and install the
   105  [latest TamaGo binary release](https://github.com/usbarmory/tamago-go/releases/latest).
   106  
   107  ### Building the applet
   108  
   109  Ensure the following environment variables are set:
   110  
   111  | Variable                | Description
   112  |-------------------------|------------
   113  | `APPLET_PRIVATE_KEY1`   | Path to Trusted Applet firmware signing key. Used by the Makefile to sign the applet.
   114  | `LOG_PRIVATE_KEY`       | Path to log signing key. Used by Makefile to add the new applet firmware to the local dev log.
   115  | `LOG_ORIGIN`            | FT log origin string. Used by Makefile to update the local dev log.
   116  | `DEV_LOG_DIR`           | Path to directory in which to store the dev FT log files.
   117  
   118  The applet firmware image can then be built, signed, and logged with the following command:
   119  
   120  ```bash
   121  make trusted_applet log_applet
   122  ```
   123  
   124  Final executables are created in the `bin` subdirectory, `trusted_applet.elf`
   125  should be used for loading through `armored-witness-os`.
   126  
   127  Firmware transparency artefacts will be written into `${DEV_LOG_DIR}`.
   128  
   129  ### Encrypted RAM support
   130  
   131  Only on i.MX6UL P/Ns, the `BEE` environment variable must be set to match
   132  `armored-witness-boot` and `armored-witness-os` compilation options in case AES
   133  CTR encryption for all external RAM, using TamaGo
   134  [bee package](https://pkg.go.dev/github.com/usbarmory/tamago/soc/nxp/bee),
   135  is configured at boot.
   136  
   137  The following targets are available:
   138  
   139  | `TARGET`    | Board            | Executing and debugging                                                                                  |
   140  |-------------|------------------|----------------------------------------------------------------------------------------------------------|
   141  | `usbarmory` | UA-MKII-LAN      | [usbarmory/mk2](https://github.com/usbarmory/tamago/tree/master/board/usbarmory)                         |
   142  
   143  The targets support native (see relevant documentation links in the table above)
   144  as well as emulated execution (e.g. `make qemu`).
   145  
   146  ### Debugging
   147  
   148  An optional Serial over USB console can be used to access Trusted OS and
   149  Trusted Applet logs, it can be enabled when compiling with the `DEBUG`
   150  environment variable set:
   151  
   152  ```bash 
   153  make DEBUG=1 trusted_applet log_applet
   154  ```
   155  
   156  The Serial over USB console can be accessed from a Linux host as follows:
   157  
   158  ```bash
   159  picocom -b 115200 -eb /dev/ttyACM0 --imap lfcrlf
   160  ```
   161  
   162  ## Trusted Applet installation
   163  
   164  Installing the various firmware images onto the device can be accomplished using the
   165  [provision tool](https://github.com/transparency-dev/armored-witness/tree/main/cmd/provision).
   166  
   167  ## LED status
   168  
   169  The [USB armory Mk II](https://github.com/usbarmory/usbarmory/wiki) LEDs
   170  are used, in sequence, as follows:
   171  
   172  | Boot sequence                   | Blue | White |
   173  |---------------------------------|------|-------|
   174  | 0. initialization               | off  | off   |
   175  | 1. trusted applet verified      | off  | on    |
   176  | 2. trusted applet execution     | on   | on    |
   177