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