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