1 /* Copyright 2014 The ChromiumOS Authors 2 * Use of this source code is governed by a BSD-style license that can be 3 * found in the LICENSE file. 4 * 5 * Vboot data structures. 6 * 7 * Note: Many of the structs have pairs of 32-bit fields and reserved fields. 8 * This is to be backwards-compatible with older verified boot data which used 9 * 64-bit fields (when we thought that hey, UEFI is 64-bit so all our fields 10 * should be too). 11 * 12 * Offsets should be padded to 32-bit boundaries, since some architectures 13 * have trouble with accessing unaligned integers. 14 */ 15 16 #ifndef VBOOT_REFERENCE_2STRUCT_H_ 17 #define VBOOT_REFERENCE_2STRUCT_H_ 18 19 #include "2api.h" 20 #include "2constants.h" 21 #include "2crypto.h" 22 #include "2sysincludes.h" 23 24 /* Flags for vb2_shared_data.flags */ 25 enum vb2_shared_data_flags { 26 /* 27 * VB2_SD_FLAG_MANUAL_RECOVERY (1 << 0) is deprecated. This flag is not 28 * necessary since the introduction of persistent context (CL:1716351). 29 * With introducing vb2_boot_mode and differentiating between manual 30 * recovery and broken screen (CL:3274699), it is suggested to leverage 31 * the vb2_boot_mode instead to determine if the user has physically 32 * requested recovery. 33 */ 34 35 /* Developer mode is enabled */ 36 VB2_SD_FLAG_DEV_MODE_ENABLED = (1 << 1), 37 38 /* 39 * TODO: might be nice to add flags for why dev mode is enabled - via 40 * gbb, virtual dev switch, or forced on for testing. 41 */ 42 43 /* Kernel keyblock was verified by signature (not just hash) */ 44 VB2_SD_FLAG_KERNEL_SIGNED = (1 << 2), 45 46 /* Software sync needs to update EC-RO or EC-RW */ 47 VB2_SD_FLAG_ECSYNC_EC_RO = (1 << 3), 48 VB2_SD_FLAG_ECSYNC_EC_RW = (1 << 4), 49 50 /* 51 * VB2_SD_FLAG_ECSYNC_PD_RW (1 << 5) is deprecated. Vboot no 52 * longer supports updating "PD" devices running CrOS EC code. 53 */ 54 55 /* Software sync says EC running RW */ 56 VB2_SD_FLAG_ECSYNC_EC_IN_RW = (1 << 6), 57 58 /* 59 * VB2_SD_FLAG_ECSYNC_PD_IN_RW (1 << 7) is deprecated. Vboot 60 * no longer supports updating "PD" devices running CrOS EC 61 * code. 62 */ 63 64 /* Display is available on this boot */ 65 VB2_SD_FLAG_DISPLAY_AVAILABLE = (1 << 8), 66 67 /* Mirrored hash (Hmir) is updated. */ 68 VB2_SD_FLAG_ECSYNC_HMIR_UPDATED = (1 << 9), 69 }; 70 71 /* Flags for vb2_shared_data.status */ 72 enum vb2_shared_data_status { 73 /* Reinitialized NV data due to invalid checksum */ 74 VB2_SD_STATUS_NV_REINIT = (1 << 0), 75 76 /* NV data has been initialized */ 77 VB2_SD_STATUS_NV_INIT = (1 << 1), 78 79 /* Secure data initialized */ 80 VB2_SD_STATUS_SECDATA_FIRMWARE_INIT = (1 << 2), 81 82 /* Chose a firmware slot */ 83 VB2_SD_STATUS_CHOSE_SLOT = (1 << 3), 84 85 /* Secure data kernel version space initialized */ 86 VB2_SD_STATUS_SECDATA_KERNEL_INIT = (1 << 4), 87 88 /* FWMP secure data initialized */ 89 VB2_SD_STATUS_SECDATA_FWMP_INIT = (1 << 5), 90 91 /* EC Sync completed successfully */ 92 VB2_SD_STATUS_EC_SYNC_COMPLETE = (1 << 6), 93 94 /* Have checked whether we are booting into recovery mode or not. */ 95 VB2_SD_STATUS_RECOVERY_DECIDED = (1 << 7), 96 }; 97 98 /* "V2SD" = vb2_shared_data.magic */ 99 #define VB2_SHARED_DATA_MAGIC 0x44533256 100 101 /* Current version of vb2_shared_data struct */ 102 #define VB2_SHARED_DATA_VERSION_MAJOR 3 103 #define VB2_SHARED_DATA_VERSION_MINOR 2 104 105 /* MAX_SIZE should not be changed without bumping up DATA_VERSION_MAJOR. */ 106 #define VB2_CONTEXT_MAX_SIZE 384 107 108 /* 109 * Data shared between vboot API calls. Stored at the start of the work 110 * buffer. 111 */ 112 struct vb2_shared_data { 113 /* Magic number for struct (VB2_SHARED_DATA_MAGIC) */ 114 uint32_t magic; 115 116 /* Version of this structure */ 117 uint16_t struct_version_major; 118 uint16_t struct_version_minor; 119 120 /* Public fields are stored in the context object */ 121 struct vb2_context ctx; 122 123 /* Padding for adding future vb2_context fields */ 124 uint8_t padding[VB2_CONTEXT_MAX_SIZE - sizeof(struct vb2_context)]; 125 126 /* Work buffer length in bytes. */ 127 uint32_t workbuf_size; 128 129 /* 130 * Amount of work buffer used so far. Verified boot sub-calls use 131 * this to know where the unused work area starts. 132 */ 133 uint32_t workbuf_used; 134 135 /* Flags; see enum vb2_shared_data_flags */ 136 uint32_t flags; 137 138 /* 139 * Reason we are in recovery mode this boot (enum vb2_nv_recovery), or 140 * 0 if we aren't. 141 */ 142 uint32_t recovery_reason; 143 144 /* Firmware slot used last boot (0=A, 1=B) */ 145 uint32_t last_fw_slot; 146 147 /* Result of last boot (enum vb2_fw_result) */ 148 uint32_t last_fw_result; 149 150 /* Firmware slot used this boot */ 151 uint32_t fw_slot; 152 153 /* 154 * Version for this slot (top 16 bits = key, lower 16 bits = firmware). 155 * 156 * TODO: Make this a union to allow getting/setting those versions 157 * separately? 158 */ 159 uint32_t fw_version; 160 161 /* Version from secdata_firmware (must be <= fw_version to boot). */ 162 uint32_t fw_version_secdata; 163 164 /* 165 * Status flags for this boot; see enum vb2_shared_data_status. Status 166 * is "what we've done"; flags above are "decisions we've made". 167 */ 168 uint32_t status; 169 170 /* Offset from start of this struct to GBB header */ 171 uint32_t gbb_offset; 172 173 /********************************************************************** 174 * Data from kernel verification stage. 175 * 176 * TODO: shouldn't be part of the main struct, since that needlessly 177 * uses more memory during firmware verification. 178 */ 179 180 /* 181 * Version for the current kernel (top 16 bits = key, lower 16 bits = 182 * kernel preamble). 183 * 184 * TODO: Make this a union to allow getting/setting those versions 185 * separately? 186 */ 187 uint32_t kernel_version; 188 189 /* Version from secdata_kernel (must be <= kernel_version to boot) */ 190 uint32_t kernel_version_secdata; 191 192 /********************************************************************** 193 * Temporary variables used during firmware verification. These don't 194 * really need to persist through to the OS, but there's nowhere else 195 * we can put them. 196 */ 197 198 /* Offset of preamble from start of vblock */ 199 uint32_t vblock_preamble_offset; 200 201 /* 202 * Offset and size of packed data key in work buffer. Size is 0 if 203 * data key is not stored in the work buffer. 204 */ 205 uint32_t data_key_offset; 206 uint32_t data_key_size; 207 208 /* 209 * Offset and size of firmware preamble in work buffer. Size is 0 if 210 * preamble is not stored in the work buffer. 211 */ 212 uint32_t preamble_offset; 213 uint32_t preamble_size; 214 215 /* 216 * Offset and size of hash context in work buffer. Size is 0 if 217 * hash context is not stored in the work buffer. 218 */ 219 uint32_t hash_offset; 220 uint32_t hash_size; 221 222 /* 223 * Current tag we're hashing 224 * 225 * For new structs, this is the offset of the vb2_signature struct 226 * in the work buffer. 227 * 228 * TODO: rename to hash_sig_offset when vboot1 structs are deprecated. 229 */ 230 uint32_t hash_tag; 231 232 /* Amount of data we still expect to hash */ 233 uint32_t hash_remaining_size; 234 235 /********************************************************************** 236 * Temporary variables used during kernel verification. These don't 237 * really need to persist through to the OS, but there's nowhere else 238 * we can put them. 239 * 240 * TODO: make a union with the firmware verification temp variables, 241 * or make both of them workbuf-allocated sub-structs, so that we can 242 * overlap them so kernel variables don't bloat firmware verification 243 * stage memory requirements. 244 */ 245 246 /* 247 * Formerly a pointer to vboot1 shared data header ("VBSD"). Caller 248 * may now export a copy of VBSD via vb2api_export_vbsd(). 249 * TODO: Remove this field and bump struct_version_major. 250 */ 251 uintptr_t reserved0; 252 253 /* 254 * Offset and size of packed kernel key in work buffer. Size is 0 if 255 * subkey is not stored in the work buffer. Note that kernel key may 256 * be inside the firmware preamble. 257 */ 258 uint32_t kernel_key_offset; 259 uint32_t kernel_key_size; 260 } __attribute__((packed)); 261 262 /****************************************************************************/ 263 264 /* Signature at start of the GBB 265 * Note that if you compile in the signature as is, you are likely to break any 266 * tools that search for the signature. */ 267 #define VB2_GBB_SIGNATURE "$GBB" 268 #define VB2_GBB_SIGNATURE_SIZE 4 269 #define VB2_GBB_XOR_CHARS "****" 270 /* TODO: can we write a macro to produce this at compile time? */ 271 #define VB2_GBB_XOR_SIGNATURE { 0x0e, 0x6d, 0x68, 0x68 } 272 273 #define VB2_GBB_HWID_DIGEST_SIZE 32 274 275 /* VB2 GBB struct version */ 276 #define VB2_GBB_MAJOR_VER 1 277 #define VB2_GBB_MINOR_VER 2 278 /* v1.2 - added fields for sha256 digest of the HWID */ 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 287 /* Flags (see enum vb2_gbb_flag in 2gbb_flags.h) */ 288 vb2_gbb_flags_t flags; 289 290 /* Offsets (from start of header) and sizes (in bytes) of components */ 291 uint32_t hwid_offset; /* HWID */ 292 uint32_t hwid_size; 293 uint32_t rootkey_offset; /* Root key */ 294 uint32_t rootkey_size; 295 uint32_t bmpfv_offset; /* BMP FV; deprecated in current FW */ 296 uint32_t bmpfv_size; 297 uint32_t recovery_key_offset; /* Recovery key */ 298 uint32_t recovery_key_size; 299 300 /* Added in version 1.2 */ 301 uint8_t hwid_digest[VB2_GBB_HWID_DIGEST_SIZE]; /* SHA-256 of HWID */ 302 303 /* Pad to match EXPECTED_VB2_GBB_HEADER_SIZE. Initialize to 0. */ 304 uint8_t pad[48]; 305 } __attribute__((packed)); 306 307 #define EXPECTED_VB2_GBB_HEADER_SIZE 128 308 309 /* VB2_GBB_FLAGS_OFFSET exposed in 2constants.h */ 310 _Static_assert(VB2_GBB_FLAGS_OFFSET == offsetof(struct vb2_gbb_header, flags), 311 "VB2_GBB_FLAGS_OFFSET set incorrectly"); 312 313 /****************************************************************************/ 314 315 /* Packed public key data */ 316 struct vb2_packed_key { 317 /* Offset of key data from start of this struct */ 318 uint32_t key_offset; 319 uint32_t reserved0; 320 321 /* Size of key data in bytes (NOT strength of key in bits) */ 322 uint32_t key_size; 323 uint32_t reserved1; 324 325 /* Signature algorithm used by the key (enum vb2_crypto_algorithm) */ 326 uint32_t algorithm; 327 uint32_t reserved2; 328 329 /* Key version */ 330 uint32_t key_version; 331 uint32_t reserved3; 332 333 /* TODO: when redoing this struct, add a text description of the key */ 334 } __attribute__((packed)); 335 336 #define EXPECTED_VB2_PACKED_KEY_SIZE 32 337 338 /****************************************************************************/ 339 340 /* Signature data (a secure hash, possibly signed) */ 341 struct vb2_signature { 342 /* Offset of signature data from start of this struct */ 343 uint32_t sig_offset; 344 uint32_t reserved0; 345 346 /* Size of signature data in bytes */ 347 uint32_t sig_size; 348 uint32_t reserved1; 349 350 /* Size of the data block which was signed in bytes */ 351 uint32_t data_size; 352 uint32_t reserved2; 353 } __attribute__((packed)); 354 355 #define EXPECTED_VB2_SIGNATURE_SIZE 24 356 357 /****************************************************************************/ 358 359 #define VB2_KEYBLOCK_MAGIC "CHROMEOS" 360 #define VB2_KEYBLOCK_MAGIC_SIZE 8 361 362 #define VB2_KEYBLOCK_VERSION_MAJOR 2 363 #define VB2_KEYBLOCK_VERSION_MINOR 1 364 365 /* 366 * Keyblock flags. 367 * 368 * The following flags set where the key is valid. Not used by firmware 369 * verification; only kernel verification. 370 */ 371 #define VB2_KEYBLOCK_FLAG_DEVELOPER_0 0x1 /* Developer switch off */ 372 #define VB2_KEYBLOCK_FLAG_DEVELOPER_1 0x2 /* Developer switch on */ 373 #define VB2_KEYBLOCK_FLAG_RECOVERY_0 0x4 /* Not recovery mode */ 374 #define VB2_KEYBLOCK_FLAG_RECOVERY_1 0x8 /* Recovery mode */ 375 #define VB2_KEYBLOCK_FLAG_MINIOS_0 0x10 /* Not miniOS boot */ 376 #define VB2_KEYBLOCK_FLAG_MINIOS_1 0x20 /* miniOS boot */ 377 378 /* 379 * Keyblock, containing the public key used to sign some other chunk of data. 380 * 381 * This should be followed by: 382 * 1) The data_key key data, pointed to by data_key.key_offset. 383 * 2) The checksum data for (vb2_keyblock + data_key data), pointed to 384 * by keyblock_checksum.sig_offset. 385 * 3) The signature data for (vb2_keyblock + data_key data), pointed to 386 * by keyblock_signature.sig_offset. 387 */ 388 struct vb2_keyblock { 389 /* Magic number */ 390 uint8_t magic[VB2_KEYBLOCK_MAGIC_SIZE]; 391 392 /* Version of this header format */ 393 uint32_t header_version_major; 394 uint32_t header_version_minor; 395 396 /* 397 * Length of this entire keyblock, including keys, signatures, and 398 * padding, in bytes 399 */ 400 uint32_t keyblock_size; 401 uint32_t reserved0; 402 403 /* 404 * Signature for this keyblock (header + data pointed to by data_key) 405 * For use with signed data keys 406 */ 407 struct vb2_signature keyblock_signature; 408 409 /* 410 * SHA-512 hash for this keyblock (header + data pointed to by 411 * data_key) For use with unsigned data keys. 412 * 413 * Only supported for kernel keyblocks, not firmware keyblocks. 414 */ 415 struct vb2_signature keyblock_hash; 416 417 /* Flags for key (VB2_KEYBLOCK_FLAG_*) */ 418 uint32_t keyblock_flags; 419 uint32_t reserved1; 420 421 /* Key to verify the chunk of data */ 422 struct vb2_packed_key data_key; 423 } __attribute__((packed)); 424 425 #define EXPECTED_VB2_KEYBLOCK_SIZE 112 426 427 /****************************************************************************/ 428 429 /* 430 * Rollback protection currently uses a 32-bit value comprised of the bottom 16 431 * bits of the (firmware or kernel) preamble version and the bottom 16 bits of 432 * the key version. So each of those versions is effectively limited to 16 433 * bits even though they get stored in 32-bit fields. 434 */ 435 #define VB2_MAX_KEY_VERSION 0xffff 436 #define VB2_MAX_PREAMBLE_VERSION 0xffff 437 438 /****************************************************************************/ 439 440 /* Firmware preamble header */ 441 #define VB2_FIRMWARE_PREAMBLE_HEADER_VERSION_MAJOR 2 442 #define VB2_FIRMWARE_PREAMBLE_HEADER_VERSION_MINOR 1 443 444 /* Flags for vb2_fw_preamble.flags */ 445 /* Use RO-normal firmware (deprecated; do not use) */ 446 #define VB2_FIRMWARE_PREAMBLE_USE_RO_NORMAL 0x00000001 447 /* Do not allow use of any hardware crypto accelerators. 448 * (deprecated; use VB2_SECDATA_KERNEL_FLAG_HWCRYPTO_ALLOWED instead) 449 */ 450 #define VB2_FIRMWARE_PREAMBLE_DISALLOW_HWCRYPTO 0x00000002 451 452 /* Premable block for rewritable firmware, vboot1 version 2.1. 453 * 454 * The firmware preamble header should be followed by: 455 * 1) The kernel_subkey key data, pointed to by kernel_subkey.key_offset. 456 * 2) The signature data for the firmware body, pointed to by 457 * body_signature.sig_offset. 458 * 3) The signature data for (header + kernel_subkey data + body signature 459 * data), pointed to by preamble_signature.sig_offset. 460 */ 461 struct vb2_fw_preamble { 462 /* 463 * Size of this preamble, including keys, signatures, and padding, in 464 * bytes 465 */ 466 uint32_t preamble_size; 467 uint32_t reserved0; 468 469 /* 470 * Signature for this preamble (header + kernel subkey + body 471 * signature) 472 */ 473 struct vb2_signature preamble_signature; 474 475 /* Version of this header format */ 476 uint32_t header_version_major; 477 uint32_t header_version_minor; 478 479 /* Firmware version */ 480 uint32_t firmware_version; 481 uint32_t reserved1; 482 483 /* Key to verify kernel keyblock */ 484 struct vb2_packed_key kernel_subkey; 485 486 /* Signature for the firmware body */ 487 struct vb2_signature body_signature; 488 489 /* 490 * Fields added in header version 2.1. You must verify the header 491 * version before reading these fields! 492 */ 493 494 /* 495 * Flags; see VB2_FIRMWARE_PREAMBLE_*. Readers should return 0 for 496 * header version < 2.1. 497 */ 498 uint32_t flags; 499 } __attribute__((packed)); 500 501 #define EXPECTED_VB2_FW_PREAMBLE_SIZE 108 502 503 _Static_assert(EXPECTED_VB2_FW_PREAMBLE_SIZE == sizeof(struct vb2_fw_preamble), 504 "EXPECTED_VB2_FW_PREAMBLE_SIZE incorrect"); 505 506 /****************************************************************************/ 507 508 /* Kernel preamble header */ 509 #define VB2_KERNEL_PREAMBLE_HEADER_VERSION_MAJOR 2 510 #define VB2_KERNEL_PREAMBLE_HEADER_VERSION_MINOR 2 511 512 /* Flags for vb2_kernel_preamble.flags */ 513 /* Kernel image type = bits 1:0 */ 514 #define VB2_KERNEL_PREAMBLE_KERNEL_TYPE_MASK 0x00000003 515 #define VB2_KERNEL_PREAMBLE_KERNEL_TYPE_CROS 0 516 #define VB2_KERNEL_PREAMBLE_KERNEL_TYPE_BOOTIMG 1 517 #define VB2_KERNEL_PREAMBLE_KERNEL_TYPE_MULTIBOOT 2 518 /* Kernel type 3 is reserved for future use */ 519 520 /* 521 * Preamble block for kernel, version 2.2 522 * 523 * This should be followed by: 524 * 1) The signature data for the kernel body, pointed to by 525 * body_signature.sig_offset. 526 * 2) The signature data for (vb2_kernel_preamble + body signature data), 527 * pointed to by preamble_signature.sig_offset. 528 * 3) The 16-bit vmlinuz header, which is used for reconstruction of 529 * vmlinuz image. 530 */ 531 struct vb2_kernel_preamble { 532 /* 533 * Size of this preamble, including keys, signatures, vmlinuz header, 534 * and padding, in bytes 535 */ 536 uint32_t preamble_size; 537 uint32_t reserved0; 538 539 /* Signature for this preamble (header + body signature) */ 540 struct vb2_signature preamble_signature; 541 542 /* Version of this header format */ 543 uint32_t header_version_major; 544 uint32_t header_version_minor; 545 546 /* Kernel version */ 547 uint32_t kernel_version; 548 uint32_t reserved1; 549 550 /* Load address for kernel body */ 551 uint64_t body_load_address; 552 /* TODO (vboot 2.1): we never used that */ 553 554 /* Address of bootloader, after body is loaded at body_load_address */ 555 uint64_t bootloader_address; 556 /* TODO (vboot 2.1): should be a 32-bit offset */ 557 558 /* Size of bootloader in bytes */ 559 uint32_t bootloader_size; 560 uint32_t reserved2; 561 562 /* Signature for the kernel body */ 563 struct vb2_signature body_signature; 564 565 /* 566 * TODO (vboot 2.1): fields for kernel offset and size. Right now the 567 * size is implicitly the same as the size of data signed by the body 568 * signature, and the offset is implicitly at the end of the preamble. 569 * But that forces us to pad the preamble to 64KB rather than just 570 * having a tiny preamble and an offset field. 571 */ 572 573 /* 574 * Fields added in header version 2.1. You must verify the header 575 * version before reading these fields! 576 */ 577 578 /* 579 * Address of 16-bit header for vmlinuz reassembly. Readers should 580 * return 0 for header version < 2.1. 581 */ 582 uint64_t vmlinuz_header_address; 583 584 /* Size of 16-bit header for vmlinuz in bytes. Readers should return 0 585 for header version < 2.1 */ 586 uint32_t vmlinuz_header_size; 587 uint32_t reserved3; 588 589 /* 590 * Fields added in header version 2.2. You must verify the header 591 * version before reading these fields! 592 */ 593 594 /* 595 * Flags; see VB2_KERNEL_PREAMBLE_*. Readers should return 0 for 596 * header version < 2.2. Flags field is currently defined as: 597 * [31:2] - Reserved (for future use) 598 * [1:0] - Kernel image type (0b00 - CrOS, 599 * 0b01 - bootimg, 600 * 0b10 - multiboot) 601 */ 602 uint32_t flags; 603 } __attribute__((packed)); 604 605 #define EXPECTED_VB2_KERNEL_PREAMBLE_2_0_SIZE 96 606 #define EXPECTED_VB2_KERNEL_PREAMBLE_2_1_SIZE 112 607 #define EXPECTED_VB2_KERNEL_PREAMBLE_2_2_SIZE 116 608 609 _Static_assert(EXPECTED_VB2_KERNEL_PREAMBLE_2_0_SIZE 610 == offsetof(struct vb2_kernel_preamble, vmlinuz_header_address), 611 "EXPECTED_VB2_KERNEL_PREAMBLE_2_0_SIZE incorrect"); 612 613 _Static_assert(EXPECTED_VB2_KERNEL_PREAMBLE_2_1_SIZE 614 == offsetof(struct vb2_kernel_preamble, flags), 615 "EXPECTED_VB2_KERNEL_PREAMBLE_2_1_SIZE incorrect"); 616 617 _Static_assert(EXPECTED_VB2_KERNEL_PREAMBLE_2_2_SIZE 618 == sizeof(struct vb2_kernel_preamble), 619 "EXPECTED_VB2_KERNEL_PREAMBLE_2_2_SIZE incorrect"); 620 621 #endif /* VBOOT_REFERENCE_2STRUCT_H_ */ 622