2d43218c2da2305b5ba17eaf4752362ad2c3ced2
[vboot.git] / firmware / 2lib / include / 2struct.h
1 /* Copyright (c) 2014 The Chromium OS Authors. All rights reserved.
2  * Use of this source code is governed by a BSD-style license that can be
3  * found in the LICENSE file.
4  *
5  * Data structure definitions for verified boot, for on-disk / in-eeprom
6  * data.
7  */
8
9 #ifndef VBOOT_REFERENCE_VBOOT_2STRUCT_H_
10 #define VBOOT_REFERENCE_VBOOT_2STRUCT_H_
11 #include <stdint.h>
12 #include "2crypto.h"
13
14 /*
15  * Key block flags.
16  *
17  *The following flags set where the key is valid.  Not used by firmware
18  * verification; only kernel verification.
19  */
20 #define VB2_KEY_BLOCK_FLAG_DEVELOPER_0  0x01 /* Developer switch off */
21 #define VB2_KEY_BLOCK_FLAG_DEVELOPER_1  0x02 /* Developer switch on */
22 #define VB2_KEY_BLOCK_FLAG_RECOVERY_0   0x04 /* Not recovery mode */
23 #define VB2_KEY_BLOCK_FLAG_RECOVERY_1   0x08 /* Recovery mode */
24 #define VB2_GBB_HWID_DIGEST_SIZE        32
25
26 /****************************************************************************/
27
28 /* Flags for vb2_shared_data.flags */
29 enum vb2_shared_data_flags {
30         /* User has explicitly and physically requested recovery */
31         VB2_SD_FLAG_MANUAL_RECOVERY = (1 << 0),
32
33         /* Developer mode is enabled */
34         /* TODO: should have been VB2_SD_FLAG_DEV_MODE_ENABLED */
35         VB2_SD_DEV_MODE_ENABLED = (1 << 1),
36
37         /*
38          * TODO: might be nice to add flags for why dev mode is enabled - via
39          * gbb, virtual dev switch, or forced on for testing.
40          */
41
42         /* Kernel keyblock was verified by signature (not just hash) */
43         VB2_SD_FLAG_KERNEL_SIGNED = (1 << 2),
44 };
45
46 /* Flags for vb2_shared_data.status */
47 enum vb2_shared_data_status {
48         /* Reinitialized NV data due to invalid checksum */
49         VB2_SD_STATUS_NV_REINIT = (1 << 0),
50
51         /* NV data has been initialized */
52         VB2_SD_STATUS_NV_INIT = (1 << 1),
53
54         /* Secure data initialized */
55         VB2_SD_STATUS_SECDATA_INIT = (1 << 2),
56
57         /* Chose a firmware slot */
58         VB2_SD_STATUS_CHOSE_SLOT = (1 << 3),
59
60         /* Secure data kernel version space initialized */
61         VB2_SD_STATUS_SECDATAK_INIT = (1 << 4),
62 };
63
64 /*
65  * Data shared between vboot API calls.  Stored at the start of the work
66  * buffer.
67  */
68 struct vb2_shared_data {
69         /* Flags; see enum vb2_shared_data_flags */
70         uint32_t flags;
71
72         /* Flags from GBB header */
73         uint32_t gbb_flags;
74
75         /*
76          * Reason we are in recovery mode this boot (enum vb2_nv_recovery), or
77          * 0 if we aren't.
78          */
79         uint32_t recovery_reason;
80
81         /* Firmware slot used last boot (0=A, 1=B) */
82         uint32_t last_fw_slot;
83
84         /* Result of last boot (enum vb2_fw_result) */
85         uint32_t last_fw_result;
86
87         /* Firmware slot used this boot */
88         uint32_t fw_slot;
89
90         /*
91          * Version for this slot (top 16 bits = key, lower 16 bits = firmware).
92          *
93          * TODO: Make this a union to allow getting/setting those versions
94          * separately?
95          */
96         uint32_t fw_version;
97
98         /* Version stored in secdata (must be <= fw_version to boot). */
99         uint32_t fw_version_secdata;
100
101         /*
102          * Status flags for this boot; see enum vb2_shared_data_status.  Status
103          * is "what we've done"; flags above are "decisions we've made".
104          */
105         uint32_t status;
106
107         /**********************************************************************
108          * Data from kernel verification stage.
109          *
110          * TODO: shouldn't be part of the main struct, since that needlessly
111          * uses more memory during firmware verification.
112          */
113
114         /*
115          * Version for the current kernel (top 16 bits = key, lower 16 bits =
116          * kernel preamble).
117          *
118          * TODO: Make this a union to allow getting/setting those versions
119          * separately?
120          */
121         uint32_t kernel_version;
122
123         /* Kernel version from secdatak (must be <= kernel_version to boot) */
124         uint32_t kernel_version_secdatak;
125
126         /**********************************************************************
127          * Temporary variables used during firmware verification.  These don't
128          * really need to persist through to the OS, but there's nowhere else
129          * we can put them.
130          */
131
132         /* Root key offset and size from GBB header */
133         uint32_t gbb_rootkey_offset;
134         uint32_t gbb_rootkey_size;
135
136         /* HWID digest from GBB header */
137         uint8_t gbb_hwid_digest[VB2_GBB_HWID_DIGEST_SIZE];
138
139         /* Offset of preamble from start of vblock */
140         uint32_t vblock_preamble_offset;
141
142         /*
143          * Offset and size of packed data key in work buffer.  Size is 0 if
144          * data key is not stored in the work buffer.
145          */
146         uint32_t workbuf_data_key_offset;
147         uint32_t workbuf_data_key_size;
148
149         /*
150          * Offset and size of firmware preamble in work buffer.  Size is 0 if
151          * preamble is not stored in the work buffer.
152          */
153         uint32_t workbuf_preamble_offset;
154         uint32_t workbuf_preamble_size;
155
156         /*
157          * Offset and size of hash context in work buffer.  Size is 0 if
158          * hash context is not stored in the work buffer.
159          */
160         uint32_t workbuf_hash_offset;
161         uint32_t workbuf_hash_size;
162
163         /*
164          * Current tag we're hashing
165          *
166          * For new structs, this is the offset of the vb2_signature struct
167          * in the work buffer.
168          *
169          * TODO: rename to workbuf_hash_sig_offset when vboot1 structs are
170          * deprecated.
171          */
172         uint32_t hash_tag;
173
174         /* Amount of data we still expect to hash */
175         uint32_t hash_remaining_size;
176
177         /**********************************************************************
178          * Temporary variables used during kernel verification.  These don't
179          * really need to persist through to the OS, but there's nowhere else
180          * we can put them.
181          *
182          * TODO: make a union with the firmware verification temp variables,
183          * or make both of them workbuf-allocated sub-structs, so that we can
184          * overlap them so kernel variables don't bloat firmware verification
185          * stage memory requirements.
186          */
187
188         /*
189          * Offset and size of packed kernel key in work buffer.  Size is 0 if
190          * subkey is not stored in the work buffer.  Note that kernel key may
191          * be inside the firmware preamble.
192          */
193         uint32_t workbuf_kernel_key_offset;
194         uint32_t workbuf_kernel_key_size;
195
196 } __attribute__((packed));
197
198 /****************************************************************************/
199
200 /* Signature at start of the GBB
201  * Note that if you compile in the signature as is, you are likely to break any
202  * tools that search for the signature. */
203 #define VB2_GBB_SIGNATURE "$GBB"
204 #define VB2_GBB_SIGNATURE_SIZE 4
205 #define VB2_GBB_XOR_CHARS "****"
206 /* TODO: can we write a macro to produce this at compile time? */
207 #define VB2_GBB_XOR_SIGNATURE { 0x0e, 0x6d, 0x68, 0x68 }
208
209 /* VB2 GBB struct version */
210 #define VB2_GBB_MAJOR_VER      1
211 #define VB2_GBB_MINOR_VER      2
212 /* v1.2 - added fields for sha256 digest of the HWID */
213
214 /* Flags for vb2_gbb_header.flags */
215 enum vb2_gbb_flag {
216         /*
217          * Reduce the dev screen delay to 2 sec from 30 sec to speed up
218          * factory.
219          */
220         VB2_GBB_FLAG_DEV_SCREEN_SHORT_DELAY = (1 << 0),
221
222         /*
223          * BIOS should load option ROMs from arbitrary PCI devices. We'll never
224          * enable this ourselves because it executes non-verified code, but if
225          * a customer wants to void their warranty and set this flag in the
226          * read-only flash, they should be able to do so.
227          *
228          * (TODO: Currently not supported. Mark as deprecated/unused?)
229          */
230         VB2_GBB_FLAG_LOAD_OPTION_ROMS = (1 << 1),
231
232         /*
233          * The factory flow may need the BIOS to boot a non-ChromeOS kernel if
234          * the dev-switch is on. This flag allows that.
235          *
236          * (TODO: Currently not supported. Mark as deprecated/unused?)
237          */
238         VB2_GBB_FLAG_ENABLE_ALTERNATE_OS = (1 << 2),
239
240         /*
241          * Force dev switch on, regardless of physical/keyboard dev switch
242          * position.
243          */
244         VB2_GBB_FLAG_FORCE_DEV_SWITCH_ON = (1 << 3),
245
246         /* Allow booting from USB in dev mode even if dev_boot_usb=0. */
247         VB2_GBB_FLAG_FORCE_DEV_BOOT_USB = (1 << 4),
248
249         /* Disable firmware rollback protection. */
250         VB2_GBB_FLAG_DISABLE_FW_ROLLBACK_CHECK = (1 << 5),
251
252         /* Allow Enter key to trigger dev->tonorm screen transition */
253         VB2_GBB_FLAG_ENTER_TRIGGERS_TONORM = (1 << 6),
254
255         /* Allow booting Legacy OSes in dev mode even if dev_boot_legacy=0. */
256         VB2_GBB_FLAG_FORCE_DEV_BOOT_LEGACY = (1 << 7),
257
258         /* Allow booting using alternate keys for FAFT servo testing */
259         VB2_GBB_FLAG_FAFT_KEY_OVERIDE = (1 << 8),
260
261         /* Disable EC software sync */
262         VB2_GBB_FLAG_DISABLE_EC_SOFTWARE_SYNC = (1 << 9),
263
264         /* Default to booting legacy OS when dev screen times out */
265         VB2_GBB_FLAG_DEFAULT_DEV_BOOT_LEGACY = (1 << 10),
266
267         /* Disable PD software sync */
268         VB2_GBB_FLAG_DISABLE_PD_SOFTWARE_SYNC = (1 << 11),
269
270         /* Disable shutdown on lid closed */
271         VB2_GBB_FLAG_DISABLE_LID_SHUTDOWN = (1 << 12),
272
273         /*
274          * Allow full fastboot capability in firmware even if
275          * dev_boot_fastboot_full_cap=0.
276          */
277         VB2_GBB_FLAG_FORCE_DEV_BOOT_FASTBOOT_FULL_CAP = (1 << 13),
278 };
279
280 struct vb2_gbb_header {
281         /* Fields present in version 1.1 */
282         uint8_t  signature[VB2_GBB_SIGNATURE_SIZE]; /* VB2_GBB_SIGNATURE */
283         uint16_t major_version;   /* See VB2_GBB_MAJOR_VER */
284         uint16_t minor_version;   /* See VB2_GBB_MINOR_VER */
285         uint32_t header_size;     /* Size of GBB header in bytes */
286         uint32_t flags;           /* Flags (see enum vb2_gbb_flag) */
287
288         /* Offsets (from start of header) and sizes (in bytes) of components */
289         uint32_t hwid_offset;           /* HWID */
290         uint32_t hwid_size;
291         uint32_t rootkey_offset;        /* Root key */
292         uint32_t rootkey_size;
293         uint32_t bmpfv_offset;          /* BMP FV */
294         uint32_t bmpfv_size;
295         uint32_t recovery_key_offset;   /* Recovery key */
296         uint32_t recovery_key_size;
297
298         /* Added in version 1.2 */
299         uint8_t  hwid_digest[VB2_GBB_HWID_DIGEST_SIZE]; /* SHA-256 of HWID */
300
301         /* Pad to match EXPECETED_VB2_GBB_HEADER_SIZE.  Initialize to 0. */
302         uint8_t  pad[48];
303 } __attribute__((packed));
304
305 /* The GBB is used outside of vboot_reference, so this size is important. */
306 #define EXPECTED_VB2_GBB_HEADER_SIZE 128
307
308 /*
309  * Root key hash for Ryu devices only.  Contains the hash of the root key.
310  * This will be embedded somewhere inside the RO part of the firmware, so that
311  * it can verify the GBB contains only the official root key.
312  */
313
314 #define RYU_ROOT_KEY_HASH_MAGIC "RtKyHash"
315 #define RYU_ROOT_KEY_HASH_MAGIC_INVCASE "rTkYhASH"
316 #define RYU_ROOT_KEY_HASH_MAGIC_SIZE 8
317
318 #define RYU_ROOT_KEY_HASH_VERSION_MAJOR 1
319 #define RYU_ROOT_KEY_HASH_VERSION_MINOR 0
320
321 struct vb2_ryu_root_key_hash {
322         /* Magic number (RYU_ROOT_KEY_HASH_MAGIC) */
323         uint8_t magic[RYU_ROOT_KEY_HASH_MAGIC_SIZE];
324
325         /* Version of this struct */
326         uint16_t header_version_major;
327         uint16_t header_version_minor;
328
329         /*
330          * Length of this struct, in bytes, including any variable length data
331          * which follows (there is none, yet).
332          */
333         uint32_t struct_size;
334
335         /*
336          * SHA-256 hash digest of the entire root key section from the GBB.  If
337          * all 0 bytes, all root keys will be treated as if matching.
338          */
339         uint8_t root_key_hash_digest[32];
340 };
341
342 #define EXPECTED_VB2_RYU_ROOT_KEY_HASH_SIZE 48
343
344 #endif  /* VBOOT_REFERENCE_VBOOT_2STRUCT_H_ */