blob: f8fd8c808fb60c586327b82e437ef7d583645e39 [file] [log] [blame]
Randall Spangler95c40312011-03-09 15:54:16 -08001/* Copyright (c) 2011 The Chromium OS Authors. All rights reserved.
Randall Spanglerd1836442010-06-10 09:59:04 -07002 * 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_STRUCT_H_
10#define VBOOT_REFERENCE_VBOOT_STRUCT_H_
11
Randall Spanglerf3029052010-06-16 13:42:58 -070012#include "sysincludes.h"
Randall Spanglerd1836442010-06-10 09:59:04 -070013
vbendeb3ecaf772010-06-24 16:19:53 -070014__pragma(pack(push, 1)) /* Support packing for MSVC. */
Randall Spanglerd1836442010-06-10 09:59:04 -070015
16/* Public key data */
17typedef struct VbPublicKey {
18 uint64_t key_offset; /* Offset of key data from start of this struct */
19 uint64_t key_size; /* Size of key data in bytes (NOT strength of key
20 * in bits) */
21 uint64_t algorithm; /* Signature algorithm used by the key */
22 uint64_t key_version; /* Key version */
Randall Spanglere9958952010-06-15 21:36:24 -070023} __attribute__((packed)) VbPublicKey;
Randall Spanglerd1836442010-06-10 09:59:04 -070024
Randall Spangler81d09962010-06-23 10:15:38 -070025#define EXPECTED_VBPUBLICKEY_SIZE 32
26
Randall Spanglerd1836442010-06-10 09:59:04 -070027
28/* Signature data (a secure hash, possibly signed) */
29typedef struct VbSignature {
30 uint64_t sig_offset; /* Offset of signature data from start of this
31 * struct */
Randall Spanglerd55c6452010-06-10 12:43:51 -070032 uint64_t sig_size; /* Size of signature data in bytes */
Randall Spanglerd1836442010-06-10 09:59:04 -070033 uint64_t data_size; /* Size of the data block which was signed in bytes */
Randall Spanglere9958952010-06-15 21:36:24 -070034} __attribute__((packed)) VbSignature;
Randall Spanglerd1836442010-06-10 09:59:04 -070035
Randall Spangler81d09962010-06-23 10:15:38 -070036#define EXPECTED_VBSIGNATURE_SIZE 24
37
Randall Spanglerd1836442010-06-10 09:59:04 -070038
39#define KEY_BLOCK_MAGIC "CHROMEOS"
40#define KEY_BLOCK_MAGIC_SIZE 8
41
42#define KEY_BLOCK_HEADER_VERSION_MAJOR 2
43#define KEY_BLOCK_HEADER_VERSION_MINOR 1
44
45/* Flags for key_block_flags */
46/* The following flags set where the key is valid */
47#define KEY_BLOCK_FLAG_DEVELOPER_0 UINT64_C(0x01) /* Developer switch off */
48#define KEY_BLOCK_FLAG_DEVELOPER_1 UINT64_C(0x02) /* Developer switch on */
49#define KEY_BLOCK_FLAG_RECOVERY_0 UINT64_C(0x04) /* Not recovery mode */
50#define KEY_BLOCK_FLAG_RECOVERY_1 UINT64_C(0x08) /* Recovery mode */
51
52/* Key block, containing the public key used to sign some other chunk
53 * of data. */
54typedef struct VbKeyBlockHeader {
55 uint8_t magic[KEY_BLOCK_MAGIC_SIZE]; /* Magic number */
56 uint32_t header_version_major; /* Version of this header format */
57 uint32_t header_version_minor; /* Version of this header format */
58 uint64_t key_block_size; /* Length of this entire key block,
59 * including keys, signatures, and
60 * padding, in bytes */
61 VbSignature key_block_signature; /* Signature for this key block
62 * (header + data pointed to by data_key)
63 * For use with signed data keys*/
64 VbSignature key_block_checksum; /* SHA-512 checksum for this key block
65 * (header + data pointed to by data_key)
66 * For use with unsigned data keys */
67 uint64_t key_block_flags; /* Flags for key (KEY_BLOCK_FLAG_*) */
68 VbPublicKey data_key; /* Key to verify the chunk of data */
Randall Spanglere9958952010-06-15 21:36:24 -070069} __attribute__((packed)) VbKeyBlockHeader;
Randall Spanglerd1836442010-06-10 09:59:04 -070070/* This should be followed by:
71 * 1) The data_key key data, pointed to by data_key.key_offset.
72 * 2) The checksum data for (VBKeyBlockHeader + data_key data), pointed to
73 * by key_block_checksum.sig_offset.
74 * 3) The signature data for (VBKeyBlockHeader + data_key data), pointed to
75 * by key_block_signature.sig_offset. */
76
Randall Spangler81d09962010-06-23 10:15:38 -070077#define EXPECTED_VBKEYBLOCKHEADER_SIZE 112
78
Randall Spanglerd1836442010-06-10 09:59:04 -070079
80#define FIRMWARE_PREAMBLE_HEADER_VERSION_MAJOR 2
81#define FIRMWARE_PREAMBLE_HEADER_VERSION_MINOR 0
82
83/* Preamble block for rewritable firmware */
84typedef struct VbFirmwarePreambleHeader {
85 uint64_t preamble_size; /* Size of this preamble, including keys,
86 * signatures, and padding, in bytes */
87 VbSignature preamble_signature; /* Signature for this preamble
88 * (header + kernel subkey +
89 * body signature) */
90 uint32_t header_version_major; /* Version of this header format */
91 uint32_t header_version_minor; /* Version of this header format */
92
93 uint64_t firmware_version; /* Firmware version */
94 VbPublicKey kernel_subkey; /* Key to verify kernel key block */
95 VbSignature body_signature; /* Signature for the firmware body */
Randall Spanglere9958952010-06-15 21:36:24 -070096} __attribute__((packed)) VbFirmwarePreambleHeader;
Randall Spanglerd1836442010-06-10 09:59:04 -070097/* This should be followed by:
98 * 1) The kernel_subkey key data, pointed to by kernel_subkey.key_offset.
99 * 2) The signature data for the firmware body, pointed to by
100 * body_signature.sig_offset.
101 * 3) The signature data for (VBFirmwarePreambleHeader + kernel_subkey data
102 * + body signature data), pointed to by
103 * preamble_signature.sig_offset. */
104
Randall Spangler81d09962010-06-23 10:15:38 -0700105#define EXPECTED_VBFIRMWAREPREAMBLEHEADER_SIZE 104
Randall Spanglerd1836442010-06-10 09:59:04 -0700106
107#define KERNEL_PREAMBLE_HEADER_VERSION_MAJOR 2
108#define KERNEL_PREAMBLE_HEADER_VERSION_MINOR 0
109
110/* Preamble block for kernel */
111typedef struct VbKernelPreambleHeader {
112 uint64_t preamble_size; /* Size of this preamble, including keys,
113 * signatures, and padding, in bytes */
114 VbSignature preamble_signature; /* Signature for this preamble
115 * (header + body signature) */
116 uint32_t header_version_major; /* Version of this header format */
117 uint32_t header_version_minor; /* Version of this header format */
118
119 uint64_t kernel_version; /* Kernel version */
120 uint64_t body_load_address; /* Load address for kernel body */
121 uint64_t bootloader_address; /* Address of bootloader, after body is
122 * loaded at body_load_address */
123 uint64_t bootloader_size; /* Size of bootloader in bytes */
124 VbSignature body_signature; /* Signature for the kernel body */
Randall Spanglere9958952010-06-15 21:36:24 -0700125} __attribute__((packed)) VbKernelPreambleHeader;
Randall Spanglerd1836442010-06-10 09:59:04 -0700126/* This should be followed by:
127 * 2) The signature data for the kernel body, pointed to by
128 * body_signature.sig_offset.
129 * 3) The signature data for (VBFirmwarePreambleHeader + body signature
130 * data), pointed to by preamble_signature.sig_offset. */
131
Randall Spangler81d09962010-06-23 10:15:38 -0700132#define EXPECTED_VBKERNELPREAMBLEHEADER_SIZE 96
133
Randall Spangler17c71262011-03-18 11:24:27 -0700134/* Constants and sub-structures for VbSharedDataHeader */
135
Randall Spanglerf4ba19d2011-03-17 16:10:21 -0700136/* Magic number for recognizing VbSharedDataHeader ("VbSD") */
137#define VB_SHARED_DATA_MAGIC 0x44536256
138
Randall Spangler95c40312011-03-09 15:54:16 -0800139/* Minimum and recommended size of shared_data_blob in bytes. */
140#define VB_SHARED_DATA_MIN_SIZE 3072
141#define VB_SHARED_DATA_REC_SIZE 16384
142
Randall Spanglerf4ba19d2011-03-17 16:10:21 -0700143/* Flags for VbSharedDataHeader */
144/* LoadFirmware() tried firmware B because of VbNvStorage firmware B tries */
145#define VBSD_FWB_TRIED 0x00000001
Randall Spangler17c71262011-03-18 11:24:27 -0700146/* LoadKernel() verified the good kernel keyblock using the kernel subkey from
Randall Spanglerf4ba19d2011-03-17 16:10:21 -0700147 * the firmware. If this flag is not present, it just used the hash of the
148 * kernel keyblock. */
149#define VBSD_KERNEL_KEY_VERIFIED 0x00000002
150/* LoadFirmware() was told the developer switch was on */
151#define VBSD_LF_DEV_SWITCH_ON 0x00000004
152
Randall Spangler17c71262011-03-18 11:24:27 -0700153/* Result codes for VbSharedDataHeader.check_fw_a_result (and b_result) */
Randall Spanglerf4ba19d2011-03-17 16:10:21 -0700154#define VBSD_LF_CHECK_NOT_DONE 0
155#define VBSD_LF_CHECK_DEV_MISMATCH 1
156#define VBSD_LF_CHECK_REC_MISMATCH 2
157#define VBSD_LF_CHECK_VERIFY_KEYBLOCK 3
158#define VBSD_LF_CHECK_KEY_ROLLBACK 4
159#define VBSD_LF_CHECK_DATA_KEY_PARSE 5
160#define VBSD_LF_CHECK_VERIFY_PREAMBLE 6
161#define VBSD_LF_CHECK_FW_ROLLBACK 7
162#define VBSD_LF_CHECK_HEADER_VALID 8
163#define VBSD_LF_CHECK_GET_FW_BODY 9
164#define VBSD_LF_CHECK_HASH_WRONG_SIZE 10
165#define VBSD_LF_CHECK_VERIFY_BODY 11
166#define VBSD_LF_CHECK_VALID 12
167
Randall Spangler17c71262011-03-18 11:24:27 -0700168/* Boot mode for VbSharedDataHeader.lk_boot_mode */
169#define VBSD_LK_BOOT_MODE_RECOVERY 0
170#define VBSD_LK_BOOT_MODE_NORMAL 1
171#define VBSD_LK_BOOT_MODE_DEVELOPER 2
172
173/* Flags for VbSharedDataKernelPart.flags */
174#define VBSD_LKP_FLAG_KEY_BLOCK_VALID 0x01
175
176/* Result codes for VbSharedDataKernelPart.check_result */
177#define VBSD_LKP_CHECK_NOT_DONE 0
178#define VBSD_LKP_CHECK_TOO_SMALL 1
179#define VBSD_LKP_CHECK_READ_START 2
180#define VBSD_LKP_CHECK_KEY_BLOCK_SIG 3
181#define VBSD_LKP_CHECK_KEY_BLOCK_HASH 4
182#define VBSD_LKP_CHECK_DEV_MISMATCH 5
183#define VBSD_LKP_CHECK_REC_MISMATCH 6
184#define VBSD_LKP_CHECK_KEY_ROLLBACK 7
185#define VBSD_LKP_CHECK_DATA_KEY_PARSE 8
186#define VBSD_LKP_CHECK_VERIFY_PREAMBLE 9
187#define VBSD_LKP_CHECK_KERNEL_ROLLBACK 10
188#define VBSD_LKP_CHECK_PREAMBLE_VALID 11
189#define VBSD_LKP_CHECK_BODY_ADDRESS 12
190#define VBSD_LKP_CHECK_BODY_OFFSET 13
191#define VBSD_LKP_CHECK_BODY_EXCEEDS_MEM 15
192#define VBSD_LKP_CHECK_BODY_EXCEEDS_PART 16
193#define VBSD_LKP_CHECK_READ_DATA 17
194#define VBSD_LKP_CHECK_VERIFY_DATA 18
195#define VBSD_LKP_CHECK_KERNEL_GOOD 19
196
197
198/* Information about a single kernel partition check in LoadKernel() */
199typedef struct VbSharedDataKernelPart {
200 uint64_t sector_start; /* Start sector of partition */
201 uint64_t sector_count; /* Sector count of partition */
202 uint32_t combined_version; /* Combined key+kernel version */
203 uint8_t gpt_index; /* Index of partition in GPT */
204 uint8_t check_result; /* Check result; see VBSD_LKP_CHECK_* */
205 uint8_t flags; /* Flags (see VBSD_LKP_FLAG_* */
Randall Spangler71415712011-03-21 11:04:50 -0700206 uint8_t reserved0; /* Reserved for padding */
Randall Spangler17c71262011-03-18 11:24:27 -0700207} VbSharedDataKernelPart;
208
209/* Number of kernel partitions to track per call. Must be power of 2. */
210#define VBSD_MAX_KERNEL_PARTS 8
211
212/* Flags for VbSharedDataKernelCall.flags */
213/* Error initializing TPM in recovery mode */
214#define VBSD_LK_FLAG_REC_TPM_INIT_ERROR 0x00000001
215
216/* Result codes for VbSharedDataKernelCall.check_result */
217#define VBSD_LKC_CHECK_NOT_DONE 0
218#define VBSD_LKC_CHECK_DEV_SWITCH_MISMATCH 1
219#define VBSD_LKC_CHECK_GPT_READ_ERROR 2
220#define VBSD_LKC_CHECK_GPT_PARSE_ERROR 3
221#define VBSD_LKC_CHECK_GOOD_PARTITION 4
222#define VBSD_LKC_CHECK_INVALID_PARTITIONS 5
223#define VBSD_LKC_CHECK_NO_PARTITIONS 6
224
225/* Information about a single call to LoadKernel() */
226typedef struct VbSharedDataKernelCall {
227 uint32_t boot_flags; /* Bottom 32 bits of flags passed in
228 * LoadKernelParams.boot_flags */
229 uint32_t flags; /* Debug flags; see VBSD_LK_FLAG_* */
230 uint64_t sector_count; /* Number of sectors on drive */
231 uint32_t sector_size; /* Sector size in bytes */
232 uint8_t check_result; /* Check result; see VBSD_LKC_CHECK_* */
233 uint8_t boot_mode; /* Boot mode for LoadKernel(); see
234 * VBSD_LK_BOOT_MODE_* constants */
235 uint8_t test_error_num; /* Test error number, if non-zero */
236 uint8_t return_code; /* Return code from LoadKernel() */
237 uint8_t kernel_parts_found; /* Number of kernel partitions found */
Randall Spangler71415712011-03-21 11:04:50 -0700238 uint8_t reserved0[7]; /* Reserved for padding */
Randall Spangler17c71262011-03-18 11:24:27 -0700239 VbSharedDataKernelPart parts[VBSD_MAX_KERNEL_PARTS]; /* Data on kernels */
240} VbSharedDataKernelCall;
241
242/* Number of kernel calls to track. Must be power of 2. */
243#define VBSD_MAX_KERNEL_CALLS 4
244
Randall Spangler95c40312011-03-09 15:54:16 -0800245/* Data shared between LoadFirmware(), LoadKernel(), and OS.
246 *
247 * The boot process is:
248 * 1) Caller allocates buffer, at least VB_SHARED_DATA_MIN bytes, ideally
249 * VB_SHARED_DATA_REC_SIZE bytes.
250 * 2) If non-recovery boot, this is passed to LoadFirmware(), which
251 * initializes the buffer, adding this header and some data.
252 * 3) Buffer is passed to LoadKernel(). If this is a recovery boot,
253 * LoadKernel() initializes the buffer, adding this header. Regardless
254 * of boot type, LoadKernel() adds some data to the buffer.
255 * 4) Caller makes data available to the OS in a platform-dependent manner.
256 * For example, via ACPI or ATAGs. */
257typedef struct VbSharedDataHeader {
258 /* Fields present in version 1 */
Randall Spanglerf4ba19d2011-03-17 16:10:21 -0700259 uint32_t magic; /* Magic number for struct
260 * (VB_SHARED_DATA_MAGIC) */
Randall Spangler95c40312011-03-09 15:54:16 -0800261 uint32_t struct_version; /* Version of this structure */
262 uint64_t struct_size; /* Size of this structure in bytes */
263 uint64_t data_size; /* Size of shared data buffer in bytes */
264 uint64_t data_used; /* Amount of shared data used so far */
Randall Spanglerf4ba19d2011-03-17 16:10:21 -0700265 uint32_t flags; /* Flags */
Randall Spangler71415712011-03-21 11:04:50 -0700266 uint32_t reserved0; /* Reserved for padding */
Randall Spangler95c40312011-03-09 15:54:16 -0800267
268 VbPublicKey kernel_subkey; /* Kernel subkey, from firmware */
269 uint64_t kernel_subkey_data_offset; /* Offset of kernel subkey data from
270 * start of this struct */
Randall Spanglerad6824b2011-03-16 19:07:33 -0700271 uint64_t kernel_subkey_data_size; /* Size of kernel subkey data */
Randall Spangler95c40312011-03-09 15:54:16 -0800272
Randall Spanglerad6824b2011-03-16 19:07:33 -0700273 /* Timer values from VbGetTimer(). Unused values are set to 0. If a
274 * function is called mutiple times, these are the times from the
275 * most recent call. */
276 uint64_t timer_load_firmware_start_enter; /* LoadFirmwareStart() - enter */
277 uint64_t timer_load_firmware_start_exit; /* LoadFirmwareStart() - exit */
278 uint64_t timer_load_firmware_enter; /* LoadFirmware() - enter */
279 uint64_t timer_load_firmware_exit; /* LoadFirmware() - exit */
280 uint64_t timer_load_kernel_enter; /* LoadKernel() - enter */
281 uint64_t timer_load_kernel_exit; /* LoadKernel() - exit */
282
Randall Spangler17c71262011-03-18 11:24:27 -0700283 /* Information stored in TPM, as retrieved by firmware */
284 uint32_t fw_version_tpm; /* Current firmware version in TPM */
285 uint32_t kernel_version_tpm; /* Current kernel version in TPM */
286
287 /* Debugging information from LoadFirmware() */
Randall Spanglerf4ba19d2011-03-17 16:10:21 -0700288 uint8_t check_fw_a_result; /* Result of checking RW firmware A */
289 uint8_t check_fw_b_result; /* Result of checking RW firmware B */
290 uint8_t firmware_index; /* Firmware index returned by
291 * LoadFirmware() or 0xFF if failure */
Randall Spangler71415712011-03-21 11:04:50 -0700292 uint8_t reserved1; /* Reserved for padding */
Randall Spangler5ac39bf2011-03-17 17:58:56 -0700293 uint32_t fw_version_tpm_start; /* Firmware TPM version at start of
294 * LoadFirmware() */
Randall Spanglerf4ba19d2011-03-17 16:10:21 -0700295 uint32_t fw_version_lowest; /* Firmware lowest version found */
296
Randall Spangler17c71262011-03-18 11:24:27 -0700297 /* Debugging information from LoadKernel() */
298 uint32_t lk_call_count; /* Number of times LoadKernel() called */
299 VbSharedDataKernelCall lk_calls[VBSD_MAX_KERNEL_CALLS]; /* Info on calls */
300
301 /* Offset and size of supplemental kernel data. Reserve space for these
302 * fields now, so that future LoadKernel() versions can store information
303 * there without needing to shift down whatever data the original
304 * LoadFirmware() might have put immediately following its
305 * VbSharedDataHeader. */
306 uint64_t kernel_supplemental_offset;
307 uint64_t kernel_supplemental_size;
Randall Spangler5ac39bf2011-03-17 17:58:56 -0700308
Randall Spangler95c40312011-03-09 15:54:16 -0800309 /* After read-only firmware which uses version 1 is released, any additional
310 * fields must be added below, and the struct version must be increased.
311 * Before reading/writing those fields, make sure that the struct being
312 * accessed is at least version 2.
313 *
314 * It's always ok for an older firmware to access a newer struct, since all
315 * the fields it knows about are present. Newer firmware needs to use
316 * reasonable defaults when accessing older structs. */
317
318} __attribute__((packed)) VbSharedDataHeader;
319
320#define VB_SHARED_DATA_VERSION 1 /* Version for struct_version */
321
vbendeb3ecaf772010-06-24 16:19:53 -0700322__pragma(pack(pop)) /* Support packing for MSVC. */
Randall Spangler81d09962010-06-23 10:15:38 -0700323
Randall Spanglerd1836442010-06-10 09:59:04 -0700324#endif /* VBOOT_REFERENCE_VBOOT_STRUCT_H_ */