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