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         /* Enable serial */
 280         VB2_GBB_FLAG_ENABLE_SERIAL = (1 << 14),
 281 };
 282
 283 struct vb2_gbb_header {
 284         /* Fields present in version 1.1 */
 285         uint8_t  signature[VB2_GBB_SIGNATURE_SIZE]; /* VB2_GBB_SIGNATURE */
 286         uint16_t major_version;   /* See VB2_GBB_MAJOR_VER */
 287         uint16_t minor_version;   /* See VB2_GBB_MINOR_VER */
 288         uint32_t header_size;     /* Size of GBB header in bytes */
 289         uint32_t flags;           /* Flags (see enum vb2_gbb_flag) */
 290
 291         /* Offsets (from start of header) and sizes (in bytes) of components */
 292         uint32_t hwid_offset;           /* HWID */
 293         uint32_t hwid_size;
 294         uint32_t rootkey_offset;        /* Root key */
 295         uint32_t rootkey_size;
 296         uint32_t bmpfv_offset;          /* BMP FV */
 297         uint32_t bmpfv_size;
 298         uint32_t recovery_key_offset;   /* Recovery key */
 299         uint32_t recovery_key_size;
 300
 301         /* Added in version 1.2 */
 302         uint8_t  hwid_digest[VB2_GBB_HWID_DIGEST_SIZE]; /* SHA-256 of HWID */
 303
 304         /* Pad to match EXPECETED_VB2_GBB_HEADER_SIZE.  Initialize to 0. */
 305         uint8_t  pad[48];
 306 } __attribute__((packed));
 307
 308 /* The GBB is used outside of vboot_reference, so this size is important. */
 309 #define EXPECTED_VB2_GBB_HEADER_SIZE 128
 310
 311 /*
 312  * Root key hash for Ryu devices only.  Contains the hash of the root key.
 313  * This will be embedded somewhere inside the RO part of the firmware, so that
 314  * it can verify the GBB contains only the official root key.
 315  */
 316
 317 #define RYU_ROOT_KEY_HASH_MAGIC "RtKyHash"
 318 #define RYU_ROOT_KEY_HASH_MAGIC_INVCASE "rTkYhASH"
 319 #define RYU_ROOT_KEY_HASH_MAGIC_SIZE 8
 320
 321 #define RYU_ROOT_KEY_HASH_VERSION_MAJOR 1
 322 #define RYU_ROOT_KEY_HASH_VERSION_MINOR 0
 323
 324 struct vb2_ryu_root_key_hash {
 325         /* Magic number (RYU_ROOT_KEY_HASH_MAGIC) */
 326         uint8_t magic[RYU_ROOT_KEY_HASH_MAGIC_SIZE];
 327
 328         /* Version of this struct */
 329         uint16_t header_version_major;
 330         uint16_t header_version_minor;
 331
 332         /*
 333          * Length of this struct, in bytes, including any variable length data
 334          * which follows (there is none, yet).
 335          */
 336         uint32_t struct_size;
 337
 338         /*
 339          * SHA-256 hash digest of the entire root key section from the GBB.  If
 340          * all 0 bytes, all root keys will be treated as if matching.
 341          */
 342         uint8_t root_key_hash_digest[32];
 343 };
 344
 345 #define EXPECTED_VB2_RYU_ROOT_KEY_HASH_SIZE 48
 346
 347 #endif  /* VBOOT_REFERENCE_VBOOT_2STRUCT_H_ */