Lee Leahy has uploaded a new change for review. ( https://review.coreboot.org/19534 )
Change subject: Documentation/Intel: Add vboot documentation ......................................................................
Documentation/Intel: Add vboot documentation
Add documentation which describes how to build and sign a coreboot image which enables vboot.
TEST=None
Change-Id: Ie17b8443772f596de0c9d8afe6f4ec3ac4d4fef8 Signed-off-by: Lee Leahy Leroy.P.Leahy@intel.com --- M Documentation/Intel/index.html A Documentation/Intel/vboot.html 2 files changed, 374 insertions(+), 0 deletions(-)
git pull ssh://review.coreboot.org:29418/coreboot refs/changes/34/19534/1
diff --git a/Documentation/Intel/index.html b/Documentation/Intel/index.html index 6aaf1be..b2e826d 100644 --- a/Documentation/Intel/index.html +++ b/Documentation/Intel/index.html @@ -29,6 +29,7 @@ </li> <li><a target="_blank" href="SoC/soc.html">SoC</a> support</li> <li><a target="_blank" href="Board/board.html">Board</a> support</li> + <li><a target="_blank" href="vboot.html">Verified Boot (vboot)</a> support</li> </ul>
diff --git a/Documentation/Intel/vboot.html b/Documentation/Intel/vboot.html new file mode 100644 index 0000000..1148028 --- /dev/null +++ b/Documentation/Intel/vboot.html @@ -0,0 +1,373 @@ +<!DOCTYPE html> +<html> + <head> + <title>vboot - Verified Boot Support</title> + </head> + <body> + +<h1>vboot - Verified Boot Support</h1> + +<p> +Google's verified boot support consists of: +</p> +<ul> + <li>A root of trust</li> + <li>Special firmware layout</li> + <li>Firmware verification</li> + <li>Firmware measurements</li> + <li>A firmware update mechanism</li> + <li>Specific build flags</li> + <li>Signing the coreboot image</li> +</ul> + +Google's vboot verifies the firmware verification and places measurements +within the TPM. + +<hr> +<h1>Root of Trust</h1> +<p> +When using vboot, the root-of-trust is basically the read-only portion of the +SPI flash. The following items factor into the trust equation: +</p> +<ul> + <li>The GCC compiler must reliably translate the code into machine code + without inserting any additional code (virus, backdoor, etc.) + </li> + <li>The CPU must reliably execute the reset sequence and instructions as + documented by the CPU manufacture. + </li> + <li>The SPI flash must provide only the code programmed into it to the CPU + without providing any alternative reset vector or code sequence. + </li> + <li>The SPI flash must honor the write-protect input and protect the + specified portion of the SPI flash from all erase and write accesses. + </li> +</ul> + +<p> +The firmware is typically protected using the write-protect pin on the SPI +flash part and setting some of the write-protect bits in the status register +during manufacturing. The protected area is typically 1/4th of the SPI flash +part size. Because this portion of the SPI flash is hardware write protected, +it is not possible to update this portion of the SPI flash in the field, +without altering the system to eliminate the ground connection to the SPI flash +write-protect pin. Without hardware modifications, this portion of the SPI +flash maintains the manufactured state during the system's lifetime. +</p> + +<hr> +<h1>Firmware Layout</h1> +<p> +Several sections are added to the firmware layout to support vboot: +</p> +<ul> + <li>Read-only section</li> + <li>Google Binary Blob (GBB) area</li> + <li>Read/write section A</li> + <li>Read/write section B</li> +</ul> +<p> +These following sections describe the various portions of the flash layout. +</p> + +<h2>Read-Only Section</h2> +<p> +The read-only section contains a coreboot file system (CBFS) that contains all +of the boot firmware necessary to perform recovery for the system. This +firmware is typically protected using the write-protect pin on the SPI flash +part and setting some of the write-protect bits in the status register during +manufacturing. The protected area is typically 1/4th of the SPI flash part +size and must cover the entire read-only section which consists of: +</p> +<ul> + <li>Vital Product Data (VPD) area</li> + <li>Firmware ID area</li> + <li>Google Binary Blob (GBB) area</li> + <li>coreboot file system containing read-only recovery firmware</li> +</ul> + +<h2>Google Binary Blob (GBB) Area</h2> +<p> +The GBB area is part of the read-only section. This area contains a 4096 or +8192 bit public root key that is used to verify the VBLOCK area to obtain the +firmware signing key. +</p> + +<h2>Recovery Firmware</h2> +<p> +The recovery firmware is contained within a coreboot file system and consists +of: +</p> +<ul> + <li>reset vector</li> + <li>bootblock</li> + <li>verstage</li> + <li>romstage</li> + <li>postcar</li> + <li>ramstage</li> + <li>payload</li> + <li>flash map file</li> + <li>config file</li> + <li>processor specific files: + <ul> + <li>Microcode</li> + <li>fspm.bin</li> + <li>fsps.bin</li> + </ul> + </li> +</ul> + +<p> +The recovery firmware is written during manufacturing and typically contains +code to write the storage device (eMMC device or hard disk). The recovery +image is usually contained on a socketed device such as a USB flash drive or +an SD card. Depending upon the payload firmware doing the recovery, it may +be possible for the user to interact with the system to specify the recovery +image path. Part of the recovery is also to write the A and B areas of the +SPI flash device to boot the system. +</p> + + +<h2>Read/Write Section</h2> + +<p> +The read/write sections contain a an area which contains the firmware signing +key and signature and an area containing a coreboot file system with a subset +of the firmware. The firmware files in FW_MAIN_A and FW_MAIN_B are: +</p> +<ul> + <li>romstage</li> + <li>postcar</li> + <li>ramstage</li> + <li>payload</li> + <li>config file</li> + <li>processor specific files: + <ul> + <li>Microcode</li> + <li>fspm.bin</li> + <li>fsps.bin</li> + </ul> + </li> +</ul> + +<p> +The firmware subset enables most issues to be fixed in the field with firmware +updates. The firmware files handle memory and most of silicon initialization. +These files also produce the tables which get passed to the operating system. +</p> + +<hr> +<h1>Firmware Updates</h1> +<p> +The read/write sections exist in one of three states: +</p> +<ul> + <li>Invalid</li> + <li>Ready to boot</li> + <li>Successfully booted</li> +</ul> + +<table border="1"> +<tr bgcolor="#ffc0c0"> +<td> +Where is this state information written? +<br/>CMOS? +<br/>RW_NVRAM? +<br/>RW_FWID_* +</td> +</tr> +</table> + +<p> +Firmware updates are handled by the operating system by writing any read/write +section that is not in the "successfully booted" state. Upon the next reboot, +vboot determines the section to boot. If it finds one in the "ready to boot" +state then it attempts to boot using that section. If the boot fails then +vboot marks the section as invalid and attempts to fall back to a read/write +section in the "successfully booted" state. If vboot is not able to find a +section in the "successfully booted" state then vboot enters recovery mode. +</p> + +<p> +Only the operating system is able to transition a section from the "ready to +boot" state to the "successfully booted" state. The transition is typically +done after after the operating system has been running for a while indicating +that successful boot was possible and the operating system is stable. +</p> + +<p> +Note that as long as the SPI write protection is in place then the system is +always recoverable. If the flash update fails then the system will continue +to boot using the previous read/write area. The same is true if coreboot +passes control to the payload or the operating system and then the boot fails. +In the worst case, the SPI flash gets totally corrupted in which case vboot +fails the signature checks and enters recovery mode. There are no times where +the SPI flash is exposed and the reset vector or part of the recovery firmware +gets corrupted. +</p> + +<hr> +<h1>Build Flags</h1> +<p> +The following Kconfig values need to be selected to enable vboot: +</p> +<ul> + <li>COLLECT_TIMESTAMPS</li> + <li>VBOOT</li> +</ul> + +<p> +The starting stage needs to be specified by selecting either +VBOOT_STARTS_IN_BOOTBLOCK or VBOOT_STARTS_IN_ROMSTAGE. +</p> + +<p> +If vboot starts in bootblock then vboot may be built as a separate stage by +selecting VBOOT_SEPARATE_VERSTAGE. Additionally, if RAM is too small to fit +both verstage and romstage then selecting VBOOT_RETURN_FROM_VERSTAGE enables +bootblock to reuse the RAM occupied by verstage for romstage. +</p> + +<p> +Non-volatile flash is needed for vboot operation. This flash area may be in +CMOS, the EC, or in a read/write area of the SPI flash device. Select one of +the following: +</p> +<ul> + <li>VBOOT_VBNV_CMOS</li> + <li>VBOOT_VBNV_EC</li> + <li>VBOOT_VBNV_FLASH</li> +</ul> +<p> +More non-volatile storage features may be found in src/vboot/Kconfig. +</p> + +<p> +A TPM is also required for vboot operation. TPMs are available in +drivers/i2c/tpm and drivers/pc80/tpm. +</p> + +<p> +Enabling vboot causes coreboot to be built several times, once for each of the +read-only section, the read/write A section and the read/write B section. +</p> + +<hr> +<h1>Signing the coreboot Image</h1> +<p> +The follow command script is an example of how to sign the coreboot image file. +This script is used on the Intel Galileo board and creates the GBB area and +inserts it into the coreboot image. It also updates the VBLOCK areas with the +firmware signing key and the signature for the FW_MAIN firmware. More details +are available in 3rdparty/vboot/README. +</p> + +<pre><code>#!/bin/sh +# +# The necessary tools were built and installed using the following commands: +# +# pushd 3rdparty/vboot +# make +# sudo make install +# popd +# +# The keys were made using the following command +# +# 3rdparty/vboot/scripts/keygeneration/create_new_keys.sh \ +# --4k --4k-root --output $PWD/keys +# +# +# Create the GBB area blob +# +gbb_utility -c 0x100,0x1000,0x7ce80,0x1000 gbb.blob + +# +# Add the empty GBB to the coreboot.rom image +# +dd conv=fdatasync ibs=4096 obs=4096 count=1553 \ +if=build/coreboot.rom of=build/coreboot.signed.rom + +dd conv=fdatasync obs=4096 obs=4096 seek=1553 if=gbb.blob \ +of=build/coreboot.signed.rom + +dd conv=fdatasync ibs=4096 obs=4096 skip=1680 seek=1680 count=368 \ +if=build/coreboot.rom of=build/coreboot.signed.rom + +# +# Add the keys and HWID to the GBB +# +gbb_utility \ +--set --hwid='Galileo' \ +-r $PWD/keys/recovery_key.vbpubk \ +-k $PWD/keys/root_key.vbpubk \ +build/coreboot.signed.rom + +# +# Sign the firmware with the keys +# +3rdparty/vboot/scripts/image_signing/sign_firmware.sh \ +build/coreboot.signed.rom \ +$PWD/keys \ +build/coreboot.signed.rom +</code></pre> + +<hr> +<h1>Boot Flow</h1> +<p> +The reset vector exist in the read-only area and points to the bootblock entry +point. The only copy of the bootblock exists in the read-only area of the SPI +flash. Verstage may be part of the bootblock or a separate stage. If separate +then the bootblock loads verstage from the read-only area and transfers control +to it. +</p> + +<p> +Upon first boot, verstage attempts to verify the read/write section A. It gets +the public root key from the GBB area and uses that to verify the VBLOCK area +in read-write section A. If the VBLOCK area is valid then it extracts the +firmware signing key (1024-8192 bits) and uses that to verify the FW_MAIN_A +area of read/write section A. If the verification is successful then verstage +instructs coreboot to use the coreboot file system in read/write section A for +the contents of the remaining boot firmware (romstage, postcar, ramstage and +the payload). +</p> + +<p> +If verification fails for the read/write area and the other read/write area is +not valid vboot falls back to the read-only area to boot into system recovery. +</p> + +<hr> +<h1>Chromebook Special Features</h1> +<p> +Google's Chromebooks have some special features: +</p> +<ul> + <li>Developer mode</li> + <li>Write-protect screw</li> +</ul> + +<h2>Developer Mode</h2> +<p> +Developer mode allow the user to use coreboot to boot another operating system. +This may be a another (beta) version of ChromeOS, or another flavor of Linux. +Use of developer mode does not void the Chromebook warranty. Upon entry into +developer mode, all locally saved data on the Chromebook is lost. This +prevents someone from entering developer mode to subvert the system security to +access files on the local system or cloud. +</p> + +<h2>Write Protect Screw</h2> +<p> +Early Chromebooks have a write-protect screw which provides the ground to the +write-protect pin of the SPI flash. Google specifically did this to allow +the manufacturing line and advanced developers to re-write the entire SPI flash +part. Once the screw is removed, any firmware may be placed on the device. +However, accessing this screw requires opening the case and voids the system +warranty! +</p> + +<hr> +<p>Modified: 2 May 2017</p> + </body> +</html>