1# Secure Flash Update Mechanism 2 3This document describes the OpenBmc software implementing the secure flash 4update mechanism. 5 6The primary details are 7[here](https://github.com/openbmc/docs/blob/master/designs/firmware-update-via-blobs.md). 8 9## Building and using the host-tool 10 11This repo contains a host-tool implementation for talking to the corresponding 12BMC blob handler. 13 14### Building the host-tool 15 16The host-tool depends on ipmi-blob-tool and pciutils. 17 18#### Building libpciaccess 19 20Check out the 21[xorg-macros source](https://gitlab.freedesktop.org/xorg/util/macros). 22 23Then run these commands in the source directory. 24 25``` 26./autogen.sh --prefix=/usr 27make install 28``` 29 30Check out the 31[libpciaccess source](https://gitlab.freedesktop.org/xorg/lib/libpciaccess). 32 33Then run these commands in the source directory. 34 35``` 36./autogen.sh 37make 38make install 39``` 40 41#### Building ipmi-blob-tool 42 43Check out the 44[ipmi-blob-tool source](https://github.com/openbmc/ipmi-blob-tool). 45 46Then run these commands in the source directory. 47 48``` 49./bootstrap.sh 50./configure 51make 52make install 53``` 54 55#### Building fmtlib 56 57Check out the [fmtlib source](https://github.com/fmtlib/fmt). 58 59Then run these commands in the source directory. 60 61``` 62mkdir build && cd build 63cmake .. 64make 65make install 66``` 67 68#### Building span-lite 69 70Check out the [span-lite source](https://github.com/martinmoene/span-lite). 71 72Then run these commands in the source directory. 73 74``` 75mkdir build && cd build 76cmake .. 77make 78make install 79``` 80 81#### Building stdplus 82 83Check out the [stdplus source](https://github.com/openbmc/stdplus). 84 85Then run these commands in the source directory. 86 87``` 88meson setup -Dexamples=false -Dtests=disabled builddir 89ninja -C builddir 90ninja -C builddir install 91``` 92 93#### Building burn_my_bmc (the host-tool) 94 95Check out the 96[phosphor-ipmi-flash source](https://github.com/openbmc/phosphor-ipmi-flash). 97 98Then run these commands in the source directory. 99 100``` 101./bootstrap.sh 102./configure --disable-build-bmc-blob-handler 103make 104make install 105``` 106 107_NOTE:_ When building from the OpenBMC SDK your configuration call will be: 108 109``` 110./configure --enable-oe-sdk --host "$(uname -m)" --disable-build-bmc-blob-handler AR=x86_64-openbmc-linux-gcc-ar RANLIB=x86_64-openbmc-linux-gcc-ranlib 111``` 112 113### Parameters 114 115The host-tool has parameters that let the caller specify every required detail. 116 117The required parameters are: 118 119| Parameter | Options | Meaning | 120| ----------- | ------------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------- | 121| `command` | `update` | The tool should try to update the BMC firmware. | 122| `interface` | `ipmibt`, `ipmilpc`, `ipmipci`, `ipminet`, `ipmipci-skip-bridge-disable` | The data transport mechanism, typically `ipmilpc`. The `ipmipci-skip-bridge-disable` is `ipmipci` but does not disable the bridge after. | 123| `image` | path | The BMC firmware image file (or tarball) | 124| `sig` | path | The path to a signature file to send to the BMC along with the image file. | 125| `type` | blob ending | The ending of the blob id. For instance `/flash/image` becomes a type of `image`. | 126 127If you're using an LPC data transfer mechanism, you'll need two additional 128parameters: `address` and `length`. These values indicate where on the host 129you've reserved memory to be used for the transfer window. 130 131If you're using a net data transfer mechanism, you'll also need two additional 132parameters: `hostname` and `port`. These specify which address and port the tool 133should attempt to connect to the BMC using. If unspecified, the `port` option 134defaults to 623, the same port as IPMI LAN+. 135 136## Introduction 137 138This supports three methods of providing the image to stage. You can send the 139file over IPMI packets, which is a very slow process. A 32-MiB image can take ~3 140hours to send via this method. This can be done in <1 minutes via the PCI or net 141bridge, or just a few minutes via LPC depending on the size of the mapped area. 142 143This is implemented as a phosphor blob handler. 144 145The image must be signed via the production or development keys, the former 146being required for production builds. The image itself and the image signature 147are separately sent to the BMC for verification. The verification package source 148is beyond the scope of this design. 149 150Basically the IPMI OEM handler receives the image in one fashion or another and 151then triggers the `verify_image` service. Then, the user polls until the result 152is reported. This is because the image verification process can exceed 10 153seconds. 154 155### Using Legacy Images 156 157The image flashing mechanism itself is the initramfs stage during reboot. It 158will check for files named "`image-*`" and flash them appropriately for each 159name to section. The IPMI command creates a file `/run/initramfs/bmc-image` and 160writes the contents there. It was found that writing it in /tmp could cause OOM 161errors moving it on low memory systems, whereas renaming a file within the same 162folder seems to only update the directory inode's contents. 163 164### Using UBI 165 166The staging file path can be controlled via software configuration. The image is 167assumed to be the tarball contents and is written into `/tmp/{tarball_name}.gz` 168 169TODO: Flesh out the UBI approach. 170 171## Configuration 172 173To use `phosphor-ipmi-flash` a platform must provide a configuration. A platform 174can configure multiple interfaces, such as both lpc and pci. However, a platform 175should only configure either static layout updates, or ubi. If enabling lpc, the 176platform must specify either aspeed or nuvoton. The system also supports 177receiving BIOS updates. 178 179The following are the two primary configuration options, which control how the 180update is treated. 181 182| Option | Meaning | 183| ------------------------ | ------------------------------------------------------- | 184| `--enable-static-layout` | Enable treating the update as a static layout update. | 185| `--enable-tarball-ubi` | Enable treating the update as a tarball for UBI update. | 186| `--enable-host-bios` | Enable receiving the update for a host bios update. | 187 188The following are configuration options for how the host and BMC are meant to 189transfer the data. By default, the data-in-IPMI mechanism is enabled. 190 191There are three configurable data transport mechanisms, either staging the bytes 192via the LPC memory region, the PCI-to-AHB memory region, or sending over a 193network connection. Because there is only one `MAPPED_ADDRESS` variable at 194present, a platform should not configure LPC and P2A at the same time. The 195platform's device-tree may have the region locked to a specific driver 196(lpc-aspeed-ctrl), preventing the region from other use. 197 198**_NOTE:_** It will likely be possible to configure both LPC and P2A in the near 199future. 200 201| Variable | Default | Meaning | 202| ---------------- | ------- | -------------------------------------------------------------------- | 203| `MAPPED_ADDRESS` | 0 | The address used for mapping P2A or LPC into the BMC's memory-space. | 204 205If a platform enables p2a as the transport mechanism, a specific vendor must be 206selected via the following configuration option. Currently, only one is 207supported. 208 209| Option | Meaning | 210| --------------------- | ---------------------- | 211| `--enable-aspeed-p2a` | Use with ASPEED parts. | 212 213If a platform enables lpc as the transport mechanism, a specific vendor must be 214selected via the following configuration option. Currently, only two are 215supported. 216 217| Option | Meaning | 218| ---------------------- | ----------------------- | 219| `--enable-aspeed-lpc` | Use with ASPEED parts. | 220| `--enable-nuvoton-lpc` | Use with Nuvoton parts. | 221 222A platform may also enable the network transport mechanism. 223 224NOTE: This mechanism is only intended to be used in-band and not exposed 225externally, as it doesn't implement any encryption or integrity verification. 226 227| Option | Meaning | 228| --------------------- | --------------------------- | 229| `--enable-net-bridge` | Enable net transport bridge | 230 231There are also options to control an optional clean up mechanism. 232 233| Option | Meaning | 234| ------------------------- | ------------------------------------------------ | 235| `--enable-cleanup-delete` | Provide a simple blob id that deletes artifacts. | 236 237If the update mechanism desired is simply a BMC reboot, a platform can just 238enable that directly. 239 240| Option | Meaning | 241| ------------------------ | -------------------------------------- | 242| `--enable-reboot-update` | Enable use of reboot update mechanism. | 243 244If you would like the update status to be tracked with a status file, this 245option can be enabled. Note that `--enable-update-status` option and the above 246`--enable-reboot-update` option cannot be enabled at the same time. 247 248| Option | Meaning | 249| ------------------------ | --------------------------------- | 250| `--enable-update-status` | Enable use of update status file. | 251 252If you would like to use host memory access to update on a PPC platform, this 253configuration option needs to be enabled. 254 255| Option | Meaning | 256| -------------- | ------------------------------ | 257| `--enable-ppc` | Enable PPC host memory access. | 258 259### Internal Configuration Details 260 261The following variables can be set to whatever you wish, however they have 262usable default values. 263 264| Variable | Default | Meaning | 265| ----------------------------- | ----------------------------------------- | ------------------------------------------------------------------------- | 266| `STATIC_HANDLER_STAGED_NAME` | `/run/initramfs/bmc-image` | The filename where to write the staged firmware image for static updates. | 267| `TARBALL_STAGED_NAME` | `/tmp/image-update.tar` | The filename where to write the UBI update tarball. | 268| `HASH_FILENAME` | `/tmp/bmc.sig` | The file to use for the hash provided. | 269| `PREPARATION_DBUS_SERVICE` | `phosphor-ipmi-flash-bmc-prepare.target` | The systemd target started when the host starts to send an update. | 270| `VERIFY_STATUS_FILENAME` | `/tmp/bmc.verify` | The file checked for the verification status. | 271| `VERIFY_DBUS_SERVICE` | `phosphor-ipmi-flash-bmc-verify.target` | The systemd target started for verification. | 272| `UPDATE_DBUS_SERVICE` | `phosphor-ipmi-flash-bmc-update.target` | The systemd target started for updating the BMC. | 273| `UPDATE_STATUS_FILENAME` | `/tmp/bmc.update` | The file checked for the update status. | 274| `BIOS_STAGED_NAME` | `/tmp/bios-image` | The file to use for staging the bios firmware update. | 275| `BIOS_VERIFY_STATUS_FILENAME` | `/tmp/bios.verify` | The file checked for the verification status. | 276| `PREPARATION_BIOS_TARGET` | `phosphor-ipmi-flash-bios-prepare.target` | The systemd target when the host starts to send an update. | 277| `VERIFY_BIOS_TARGET` | `phosphor-ipmi-flash-bios-verify.target` | The systemd target started for verification. | 278| `UPDATE_BIOS_TARGET` | `phosphor-ipmi-flash-bios-update.target` | The systemd target started for updating the BIOS. | 279 280## JSON Configuration 281 282Read the [details](bmc_json_config.md) of the json configuration. The json 283configurations are used to configure the BMC's flash handler behaviors. 284 285## Flash State Machine Details 286 287[This document](ipmi_flash.md) describes the details of the state machine 288implemented and how different interactions with it will respond. This also 289describes how a host-side tool is expected to talk to it (triggering different 290states and actions). 291