README.md
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