1 /* Copyright 2022 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 * Definition of the vb2_context structure and related constants. 6 */ 7 8 #ifndef VBOOT_REFERENCE_2CONTEXT_H_ 9 #define VBOOT_REFERENCE_2CONTEXT_H_ 10 11 #include "2constants.h" 12 13 /* Flags for vb2_context. 14 * 15 * Unless otherwise noted, flags are set by verified boot and may be read (but 16 * not set or cleared) by the caller. 17 */ 18 enum vb2_context_flags { 19 20 /* 21 * Verified boot has changed nvdata[]. Caller must save nvdata[] back 22 * to its underlying storage, then may clear this flag. 23 */ 24 VB2_CONTEXT_NVDATA_CHANGED = (1 << 0), 25 26 /* 27 * Verified boot has changed secdata_firmware[]. Caller must save 28 * secdata_firmware[] back to its underlying storage, then may clear 29 * this flag. 30 */ 31 VB2_CONTEXT_SECDATA_FIRMWARE_CHANGED = (1 << 1), 32 33 /* Recovery mode is requested this boot */ 34 VB2_CONTEXT_RECOVERY_MODE = (1 << 2), 35 36 /* Developer mode is requested this boot */ 37 VB2_CONTEXT_DEVELOPER_MODE = (1 << 3), 38 39 /* 40 * Force recovery mode due to physical user request. Caller may set 41 * this flag when initializing the context. 42 */ 43 VB2_CONTEXT_FORCE_RECOVERY_MODE = (1 << 4), 44 45 /* 46 * Force developer mode enabled. Caller may set this flag when 47 * initializing the context. Previously used for forcing developer 48 * mode with physical dev switch. 49 * 50 * Deprecated as part of chromium:942901. 51 */ 52 VB2_CONTEXT_DEPRECATED_FORCE_DEVELOPER_MODE = (1 << 5), 53 54 /* Using firmware slot B. If this flag is clear, using slot A. */ 55 VB2_CONTEXT_FW_SLOT_B = (1 << 6), 56 57 /* RAM should be cleared by caller this boot */ 58 VB2_CONTEXT_CLEAR_RAM = (1 << 7), 59 60 /* Wipeout by the app should be requested. */ 61 VB2_CONTEXT_FORCE_WIPEOUT_MODE = (1 << 8), 62 63 /* Erase developer mode state if it is enabled. */ 64 VB2_CONTEXT_DISABLE_DEVELOPER_MODE = (1 << 9), 65 66 /* 67 * Verified boot has changed secdata_kernel[]. Caller must save 68 * secdata_kernel[] back to its underlying storage, then may clear 69 * this flag. 70 */ 71 VB2_CONTEXT_SECDATA_KERNEL_CHANGED = (1 << 10), 72 73 /* 74 * Allow kernel verification to roll forward the version in 75 * secdata_kernel[]. Caller may set this flag before calling 76 * vb2api_kernel_phase3(). 77 */ 78 VB2_CONTEXT_ALLOW_KERNEL_ROLL_FORWARD = (1 << 11), 79 80 /* 81 * Boot optimistically: don't touch failure counters. Caller may set 82 * this flag when initializing the context. 83 */ 84 VB2_CONTEXT_NOFAIL_BOOT = (1 << 12), 85 86 /* 87 * secdata is not ready this boot, but should be ready next boot. It 88 * would like to reboot. The decision whether to reboot or not must be 89 * deferred until vboot, because rebooting all the time before then 90 * could cause a device with malfunctioning secdata to get stuck in an 91 * unrecoverable crash loop. 92 */ 93 VB2_CONTEXT_SECDATA_WANTS_REBOOT = (1 << 13), 94 95 /* 96 * Boot is S3->S0 resume, not S5->S0 normal boot. Caller may set this 97 * flag when initializing the context. 98 */ 99 VB2_CONTEXT_S3_RESUME = (1 << 14), 100 101 /* 102 * System supports EC software sync. Caller may set this flag at any 103 * time before calling vb2api_kernel_phase2(). 104 */ 105 VB2_CONTEXT_EC_SYNC_SUPPORTED = (1 << 15), 106 107 /* 108 * EC software sync is slow to update; warning screen should be 109 * displayed. Caller may set this flag at any time before calling 110 * vb2api_kernel_phase2(). 111 */ 112 VB2_CONTEXT_EC_SYNC_SLOW = (1 << 16), 113 114 /* 115 * EC firmware supports early firmware selection; two EC images exist, 116 * and EC may have already verified and jumped to EC-RW prior to EC 117 * software sync. Deprecated as part of chromium:1038259. 118 */ 119 VB2_CONTEXT_DEPRECATED_EC_EFS = (1 << 17), 120 121 /* 122 * NV storage uses data format V2. Data is size VB2_NVDATA_SIZE_V2, 123 * not VB2_NVDATA_SIZE. 124 * 125 * Caller must set this flag when initializing the context to use V2. 126 * (Vboot cannot infer the data size from the data itself, because the 127 * data provided by the caller could be uninitialized.) 128 */ 129 VB2_CONTEXT_NVDATA_V2 = (1 << 18), 130 131 /* 132 * Allow vendor data to be set via the vendor data ui. 133 * 134 * Deprecated with CL:2512740. 135 */ 136 VB2_CONTEXT_DEPRECATED_VENDOR_DATA_SETTABLE = (1 << 19), 137 138 /* 139 * Caller may set this before running vb2api_fw_phase1. In this case, 140 * it means: "Display is available on this boot. Please advertise 141 * as such to downstream vboot code and users." 142 * 143 * vboot may also set this before returning from vb2api_fw_phase1. 144 * In this case, it means: "Please initialize display so that it is 145 * available to downstream vboot code and users." This is used when 146 * vboot encounters some internally-generated request for display 147 * support. 148 */ 149 VB2_CONTEXT_DISPLAY_INIT = (1 << 20), 150 151 /* 152 * Caller may set this before running vb2api_kernel_phase1. It means 153 * that there is no FWMP on this system, and thus default values should 154 * be used instead. 155 * 156 * Caller should *not* set this when FWMP is available but invalid. 157 */ 158 VB2_CONTEXT_NO_SECDATA_FWMP = (1 << 21), 159 160 /* 161 * Enable detachable menu ui (volume up/down + power). 162 * 163 * Deprecated with CL:1975390. 164 */ 165 VB2_CONTEXT_DEPRECATED_DETACHABLE_UI = (1 << 22), 166 167 /* 168 * NO_BOOT means the OS is not allowed to boot. Only relevant for EFS2. 169 */ 170 VB2_CONTEXT_NO_BOOT = (1 << 23), 171 172 /* 173 * TRUSTED means EC is running an RO copy and PD isn't enabled. At 174 * least that was last known to the GSC. If EC RO is correctly behaving, 175 * it doesn't jump to RW when this flag is set. 176 */ 177 VB2_CONTEXT_EC_TRUSTED = (1 << 24), 178 179 /* 180 * Boot into developer mode is allowed by FWMP or GBB flags. 181 */ 182 VB2_CONTEXT_DEV_BOOT_ALLOWED = (1 << 25), 183 184 /* 185 * Boot into developer mode from external disk is allowed by nvdata, 186 * FWMP or GBB flags. 187 */ 188 VB2_CONTEXT_DEV_BOOT_EXTERNAL_ALLOWED = (1 << 26), 189 190 /* 191 * Boot into developer mode from alternate bootloader is allowed by 192 * nvdata, FWMP or GBB flags. 193 */ 194 VB2_CONTEXT_DEV_BOOT_ALTFW_ALLOWED = (1 << 27), 195 196 /* 197 * If this is set after kernel verification, caller should disable the 198 * TPM before jumping to kernel. 199 */ 200 VB2_CONTEXT_DISABLE_TPM = (1 << 28), 201 202 /* 203 * Indicates there is only one RW slot present. Caller should set this 204 * flag when initializing the context if the flash layout does not 205 * support two RW slots. 206 */ 207 VB2_CONTEXT_SLOT_A_ONLY = (1 << 29), 208 }; 209 210 /* Helper for aligning fields in vb2_context. */ 211 #define VB2_PAD_STRUCT3(size, align, count) \ 212 uint8_t _pad##count[align - (((size - 1) % align) + 1)] 213 #define VB2_PAD_STRUCT2(size, align, count) VB2_PAD_STRUCT3(size, align, count) 214 #define VB2_PAD_STRUCT(size, align) VB2_PAD_STRUCT2(size, align, __COUNTER__) 215 216 /* 217 * Context for firmware verification. Pass this to all vboot APIs. 218 * 219 * Context is stored as part of vb2_shared_data, initialized with vb2api_init(). 220 * Subsequent retrieval of the context object should be done by calling 221 * vb2api_reinit(), e.g. if switching firmware applications. 222 * 223 * The context struct can be seen as the "publicly accessible" portion of 224 * vb2_shared_data, and thus does not require its own magic and version fields. 225 */ 226 struct vb2_context { 227 228 /********************************************************************** 229 * Fields caller must initialize before calling any API functions. 230 */ 231 232 /* 233 * Flags; see vb2_context_flags. Some flags may only be set by caller 234 * prior to calling vboot functions. 235 */ 236 uint64_t flags; 237 238 /* 239 * Non-volatile data. Caller must fill this from some non-volatile 240 * location before calling vb2api_fw_phase1. If the 241 * VB2_CONTEXT_NVDATA_CHANGED flag is set when a vb2api function 242 * returns, caller must save the data back to the non-volatile location 243 * and then clear the flag. 244 */ 245 uint8_t nvdata[VB2_NVDATA_SIZE_V2]; 246 VB2_PAD_STRUCT(VB2_NVDATA_SIZE_V2, 8); 247 248 /* 249 * Secure data for firmware verification stage. Caller must fill this 250 * from some secure non-volatile location before calling 251 * vb2api_fw_phase1. If the VB2_CONTEXT_SECDATA_FIRMWARE_CHANGED flag 252 * is set when a function returns, caller must save the data back to the 253 * secure non-volatile location and then clear the flag. 254 */ 255 uint8_t secdata_firmware[VB2_SECDATA_FIRMWARE_SIZE]; 256 VB2_PAD_STRUCT(VB2_SECDATA_FIRMWARE_SIZE, 8); 257 258 /********************************************************************** 259 * Fields caller must initialize before calling vb2api_kernel_phase1(). 260 */ 261 262 /* 263 * Secure data for kernel verification stage. Caller must fill this 264 * from some secure non-volatile location before calling 265 * vb2api_kernel_phase1. If the VB2_CONTEXT_SECDATA_KERNEL_CHANGED 266 * flag is set when a function returns, caller must save the data back 267 * to the secure non-volatile location and then clear the flag. 268 */ 269 uint8_t secdata_kernel[VB2_SECDATA_KERNEL_MAX_SIZE]; 270 VB2_PAD_STRUCT(VB2_SECDATA_KERNEL_MAX_SIZE, 8); 271 272 /* 273 * Firmware management parameters (FWMP) secure data. Caller must fill 274 * this from some secure non-volatile location before calling 275 * vb2api_kernel_phase1. Since FWMP is a variable-size space, caller 276 * should initially fill in VB2_SECDATA_FWMP_MIN_SIZE bytes, and call 277 * vb2_secdata_fwmp_check() to see whether more should be read. If the 278 * VB2_CONTEXT_SECDATA_FWMP_CHANGED flag is set when a function 279 * returns, caller must save the data back to the secure non-volatile 280 * location and then clear the flag. 281 */ 282 uint8_t secdata_fwmp[VB2_SECDATA_FWMP_MAX_SIZE]; 283 VB2_PAD_STRUCT(VB2_SECDATA_FWMP_MAX_SIZE, 8); 284 285 /********************************************************************** 286 * Fields below added in struct version 3.1. 287 */ 288 289 /* 290 * Mutually exclusive boot mode (from enum vb2_boot_mode). 291 * This constant is initialized after calling vb2api_fw_phase1(). 292 */ 293 const uint8_t boot_mode; 294 }; 295 296 #endif /* VBOOT_REFERENCE_2CONTEXT_H_ */ 297