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 pciutils 18 19Check out the [pciutils source](https://github.com/pciutils/pciutils). 20 21Then run these commands in the source directory. 22``` 23make SHARED=yes 24make SHARED=yes install 25make install-lib 26``` 27 28#### Building ipmi-blob-tool 29 30Check out the [ipmi-blob-tool source](https://github.com/openbmc/ipmi-blob-tool). 31 32Then run these commands in the source directory. 33 34``` 35./bootstrap.sh 36./configure 37make 38make install 39``` 40 41#### Building burn_my_bmc (the host-tool) 42 43Check out the [phosphor-ipmi-flash source](https://github.com/openbmc/phosphor-ipmi-flash). 44 45Then run these commands in the source directory. 46 47``` 48./bootstrap.sh 49./configure --disable-build-bmc-blob-handler 50make 51make install 52``` 53 54### Parameters 55 56The host-tool has parameters that let the caller specify every required detail. 57 58The required parameters are: 59 60 Parameter | Options | Meaning 61----------- | -------- | ------- 62`command` | `update` | The tool should try to update the BMC firmware. 63`interface` | `ipmibt`, `ipmilpc`, `ipmipci` | The data transport mechanism, typically `ipmilpc` 64`image` | path | The BMC firmware image file (or tarball) 65`sig` | path | The path to a signature file to send to the BMC along with the image file. 66`type` | `static`, `ubitar` | Whether we're updating via the static layout or UBI tarball. 67 68If you're using an LPC data transfer mechanism, you'll need two additional 69parameters: `address` and `length`. These values indicate where on the host 70you've reserved memory to be used for the transfer window. 71 72## Introduction 73 74This supports two methods of providing the image to stage. You can send the 75file over IPMI packets, which is a very slow process. A 32-MiB image can take 76~3 hours to send via this method. This can be done in <1 minutes via the PCI 77bridge, or just a few minutes via LPC depending on the size of the mapped area. 78 79This is implemented as a phosphor blob handler. 80 81The image must be signed via the production or development keys, the former 82being required for production builds. The image itself and the image signature 83are separately sent to the BMC for verification. The verification package 84source is beyond the scope of this design. 85 86Basically the IPMI OEM handler receives the image in one fashion or another and 87then triggers the `verify_image` service. Then, the user polls until the result 88is reported. This is because the image verification process can exceed 10 89seconds. 90 91### Using Legacy Images 92 93The image flashing mechanism itself is the initramfs stage during reboot. It 94will check for files named "`image-*`" and flash them appropriately for each 95name to section. The IPMI command creates a file `/run/initramfs/bmc-image` and 96writes the contents there. It was found that writing it in /tmp could cause OOM 97errors moving it on low memory systems, whereas renaming a file within the same 98folder seems to only update the directory inode's contents. 99 100### Using UBI 101 102The staging file path can be controlled via software configuration. The image 103is assumed to be the tarball contents and is written into `/tmp/{tarball_name}.gz` 104 105TODO: Flesh out the UBI approach. 106 107## Configuration 108 109To use `phosphor-ipmi-flash` a platform must provide a configuration. A 110platform can configure multiple interfaces, such as both lpc and pci. However, 111a platform should only configure either static layout updates, or ubi. If 112enabling lpc, the platform must specify either aspeed or nuvoton. 113 114The following are the two primary configuration options, which control how the 115update is treated. 116 117Option | Meaning 118------------------------ | ------- 119`--enable-static-layout` | Enable treating the update as a static layout update. 120`--enable-tarball-ubi` | Enable treating the update as a tarball for UBI update. 121 122The following are configuration options for how the host and BMC are meant to 123transfer the data. By default, the data-in-IPMI mechanism is enabled. 124 125There are two configurable data transport mechanisms, either staging the bytes 126via the LPC memory region, or the PCI-to-AHB memory region. Because there is 127only one `MAPPED_ADDRESS` variable at present, a platform should only configure 128one. The platform's device-tree may have the region locked to a specific 129driver (lpc-aspeed-ctrl), preventing the region from other use. 130 131***NOTE:*** It will likely be possible to configure both in the near future. 132 133Variable | Default | Meaning 134--------------------- | ------- | ------- 135`MAPPED_ADDRESS` | 0 | The address used for mapping P2A or LPC into the BMC's memory-space. 136 137Option | Meaning 138--------------------- | ------- 139`--enable-pci-bridge` | Enable the PCI-to-AHB transport option. 140`--enable-lpc-bridge` | Enable the LPC-to-AHB transport option. 141 142If a platform enables p2a as the transport mechanism, a specific vendor must be 143selected via the following configuration option. Currently, only one is 144supported. 145 146Option | Meaning 147-----------------------| ------- 148`--enable-aspeed-p2a` | Use with ASPEED parts. 149 150If a platform enables lpc as the transport mechanism, a specific vendor must be 151selected via the following configuration option. Currently, only two are 152supported. 153 154Option | Meaning 155---------------------- | ------- 156`--enable-aspeed-lpc` | Use with ASPEED parts. 157`--enable-nuvoton-lpc` | Use with Nuvoton parts. 158 159There are also options to control an optional clean up mechanism. 160 161Option | Meaning 162------------------------- | ------- 163`--enable-cleanup-delete` | Provide a simple blob id that deletes artifacts. 164 165If the update mechanism desired is simply a BMC reboot, a platform can just 166enable that directly. 167 168Option | Meaning 169------------------------ | ------- 170`--enable-reboot-update` | Enable use of reboot update mechanism. 171 172### Internal Configuration Details 173 174The following variables can be set to whatever you wish, however they have 175usable default values. 176 177Variable | Default | Meaning 178---------------------------- | -------------------------- | ------------------------------------------------------------------------- 179`STATIC_HANDLER_STAGED_NAME` | `/run/initramfs/bmc-image` | The filename where to write the staged firmware image for static updates. 180`TARBALL_STAGED_NAME` | `/tmp/image-update.tar` | The filename where to write the UBI update tarball. 181`HASH_FILENAME` | `/tmp/bmc.sig` | The file to use for the hash provided. 182`PREPARATION_DBUS_SERVICE` | `prepare_update.service` | The systemd service started when the host starts to send an update. 183`VERIFY_STATUS_FILENAME` | `/tmp/bmc.verify` | The file checked for the verification status. 184`VERIFY_DBUS_SERVICE` | `verify_image.service` | The systemd service started for verification. 185`UPDATE_DBUS_SERVICE` | `update_bmc.service` | The systemd service started for updating the BMC. 186 187## Flash State Machine Details 188 189[This document](ipmi_flash.md) describes the details of the state machine 190implemented and how different interactions with it will respond. This also 191describes how a host-side tool is expected to talk to it (triggering different 192states and actions). 193