Documentation/security/vboot/index.md

   1 # vboot - Verified Boot Support
   2
   3 Google's verified boot support consists of:
   4
   5 *   A root of trust
   6 *   Special firmware layout
   7 *   Firmware verification
   8 *   Firmware measurements
   9 *   A firmware update mechanism
  10 *   Specific build flags
  11 *   Signing the coreboot image
  12
  13 Google's vboot verifies the firmware and places measurements within the TPM.
  14
  15 ```{toctree}
  16 :maxdepth: 1
  17
  18 List of supported Devices <list_vboot.md>
  19 ```
  20
  21 ***
  22
  23 ## Root of Trust
  24
  25 When using vboot, the root-of-trust is basically the read-only portion of the
  26 SPI flash. The following items factor into the trust equation:
  27
  28 * The GCC compiler must reliably translate the code into machine code
  29   without inserting any additional code (virus, backdoor, etc.)
  30 * The CPU must reliably execute the reset sequence and instructions as
  31   documented by the CPU manufacturer.
  32 * The SPI flash must provide only the code programmed into it to the CPU
  33   without providing any alternative reset vector or code sequence.
  34 * The SPI flash must honor the write-protect input and protect the specified
  35   portion of the SPI flash from all erase and write accesses.
  36
  37 The firmware is typically protected using the write-protect pin on the SPI
  38 flash part and setting some of the write-protect bits in the status register
  39 during manufacturing. The protected area is platform specific and for x86
  40 platforms is typically 1/4th of the SPI flash part size.
  41 Because this portion of the SPI flash is hardware write protected, it is not
  42 possible to update this portion of the SPI flash in the field, without altering
  43 the system to eliminate the ground connection to the SPI flash write-protect pin.
  44 Without hardware modifications, this portion of the SPI flash maintains the
  45 manufactured state during the system's lifetime.
  46
  47 ***
  48
  49 ## Firmware Layout
  50
  51 Several sections are added to the firmware layout to support vboot:
  52
  53 * Read-only section
  54 * Google Binary Blob (GBB) area
  55 * Read/write section A
  56 * Read/write section B
  57
  58 The following sections describe the various portions of the flash layout.
  59
  60 ### Read-Only Section
  61
  62 The read-only section contains a coreboot file system (CBFS) that contains all
  63 of the boot firmware necessary to perform recovery for the system. This firmware
  64 is typically protected using the write-protect pin on the SPI flash part and
  65 setting some of the write-protect bits in the status register during
  66 manufacturing.
  67 The protected area is typically 1/4th of the SPI flash part size and must cover
  68 the entire read-only section which consists of:
  69
  70 * Vital Product Data (VPD) area
  71 * Firmware ID area
  72 * Google Binary Blob (GBB) area
  73 * coreboot file system containing read-only recovery firmware
  74
  75 ### Google Binary Blob (GBB) Area
  76
  77 The GBB area is part of the read-only section. This area contains a 4096 or 8192
  78 bit public root RSA key that is used to verify the *VBLOCK* area to obtain the
  79 firmware signing key.
  80
  81 ### Recovery Firmware
  82
  83 The recovery firmware is contained within a coreboot file system and consists of:
  84
  85 * reset vector
  86 * bootblock
  87 * verstage
  88 * romstage
  89 * postcar
  90 * ramstage
  91 * payload
  92 * flash map file
  93 * config file
  94 * processor specific files:
  95   * Microcode
  96   * fspm.bin
  97   * fsps.bin
  98
  99 The recovery firmware is written during manufacturing and typically contains
 100 code to write the storage device (eMMC device or hard disk). The recovery image
 101 is usually contained on a socketed device such as a USB flash drive or an
 102 SD card. Depending upon the payload firmware doing the recovery, it may be
 103 possible for the user to interact with the system to specify the recovery
 104 image path. Part of the recovery is also to write the A and B areas of the SPI
 105 flash device to boot the system.
 106
 107 ### Read/Write Section
 108
 109 The read/write sections contain an area which contains the firmware signing
 110 key and signature and an area containing a coreboot file system with a subset
 111 of the firmware. The firmware files in *FW_MAIN_A* and *FW_MAIN_B* are:
 112
 113 * romstage
 114 * postcar
 115 * ramstage
 116 * payload
 117 * config file
 118 * processor specific files:
 119   * Microcode
 120   * fspm.bin
 121   * fsps.bin
 122
 123 The firmware subset enables most issues to be fixed in the field with firmware
 124 updates. The firmware files handle memory and most of silicon initialization.
 125 These files also produce the tables which get passed to the operating system.
 126
 127 ***
 128
 129 ## Firmware Updates
 130
 131 The read/write sections exist in one of three states:
 132
 133 * Invalid
 134 * Ready to boot
 135 * Successfully booted
 136
 137
 138 Firmware updates are handled by the operating system by writing any read/write
 139 section that is not in the "successfully booted" state. Upon the next reboot,
 140 vboot determines the section to boot. If it finds one in the "ready to boot"
 141 state then it attempts to boot using that section. If the boot fails then
 142 vboot marks the section as invalid and attempts to fall back to a read/write
 143 section in the "successfully booted" state. If vboot is not able to find a
 144 section in the "successfully booted" state then vboot enters recovery mode.
 145
 146 Only the operating system is able to transition a section from the
 147 "ready to boot" state to the "successfully booted" state.
 148 The transition is typically done after the operating system has been running
 149 for a while indicating that successful boot was possible and the operating
 150 system is stable.
 151
 152 Note that as long as the SPI write protection is in place then the system
 153 is always recoverable. If the flash update fails then the system will continue
 154 to boot using the previous read/write area. The same is true if coreboot passes
 155 control to the payload or the operating system and then the boot fails. In the
 156 worst case, the SPI flash gets totally corrupted in which case vboot fails the
 157 signature checks and enters recovery mode. There are no times where the SPI
 158 flash is exposed and the reset vector or part of the recovery firmware gets
 159 corrupted.
 160
 161 ***
 162
 163 ## Build Flags
 164
 165 The following *Kconfig* values need to be selected to enable vboot:
 166
 167 * COLLECT_TIMESTAMPS
 168 * VBOOT
 169
 170 The starting stage needs to be specified by selecting either
 171 VBOOT_STARTS_IN_BOOTBLOCK or VBOOT_STARTS_IN_ROMSTAGE.
 172
 173 If vboot starts in bootblock then vboot may be built as a separate stage by
 174 selecting `VBOOT_SEPARATE_VERSTAGE`. Additionally, if static RAM is too small
 175 to fit both verstage and romstage then selecting `VBOOT_RETURN_FROM_VERSTAGE`
 176 enables bootblock to reuse the RAM occupied by verstage for romstage.
 177
 178 Non-volatile flash is needed for vboot operation. This flash area may be in
 179 CMOS, the EC, or in a read/write area of the SPI flash device.
 180 Select one of the following:
 181
 182 * `VBOOT_VBNV_CMOS`
 183 * `VBOOT_VBNV_FLASH`
 184
 185 More non-volatile storage features may be found in `security/vboot/Kconfig`.
 186
 187 A TPM is also required for vboot operation.
 188 TPMs are available in `drivers/i2c/tpm` and `drivers/pc80/tpm`.
 189
 190 In addition to adding the coreboot files into the read-only region,
 191 enabling vboot causes the build script to add the read/write files into
 192 coreboot file systems in *FW_MAIN_A* and *FW_MAIN_B*.
 193
 194 **RO_REGION_ONLY**
 195
 196 The files added to this list will only be placed in the read-only region and
 197 not into the read/write coreboot file systems in *FW_MAIN_A* and *FW_MAIN_B*.
 198
 199 **VBOOT_ENABLE_CBFS_FALLBACK**
 200
 201 Normally coreboot will use the active read/write coreboot file system for all
 202 of it's file access when vboot is active and is not in recovery mode.
 203
 204 When the `VBOOT_ENABLE_CBFS_FALLBACK` option is enabled the cbfs file system will
 205 first try to locate a file in the active read/write file system. If the file
 206 doesn't exist here the file system will try to locate the file in the read-only
 207 file system.
 208
 209 This option can be used to prevent duplication of static data. Files can be
 210 removed from the read/write partitions by adding them to the `RO_REGION_ONLY`
 211 config. If a file needs to be changed in a later stage simply remove it from
 212 this list.
 213
 214 ***
 215
 216 ## Signing the coreboot Image
 217
 218 The following command script is an example of how to sign the coreboot image
 219 file. This script is used on the Intel Galileo board and creates the *GBB* area
 220 and inserts it into the coreboot image. It also updates the *VBLOCK* areas with
 221 the firmware signing key and the signature for the *FW_MAIN* firmware.
 222 More details are available in `3rdparty/vboot/README`.
 223
 224 ```bash
 225 #!/bin/sh
 226 #
 227 #  The necessary tools were built and installed using the following commands:
 228 #
 229 #        pushd 3rdparty/vboot
 230 #        make
 231 #        sudo make install
 232 #        popd
 233 #
 234 #  The keys were made using the following command
 235 #
 236 #        3rdparty/vboot/scripts/keygeneration/create_new_keys.sh  \
 237 #                --output $PWD/keys
 238 #
 239 #
 240 #  The "magic" numbers below are derived from the GBB section in
 241 #  src/mainboard/intel/galileo/vboot.fmd.
 242 #
 243 #  GBB Header Size:     0x80
 244 #  GBB Offset:      0x611000, 4KiB block number: 1553 (0x611)
 245 #  GBB Length:       0x7f000, 4KiB blocks:        127  (0x7f)
 246 #  COREBOOT Offset: 0x690000, 4KiB block number: 1680 (0x690)
 247 #  COREBOOT Length: 0x170000, 4KiB blocks:        368 (0x170)
 248 #
 249 #  0x7f000 (GBB Length) = 0x80 + 0x100 + 0x1000 + 0x7ce80 + 0x1000
 250 #
 251 #  Create the GBB area blob
 252 #  Parameters: hwid_size,rootkey_size,bmpfv_size,recoverykey_size
 253 #
 254 gbb_utility -c 0x100,0x1000,0x7ce80,0x1000 gbb.blob
 255
 256 #
 257 #  Copy from the start of the flash to the GBB region into the signed flash
 258 #  image.
 259 #
 260 #  1553 * 4096 = 0x611 * 0x1000 = 0x611000, size of area before GBB
 261 #
 262 dd  conv=fdatasync  ibs=4096  obs=4096  count=1553  \
 263 if=build/coreboot.rom  of=build/coreboot.signed.rom
 264
 265 #
 266 #  Append the empty GBB area to the coreboot.rom image.
 267 #
 268 #  1553 * 4096 = 0x611 * 0x1000 = 0x611000, offset to GBB
 269 #
 270 dd  conv=fdatasync  obs=4096  obs=4096  seek=1553  if=gbb.blob  \
 271 of=build/coreboot.signed.rom
 272
 273 #
 274 #  Append the rest of the read-only region into the signed flash image.
 275 #
 276 #  1680 * 4096 = 0x690 * 0x1000 = 0x690000, offset to COREBOOT area
 277 #   368 * 4096 = 0x170 * 0x1000 = 0x170000, length of COREBOOT area
 278 #
 279 dd  conv=fdatasync  ibs=4096  obs=4096  skip=1680  seek=1680  count=368  \
 280 if=build/coreboot.rom  of=build/coreboot.signed.rom
 281
 282 #
 283 #  Insert the HWID and public root and recovery RSA keys into the GBB area.
 284 #
 285 gbb_utility                          \
 286 --set --hwid='Galileo'            \
 287 -r $PWD/keys/recovery_key.vbpubk  \
 288 -k $PWD/keys/root_key.vbpubk      \
 289 build/coreboot.signed.rom
 290
 291 #
 292 #  Sign the read/write firmware areas with the private signing key and update
 293 #  the VBLOCK_A and VBLOCK_B regions.
 294 #
 295 3rdparty/vboot/scripts/image_signing/sign_firmware.sh  \
 296 build/coreboot.signed.rom                           \
 297 $PWD/keys                                           \
 298        build/coreboot.signed.rom
 299 ```
 300
 301 ***
 302
 303 ## Boot Flow
 304
 305 The reset vector exist in the read-only area and points to the bootblock
 306 entry point. The only copy of the bootblock exists in the read-only area
 307 of the SPI flash. Verstage may be part of the bootblock or a separate stage.
 308 If separate then the bootblock loads verstage from the read-only area and
 309 transfers control to it.
 310
 311 Upon first boot, verstage attempts to verify the read/write section A.
 312 It gets the public root key from the GBB area and uses that to verify the
 313 *VBLOCK* area in read-write section A. If the *VBLOCK* area is valid then it
 314 extracts the firmware signing key (1024-8192 bits) and uses that to verify
 315 the *FW_MAIN_A* area of read/write section A. If the verification is successful
 316 then verstage instructs coreboot to use the coreboot file system in read/write
 317 section A for the contents of the remaining boot firmware (romstage, postcar,
 318 ramstage and the payload).
 319
 320 If verification fails for the read/write area and the other read/write area is
 321 not valid vboot falls back to the read-only area to boot into system recovery.
 322
 323 ***
 324
 325 ## Chromebook Special Features
 326
 327 Google's Chromebooks have some special features:
 328
 329 * Developer mode
 330 * Write-protect screw
 331
 332 ### Developer Mode
 333
 334 Developer mode allows the user to use coreboot to boot another operating system.
 335 This may be a another (beta) version of ChromeOS, or another flavor of
 336 GNU/Linux. Use of developer mode does not void the system warranty. Upon entry
 337 into developer mode, all locally saved data on the system is lost.
 338 This prevents someone from entering developer mode to subvert the system
 339 security to access files on the local system or cloud.
 340
 341 ### Write Protect Screw
 342
 343 Chromebooks have a write-protect screw which provides the ground to the
 344 write-protect pin of the SPI flash.
 345 Google specifically did this to allow the manufacturing line and advanced
 346 developers to re-write the entire SPI flash part. Once the screw is removed,
 347 any firmware may be placed on the device.
 348 However, accessing this screw requires opening the case and voids the
 349 system warranty!