1 /* Copyright (c) 2013 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 6 /* APIs between calling firmware and vboot_reference 7 * 8 * General notes: 9 * 10 * TODO: split this file into a vboot_entry_points.h file which contains the 11 * entry points for the firmware to call vboot_reference, and a 12 * vboot_firmware_exports.h which contains the APIs to be implemented by the 13 * calling firmware and exported to vboot_reference. 14 * 15 * Notes: 16 * * Assumes this code is never called in the S3 resume path. TPM resume 17 * must be done elsewhere, and VB2_NV_DEBUG_RESET_MODE is ignored. 18 */ 19 20 #ifndef VBOOT_2_API_H_ 21 #define VBOOT_2_API_H_ 22 #include <stdint.h> 23 24 #include "2common.h" 25 #include "2crypto.h" 26 #include "2fw_hash_tags.h" 27 #include "2guid.h" 28 #include "2recovery_reasons.h" 29 #include "2return_codes.h" 30 31 /* Size of non-volatile data used by vboot */ 32 #define VB2_NVDATA_SIZE 16 33 34 /* Size of secure data used by vboot */ 35 #define VB2_SECDATA_SIZE 10 36 37 /* 38 * Recommended size of work buffer. 39 * 40 * TODO: The recommended size really depends on which key algorithms are 41 * used. Should have a better / more accurate recommendation than this. 42 */ 43 #define VB2_WORKBUF_RECOMMENDED_SIZE (12 * 1024) 44 45 /* Recommended buffer size for vb2api_get_pcr_digest */ 46 #define VB2_PCR_DIGEST_RECOMMENDED_SIZE 32 47 48 /* Flags for vb2_context. 49 * 50 * Unless otherwise noted, flags are set by verified boot and may be read (but 51 * not set or cleared) by the caller. 52 */ 53 enum vb2_context_flags { 54 55 /* 56 * Verified boot has changed nvdata[]. Caller must save nvdata[] back 57 * to its underlying storage, then may clear this flag. 58 */ 59 VB2_CONTEXT_NVDATA_CHANGED = (1 << 0), 60 61 /* 62 * Verified boot has changed secdata[]. Caller must save secdata[] 63 * back to its underlying storage, then may clear this flag. 64 */ 65 VB2_CONTEXT_SECDATA_CHANGED = (1 << 1), 66 67 /* Recovery mode is requested this boot */ 68 VB2_CONTEXT_RECOVERY_MODE = (1 << 2), 69 70 /* Developer mode is requested this boot */ 71 VB2_CONTEXT_DEVELOPER_MODE = (1 << 3), 72 73 /* 74 * Force recovery mode due to physical user request. Caller may set 75 * this flag when initializing the context. 76 */ 77 VB2_CONTEXT_FORCE_RECOVERY_MODE = (1 << 4), 78 79 /* 80 * Force developer mode enabled. Caller may set this flag when 81 * initializing the context. 82 */ 83 VB2_CONTEXT_FORCE_DEVELOPER_MODE = (1 << 5), 84 85 /* Using firmware slot B. If this flag is clear, using slot A. */ 86 VB2_CONTEXT_FW_SLOT_B = (1 << 6), 87 88 /* RAM should be cleared by caller this boot */ 89 VB2_CONTEXT_CLEAR_RAM = (1 << 7), 90 }; 91 92 /* 93 * Context for firmware verification. Pass this to all vboot APIs. 94 * 95 * Caller may relocate this between calls to vboot APIs. 96 */ 97 struct vb2_context { 98 /********************************************************************** 99 * Fields which must be initialized by caller. 100 */ 101 102 /* 103 * Flags; see vb2_context_flags. Some flags may only be set by caller 104 * prior to calling vboot functions. 105 */ 106 uint32_t flags; 107 108 /* 109 * Work buffer, and length in bytes. Caller may relocate this between 110 * calls to vboot APIs; it contains no internal pointers. Caller must 111 * not examine the contents of this work buffer directly. 112 */ 113 uint8_t *workbuf; 114 uint32_t workbuf_size; 115 116 /* 117 * Non-volatile data. Caller must fill this from some non-volatile 118 * location. If the VB2_CONTEXT_NVDATA_CHANGED flag is set when a 119 * vb2api function returns, caller must save the data back to the 120 * non-volatile location and then clear the flag. 121 */ 122 uint8_t nvdata[VB2_NVDATA_SIZE]; 123 124 /* 125 * Secure data. Caller must fill this from some secure non-volatile 126 * location. If the VB2_CONTEXT_SECDATA_CHANGED flag is set when a 127 * function returns, caller must save the data back to the secure 128 * non-volatile location and then clear the flag. 129 */ 130 uint8_t secdata[VB2_SECDATA_SIZE]; 131 132 /* 133 * Context pointer for use by caller. Verified boot never looks at 134 * this. Put context here if you need it for APIs that verified boot 135 * may call (vb2ex_...() functions). 136 */ 137 void *non_vboot_context; 138 139 /********************************************************************** 140 * Fields caller may examine after calling vb2api_fw_phase1(). Caller 141 * must set these fields to 0 before calling any vboot functions. 142 */ 143 144 /* 145 * Amount of work buffer used so far. Verified boot sub-calls use 146 * this to know where the unused work area starts. Caller may use 147 * this between calls to vboot APIs to know how much data must be 148 * copied when relocating the work buffer. 149 */ 150 uint32_t workbuf_used; 151 }; 152 153 enum vb2_resource_index { 154 155 /* Google binary block */ 156 VB2_RES_GBB, 157 158 /* 159 * Verified boot block (keyblock+preamble). Use VB2_CONTEXT_FW_SLOT_B 160 * to determine whether this refers to slot A or slot B; vboot will 161 * set that flag to the proper state before reading the vblock. 162 */ 163 VB2_RES_FW_VBLOCK, 164 }; 165 166 /* Digest ID for vbapi_get_pcr_digest() */ 167 enum vb2_pcr_digest { 168 /* Digest based on current developer and recovery mode flags */ 169 BOOT_MODE_PCR, 170 171 /* SHA-256 hash digest of HWID, from GBB */ 172 HWID_DIGEST_PCR, 173 }; 174 175 /****************************************************************************** 176 * APIs provided by verified boot. 177 * 178 * At a high level, call functions in the order described below. After each 179 * call, examine vb2_context.flags to determine whether nvdata or secdata 180 * needs to be written. 181 * 182 * If you need to cause the boot process to fail at any point, call 183 * vb2api_fail(). Then check vb2_context.flags to see what data needs to be 184 * written. Then reboot. 185 * 186 * Load nvdata from wherever you keep it. 187 * 188 * Load secdata from wherever you keep it. 189 * 190 * If it wasn't there at all (for example, this is the first boot 191 * of a new system in the factory), call vb2api_secdata_create() 192 * to initialize the data. 193 * 194 * If access to your storage is unreliable (reads/writes may 195 * contain corrupt data), you may call vb2api_secdata_check() to 196 * determine if the data was valid, and retry reading if it 197 * wasn't. (In that case, you should also read back and check the 198 * data after any time you write it, to make sure it was written 199 * correctly.) 200 * 201 * Call vb2api_fw_phase1(). At present, this nominally decides whether 202 * recovery mode is needed this boot. 203 * 204 * Call vb2api_fw_phase2(). At present, this nominally decides which 205 * firmware slot will be attempted (A or B). 206 * 207 * Call vb2api_fw_phase3(). At present, this nominally verifies the 208 * firmware keyblock and preamble. 209 * 210 * Lock down wherever you keep secdata. It should no longer be writable 211 * this boot. 212 * 213 * Verify the hash of each section of code/data you need to boot the RW 214 * firmware. For each section: 215 * 216 * Call vb2_init_hash() to see if the hash exists. 217 * 218 * Load the data for the section. Call vb2_extend_hash() on the 219 * data as you load it. You can load it all at once and make one 220 * call, or load and hash-extend a block at a time. 221 * 222 * Call vb2_check_hash() to see if the hash is valid. 223 * 224 * If it is valid, you may use the data and/or execute 225 * code from that section. 226 * 227 * If the hash was invalid, you must reboot. 228 * 229 * At this point, firmware verification is done, and vb2_context contains the 230 * kernel key needed to verify the kernel. That context should be preserved 231 * and passed on to kernel selection. For now, that requires translating it 232 * into the old VbSharedData format (via a func which does not yet exist...) 233 */ 234 235 /** 236 * Sanity-check the contents of the secure storage context. 237 * 238 * Use this if reading from secure storage may be flaky, and you want to retry 239 * reading it several times. 240 * 241 * This may be called before vb2api_phase1(). 242 * 243 * @param ctx Context pointer 244 * @return VB2_SUCCESS, or non-zero error code if error. 245 */ 246 int vb2api_secdata_check(const struct vb2_context *ctx); 247 248 /** 249 * Create fresh data in the secure storage context. 250 * 251 * Use this only when initializing the secure storage context on a new machine 252 * the first time it boots. Do NOT simply use this if vb2api_secdata_check() 253 * (or any other API in this library) fails; that could allow the secure data 254 * to be rolled back to an insecure state. 255 * 256 * This may be called before vb2api_phase1(). 257 * 258 * @param ctx Context pointer 259 * @return VB2_SUCCESS, or non-zero error code if error. 260 */ 261 int vb2api_secdata_create(struct vb2_context *ctx); 262 263 /** 264 * Report firmware failure to vboot. 265 * 266 * This may be called before vb2api_phase1() to indicate errors in the boot 267 * process prior to the start of vboot. 268 * 269 * If this is called after vb2api_phase1(), on return, the calling firmware 270 * should check for updates to secdata and/or nvdata, then reboot. 271 * 272 * @param reason Recovery reason 273 * @param subcode Recovery subcode 274 */ 275 void vb2api_fail(struct vb2_context *ctx, uint8_t reason, uint8_t subcode); 276 277 /** 278 * Firmware selection, phase 1. 279 * 280 * On error, the calling firmware should jump directly to recovery-mode 281 * firmware without rebooting. 282 * 283 * @param ctx Vboot context 284 * @return VB2_SUCCESS, or error code on error. 285 */ 286 int vb2api_fw_phase1(struct vb2_context *ctx); 287 288 /** 289 * Firmware selection, phase 2. 290 * 291 * On error, the calling firmware should check for updates to secdata and/or 292 * nvdata, then reboot. 293 * 294 * @param ctx Vboot context 295 * @return VB2_SUCCESS, or error code on error. 296 */ 297 int vb2api_fw_phase2(struct vb2_context *ctx); 298 299 /** 300 * Firmware selection, phase 3. 301 * 302 * On error, the calling firmware should check for updates to secdata and/or 303 * nvdata, then reboot. 304 * 305 * On success, the calling firmware should lock down secdata before continuing 306 * with the boot process. 307 * 308 * @param ctx Vboot context 309 * @return VB2_SUCCESS, or error code on error. 310 */ 311 int vb2api_fw_phase3(struct vb2_context *ctx); 312 313 /** 314 * Initialize hashing data for the specified tag. 315 * 316 * @param ctx Vboot context 317 * @param tag Tag to start hashing (enum vb2_hash_tag) 318 * @param size If non-null, expected size of data for tag will be 319 * stored here on output. 320 * @return VB2_SUCCESS, or error code on error. 321 */ 322 int vb2api_init_hash(struct vb2_context *ctx, uint32_t tag, uint32_t *size); 323 324 /** 325 * Same, but for new-style structs. 326 */ 327 int vb2api_init_hash2(struct vb2_context *ctx, 328 const struct vb2_guid *guid, 329 uint32_t *size); 330 331 /** 332 * Extend the hash started by vb2api_init_hash() with additional data. 333 * 334 * (This is the same for both old and new style structs.) 335 * 336 * @param ctx Vboot context 337 * @param buf Data to hash 338 * @param size Size of data in bytes 339 * @return VB2_SUCCESS, or error code on error. 340 */ 341 int vb2api_extend_hash(struct vb2_context *ctx, 342 const void *buf, 343 uint32_t size); 344 345 /** 346 * Check the hash value started by vb2api_init_hash(). 347 * 348 * @param ctx Vboot context 349 * @return VB2_SUCCESS, or error code on error. 350 */ 351 int vb2api_check_hash(struct vb2_context *ctx); 352 353 /** 354 * Get a PCR digest 355 * 356 * @param ctx Vboot context 357 * @param which_digest PCR index of the digest 358 * @param dest Destination where the digest is copied. 359 * Recommended size is VB2_PCR_DIGEST_RECOMMENDED_SIZE. 360 * @param dest_size IN: size of the buffer pointed by dest 361 * OUT: size of the copied digest 362 * @return VB2_SUCCESS, or error code on error 363 */ 364 int vb2api_get_pcr_digest(struct vb2_context *ctx, 365 enum vb2_pcr_digest which_digest, 366 uint8_t *dest, 367 uint32_t *dest_size); 368 369 /*****************************************************************************/ 370 /* APIs provided by the caller to verified boot */ 371 372 /** 373 * Clear the TPM owner. 374 * 375 * @param ctx Vboot context 376 * @return VB2_SUCCESS, or error code on error. 377 */ 378 int vb2ex_tpm_clear_owner(struct vb2_context *ctx); 379 380 /** 381 * Read a verified boot resource. 382 * 383 * @param ctx Vboot context 384 * @param index Resource index to read 385 * @param offset Byte offset within resource to start at 386 * @param buf Destination for data 387 * @param size Amount of data to read 388 * @return VB2_SUCCESS, or error code on error. 389 */ 390 int vb2ex_read_resource(struct vb2_context *ctx, 391 enum vb2_resource_index index, 392 uint32_t offset, 393 void *buf, 394 uint32_t size); 395 396 void vb2ex_printf(const char *func, const char *fmt, ...); 397 398 /** 399 * Initialize the hardware crypto engine to calculate a block-style digest. 400 * 401 * @param hash_alg Hash algorithm to use 402 * @param data_size Expected total size of data to hash 403 * @return VB2_SUCCESS, or non-zero error code (HWCRYPTO_UNSUPPORTED not fatal). 404 */ 405 int vb2ex_hwcrypto_digest_init(enum vb2_hash_algorithm hash_alg, 406 uint32_t data_size); 407 408 /** 409 * Extend the hash in the hardware crypto engine with another block of data. 410 * 411 * @param buf Next data block to hash 412 * @param size Length of data block in bytes 413 * @return VB2_SUCCESS, or non-zero error code. 414 */ 415 int vb2ex_hwcrypto_digest_extend(const uint8_t *buf, uint32_t size); 416 417 /** 418 * Finalize the digest in the hardware crypto engine and extract the result. 419 * 420 * @param digest Destination buffer for resulting digest 421 * @param digest_size Length of digest buffer in bytes 422 * @return VB2_SUCCESS, or non-zero error code. 423 */ 424 int vb2ex_hwcrypto_digest_finalize(uint8_t *digest, uint32_t digest_size); 425 426 #endif /* VBOOT_2_API_H_ */ 427