[coreboot-gerrit] Change in coreboot[master]: Documentation/Intel: Add vboot documentation
Lee Leahy (Code Review)
gerrit at coreboot.org
Wed May 3 02:47:27 CEST 2017
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 at 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>
--
To view, visit https://review.coreboot.org/19534
To unsubscribe, visit https://review.coreboot.org/settings
Gerrit-MessageType: newchange
Gerrit-Change-Id: Ie17b8443772f596de0c9d8afe6f4ec3ac4d4fef8
Gerrit-PatchSet: 1
Gerrit-Project: coreboot
Gerrit-Branch: master
Gerrit-Owner: Lee Leahy <leroy.p.leahy at intel.com>
More information about the coreboot-gerrit
mailing list