Randall Spangler | 3333e57 | 2014-05-14 11:37:52 -0700 | [diff] [blame] | 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. |
Joel Kitching | 9adf2aa | 2019-08-20 17:43:50 +0800 | [diff] [blame] | 4 | * |
| 5 | * APIs between calling firmware and vboot_reference |
Randall Spangler | 3333e57 | 2014-05-14 11:37:52 -0700 | [diff] [blame] | 6 | * |
| 7 | * General notes: |
| 8 | * |
| 9 | * TODO: split this file into a vboot_entry_points.h file which contains the |
| 10 | * entry points for the firmware to call vboot_reference, and a |
| 11 | * vboot_firmware_exports.h which contains the APIs to be implemented by the |
| 12 | * calling firmware and exported to vboot_reference. |
| 13 | * |
| 14 | * Notes: |
| 15 | * * Assumes this code is never called in the S3 resume path. TPM resume |
| 16 | * must be done elsewhere, and VB2_NV_DEBUG_RESET_MODE is ignored. |
| 17 | */ |
| 18 | |
Joel Kitching | 9adf2aa | 2019-08-20 17:43:50 +0800 | [diff] [blame] | 19 | #ifndef VBOOT_REFERENCE_2API_H_ |
| 20 | #define VBOOT_REFERENCE_2API_H_ |
Randall Spangler | 3333e57 | 2014-05-14 11:37:52 -0700 | [diff] [blame] | 21 | |
Joel Kitching | 6988559 | 2019-03-06 18:41:33 +0800 | [diff] [blame] | 22 | #include "2constants.h" |
Julius Werner | f10e909 | 2014-12-16 19:24:54 -0800 | [diff] [blame] | 23 | #include "2crypto.h" |
Randall Spangler | 435c74f | 2014-10-15 13:56:03 -0700 | [diff] [blame] | 24 | #include "2fw_hash_tags.h" |
Joel Kitching | dde7e4c | 2019-04-25 17:58:11 +0800 | [diff] [blame] | 25 | #include "2gbb_flags.h" |
Bill Richardson | 36bc591 | 2015-03-04 16:13:45 -0800 | [diff] [blame] | 26 | #include "2id.h" |
Randall Spangler | 3333e57 | 2014-05-14 11:37:52 -0700 | [diff] [blame] | 27 | #include "2recovery_reasons.h" |
| 28 | #include "2return_codes.h" |
Joel Kitching | 9adf2aa | 2019-08-20 17:43:50 +0800 | [diff] [blame] | 29 | #include "2secdata.h" |
Randall Spangler | 3333e57 | 2014-05-14 11:37:52 -0700 | [diff] [blame] | 30 | |
Joel Kitching | fbde3aa | 2019-08-27 17:13:55 +0800 | [diff] [blame^] | 31 | /* TODO(chromium:972956): Remove once coreboot is using updated names */ |
| 32 | #define secdata secdata_firmware |
| 33 | #define secdatak secdata_kernel |
| 34 | #define vb2api_secdata_check vb2api_secdata_firmware_check |
| 35 | #define vb2api_secdata_create vb2api_secdata_firmware_create |
| 36 | #define vb2api_secdatak_check vb2api_secdata_kernel_check |
| 37 | #define vb2api_secdatak_create vb2api_secdata_kernel_create |
| 38 | |
Matt Delco | 08bf680 | 2019-02-13 15:54:24 -0800 | [diff] [blame] | 39 | /* Modes for vb2ex_tpm_set_mode. */ |
| 40 | enum vb2_tpm_mode { |
| 41 | /* |
| 42 | * TPM is enabled tentatively, and may be set to either |
| 43 | * ENABLED or DISABLED mode. |
| 44 | */ |
| 45 | VB2_TPM_MODE_ENABLED_TENTATIVE = 0, |
| 46 | |
| 47 | /* TPM is enabled, and mode may not be changed. */ |
| 48 | VB2_TPM_MODE_ENABLED = 1, |
| 49 | |
| 50 | /* TPM is disabled, and mode may not be changed. */ |
| 51 | VB2_TPM_MODE_DISABLED = 2, |
| 52 | }; |
| 53 | |
Randall Spangler | 3333e57 | 2014-05-14 11:37:52 -0700 | [diff] [blame] | 54 | /* Flags for vb2_context. |
| 55 | * |
| 56 | * Unless otherwise noted, flags are set by verified boot and may be read (but |
| 57 | * not set or cleared) by the caller. |
| 58 | */ |
| 59 | enum vb2_context_flags { |
| 60 | |
| 61 | /* |
| 62 | * Verified boot has changed nvdata[]. Caller must save nvdata[] back |
| 63 | * to its underlying storage, then may clear this flag. |
| 64 | */ |
| 65 | VB2_CONTEXT_NVDATA_CHANGED = (1 << 0), |
| 66 | |
| 67 | /* |
Joel Kitching | fbde3aa | 2019-08-27 17:13:55 +0800 | [diff] [blame^] | 68 | * Verified boot has changed secdata_firmware[]. Caller must save |
| 69 | * secdata_firmware[] back to its underlying storage, then may clear |
| 70 | * this flag. |
Randall Spangler | 3333e57 | 2014-05-14 11:37:52 -0700 | [diff] [blame] | 71 | */ |
Joel Kitching | fbde3aa | 2019-08-27 17:13:55 +0800 | [diff] [blame^] | 72 | VB2_CONTEXT_SECDATA_FIRMWARE_CHANGED = (1 << 1), |
| 73 | /* TODO: Remove once coreboot has switched over */ |
Randall Spangler | 3333e57 | 2014-05-14 11:37:52 -0700 | [diff] [blame] | 74 | VB2_CONTEXT_SECDATA_CHANGED = (1 << 1), |
| 75 | |
| 76 | /* Recovery mode is requested this boot */ |
| 77 | VB2_CONTEXT_RECOVERY_MODE = (1 << 2), |
| 78 | |
| 79 | /* Developer mode is requested this boot */ |
| 80 | VB2_CONTEXT_DEVELOPER_MODE = (1 << 3), |
| 81 | |
| 82 | /* |
| 83 | * Force recovery mode due to physical user request. Caller may set |
| 84 | * this flag when initializing the context. |
| 85 | */ |
| 86 | VB2_CONTEXT_FORCE_RECOVERY_MODE = (1 << 4), |
| 87 | |
| 88 | /* |
| 89 | * Force developer mode enabled. Caller may set this flag when |
Joel Kitching | a8a24fe | 2019-03-18 17:59:26 +0800 | [diff] [blame] | 90 | * initializing the context. Previously used for forcing developer |
| 91 | * mode with physical dev switch. |
Joel Kitching | 3d8d93b | 2019-03-17 18:14:18 +0800 | [diff] [blame] | 92 | * |
| 93 | * Deprecated as part of chromium:942901. |
Randall Spangler | 3333e57 | 2014-05-14 11:37:52 -0700 | [diff] [blame] | 94 | */ |
Joel Kitching | a8a24fe | 2019-03-18 17:59:26 +0800 | [diff] [blame] | 95 | VB2_CONTEXT_DEPRECATED_FORCE_DEVELOPER_MODE = (1 << 5), |
Randall Spangler | 3333e57 | 2014-05-14 11:37:52 -0700 | [diff] [blame] | 96 | |
| 97 | /* Using firmware slot B. If this flag is clear, using slot A. */ |
| 98 | VB2_CONTEXT_FW_SLOT_B = (1 << 6), |
| 99 | |
| 100 | /* RAM should be cleared by caller this boot */ |
| 101 | VB2_CONTEXT_CLEAR_RAM = (1 << 7), |
Vadim Bendebury | 7b50512 | 2015-03-12 18:58:13 -0700 | [diff] [blame] | 102 | |
| 103 | /* Wipeout by the app should be requested. */ |
| 104 | VB2_CONTEXT_FORCE_WIPEOUT_MODE = (1 << 8), |
Vadim Bendebury | 3939252 | 2015-03-20 16:19:57 -0700 | [diff] [blame] | 105 | |
| 106 | /* Erase TPM developer mode state if it is enabled. */ |
Joel Kitching | 1e17774 | 2019-01-11 19:31:53 +0800 | [diff] [blame] | 107 | VB2_CONTEXT_DISABLE_DEVELOPER_MODE = (1 << 9), |
Randall Spangler | bf9c276 | 2015-05-12 13:44:30 -0700 | [diff] [blame] | 108 | |
| 109 | /* |
Joel Kitching | fbde3aa | 2019-08-27 17:13:55 +0800 | [diff] [blame^] | 110 | * Verified boot has changed secdata_kernel[]. Caller must save |
| 111 | * secdata_kernel[] back to its underlying storage, then may clear |
| 112 | * this flag. |
Randall Spangler | bf9c276 | 2015-05-12 13:44:30 -0700 | [diff] [blame] | 113 | */ |
Joel Kitching | fbde3aa | 2019-08-27 17:13:55 +0800 | [diff] [blame^] | 114 | VB2_CONTEXT_SECDATA_KERNEL_CHANGED = (1 << 10), |
Randall Spangler | d7f0f93 | 2015-05-19 13:41:09 -0700 | [diff] [blame] | 115 | |
| 116 | /* |
Joel Kitching | fbde3aa | 2019-08-27 17:13:55 +0800 | [diff] [blame^] | 117 | * Allow kernel verification to roll forward the version in |
| 118 | * secdata_kernel[]. Caller may set this flag before calling |
| 119 | * vb2api_kernel_phase3(). |
Randall Spangler | d7f0f93 | 2015-05-19 13:41:09 -0700 | [diff] [blame] | 120 | */ |
| 121 | VB2_CONTEXT_ALLOW_KERNEL_ROLL_FORWARD = (1 << 11), |
Patrick Georgi | ebf886b | 2015-02-10 14:58:28 +0100 | [diff] [blame] | 122 | |
Randall Spangler | 3942724 | 2018-01-02 12:32:16 -0800 | [diff] [blame] | 123 | /* |
| 124 | * Boot optimistically: don't touch failure counters. Caller may set |
| 125 | * this flag when initializing the context. |
| 126 | */ |
Patrick Georgi | ebf886b | 2015-02-10 14:58:28 +0100 | [diff] [blame] | 127 | VB2_CONTEXT_NOFAIL_BOOT = (1 << 12), |
Randall Spangler | c8e4854 | 2015-09-17 12:54:51 -0700 | [diff] [blame] | 128 | |
| 129 | /* |
| 130 | * Secdata is not ready this boot, but should be ready next boot. It |
| 131 | * would like to reboot. The decision whether to reboot or not must be |
| 132 | * deferred until vboot, because rebooting all the time before then |
| 133 | * could cause a device with malfunctioning secdata to get stuck in an |
| 134 | * unrecoverable crash loop. |
| 135 | */ |
| 136 | VB2_CONTEXT_SECDATA_WANTS_REBOOT = (1 << 13), |
Duncan Laurie | d187cd3 | 2016-02-19 20:20:10 -0800 | [diff] [blame] | 137 | |
Randall Spangler | 3942724 | 2018-01-02 12:32:16 -0800 | [diff] [blame] | 138 | /* |
| 139 | * Boot is S3->S0 resume, not S5->S0 normal boot. Caller may set this |
| 140 | * flag when initializing the context. |
| 141 | */ |
Duncan Laurie | d187cd3 | 2016-02-19 20:20:10 -0800 | [diff] [blame] | 142 | VB2_CONTEXT_S3_RESUME = (1 << 14), |
Randall Spangler | 3942724 | 2018-01-02 12:32:16 -0800 | [diff] [blame] | 143 | |
| 144 | /* |
| 145 | * System supports EC software sync. Caller may set this flag at any |
| 146 | * time before calling VbSelectAndLoadKernel(). |
| 147 | */ |
| 148 | VB2_CONTEXT_EC_SYNC_SUPPORTED = (1 << 15), |
| 149 | |
| 150 | /* |
| 151 | * EC software sync is slow to update; warning screen should be |
| 152 | * displayed. Caller may set this flag at any time before calling |
| 153 | * VbSelectAndLoadKernel(). |
| 154 | */ |
| 155 | VB2_CONTEXT_EC_SYNC_SLOW = (1 << 16), |
| 156 | |
| 157 | /* |
| 158 | * EC firmware supports early firmware selection; two EC images exist, |
| 159 | * and EC may have already verified and jumped to EC-RW prior to EC |
| 160 | * software sync. |
| 161 | */ |
| 162 | VB2_CONTEXT_EC_EFS = (1 << 17), |
Randall Spangler | a80a79f | 2018-02-26 17:01:24 -0800 | [diff] [blame] | 163 | |
| 164 | /* |
| 165 | * NV storage uses data format V2. Data is size VB2_NVDATA_SIZE_V2, |
| 166 | * not VB2_NVDATA_SIZE. |
| 167 | * |
| 168 | * Caller must set this flag when initializing the context to use V2. |
| 169 | * (Vboot cannot infer the data size from the data itself, because the |
| 170 | * data provided by the caller could be uninitialized.) |
| 171 | */ |
| 172 | VB2_CONTEXT_NVDATA_V2 = (1 << 18), |
Mathew King | 9d6dc0d | 2019-02-11 10:27:59 -0700 | [diff] [blame] | 173 | |
| 174 | /* Allow vendor data to be set via the vendor data ui. */ |
| 175 | VB2_CONTEXT_VENDOR_DATA_SETTABLE = (1 << 19), |
Joel Kitching | e7edff6 | 2019-04-12 11:45:32 +0800 | [diff] [blame] | 176 | |
| 177 | /* |
| 178 | * Caller may set this before running vb2api_fw_phase1. In this case, |
| 179 | * it means: "Display is available on this boot. Please advertise |
| 180 | * as such to downstream vboot code and users." |
| 181 | * |
| 182 | * vboot may also set this before returning from vb2api_fw_phase1. |
| 183 | * In this case, it means: "Please initialize display so that it is |
| 184 | * available to downstream vboot code and users." This is used when |
| 185 | * vboot encounters some internally-generated request for display |
| 186 | * support. |
| 187 | */ |
| 188 | VB2_CONTEXT_DISPLAY_INIT = (1 << 20), |
Randall Spangler | 3333e57 | 2014-05-14 11:37:52 -0700 | [diff] [blame] | 189 | }; |
| 190 | |
| 191 | /* |
| 192 | * Context for firmware verification. Pass this to all vboot APIs. |
| 193 | * |
| 194 | * Caller may relocate this between calls to vboot APIs. |
| 195 | */ |
| 196 | struct vb2_context { |
| 197 | /********************************************************************** |
| 198 | * Fields which must be initialized by caller. |
| 199 | */ |
| 200 | |
| 201 | /* |
| 202 | * Flags; see vb2_context_flags. Some flags may only be set by caller |
| 203 | * prior to calling vboot functions. |
| 204 | */ |
| 205 | uint32_t flags; |
| 206 | |
| 207 | /* |
| 208 | * Work buffer, and length in bytes. Caller may relocate this between |
| 209 | * calls to vboot APIs; it contains no internal pointers. Caller must |
| 210 | * not examine the contents of this work buffer directly. |
| 211 | */ |
| 212 | uint8_t *workbuf; |
| 213 | uint32_t workbuf_size; |
| 214 | |
| 215 | /* |
| 216 | * Non-volatile data. Caller must fill this from some non-volatile |
| 217 | * location. If the VB2_CONTEXT_NVDATA_CHANGED flag is set when a |
| 218 | * vb2api function returns, caller must save the data back to the |
| 219 | * non-volatile location and then clear the flag. |
| 220 | */ |
Randall Spangler | a80a79f | 2018-02-26 17:01:24 -0800 | [diff] [blame] | 221 | uint8_t nvdata[VB2_NVDATA_SIZE_V2]; |
Randall Spangler | 3333e57 | 2014-05-14 11:37:52 -0700 | [diff] [blame] | 222 | |
| 223 | /* |
Randall Spangler | bf9c276 | 2015-05-12 13:44:30 -0700 | [diff] [blame] | 224 | * Secure data for firmware verification stage. Caller must fill this |
| 225 | * from some secure non-volatile location. If the |
| 226 | * VB2_CONTEXT_SECDATA_CHANGED flag is set when a function returns, |
| 227 | * caller must save the data back to the secure non-volatile location |
| 228 | * and then clear the flag. |
Randall Spangler | 3333e57 | 2014-05-14 11:37:52 -0700 | [diff] [blame] | 229 | */ |
Joel Kitching | fbde3aa | 2019-08-27 17:13:55 +0800 | [diff] [blame^] | 230 | uint8_t secdata_firmware[VB2_SECDATA_FIRMWARE_SIZE]; |
Randall Spangler | 3333e57 | 2014-05-14 11:37:52 -0700 | [diff] [blame] | 231 | |
| 232 | /* |
| 233 | * Context pointer for use by caller. Verified boot never looks at |
| 234 | * this. Put context here if you need it for APIs that verified boot |
| 235 | * may call (vb2ex_...() functions). |
| 236 | */ |
| 237 | void *non_vboot_context; |
| 238 | |
| 239 | /********************************************************************** |
| 240 | * Fields caller may examine after calling vb2api_fw_phase1(). Caller |
Joel Kitching | 9ad8a41 | 2018-08-02 16:21:17 +0800 | [diff] [blame] | 241 | * must set these fields to 0 before calling any vboot functions. |
Randall Spangler | 3333e57 | 2014-05-14 11:37:52 -0700 | [diff] [blame] | 242 | */ |
| 243 | |
| 244 | /* |
| 245 | * Amount of work buffer used so far. Verified boot sub-calls use |
| 246 | * this to know where the unused work area starts. Caller may use |
| 247 | * this between calls to vboot APIs to know how much data must be |
| 248 | * copied when relocating the work buffer. |
| 249 | */ |
| 250 | uint32_t workbuf_used; |
Randall Spangler | bf9c276 | 2015-05-12 13:44:30 -0700 | [diff] [blame] | 251 | |
| 252 | /********************************************************************** |
| 253 | * Fields caller must initialize before calling vb2api_kernel_phase1(). |
| 254 | */ |
| 255 | |
| 256 | /* |
| 257 | * Secure data for kernel verification stage. Caller must fill this |
| 258 | * from some secure non-volatile location. If the |
Joel Kitching | fbde3aa | 2019-08-27 17:13:55 +0800 | [diff] [blame^] | 259 | * VB2_CONTEXT_SECDATA_KERNEL_CHANGED flag is set when a function |
| 260 | * returns, caller must save the data back to the secure non-volatile |
| 261 | * location and then clear the flag. |
Randall Spangler | bf9c276 | 2015-05-12 13:44:30 -0700 | [diff] [blame] | 262 | */ |
Joel Kitching | fbde3aa | 2019-08-27 17:13:55 +0800 | [diff] [blame^] | 263 | uint8_t secdata_kernel[VB2_SECDATA_KERNEL_SIZE]; |
Randall Spangler | 3333e57 | 2014-05-14 11:37:52 -0700 | [diff] [blame] | 264 | }; |
| 265 | |
Randall Spangler | 3d5cd88 | 2015-05-20 17:22:17 -0700 | [diff] [blame] | 266 | /* Resource index for vb2ex_read_resource() */ |
Randall Spangler | da2b49c | 2014-06-10 17:03:40 -0700 | [diff] [blame] | 267 | enum vb2_resource_index { |
| 268 | |
| 269 | /* Google binary block */ |
| 270 | VB2_RES_GBB, |
| 271 | |
| 272 | /* |
Randall Spangler | 3d5cd88 | 2015-05-20 17:22:17 -0700 | [diff] [blame] | 273 | * Firmware verified boot block (keyblock+preamble). Use |
| 274 | * VB2_CONTEXT_FW_SLOT_B to determine whether this refers to slot A or |
| 275 | * slot B; vboot will set that flag to the proper state before reading |
| 276 | * the vblock. |
Randall Spangler | da2b49c | 2014-06-10 17:03:40 -0700 | [diff] [blame] | 277 | */ |
| 278 | VB2_RES_FW_VBLOCK, |
Randall Spangler | 3d5cd88 | 2015-05-20 17:22:17 -0700 | [diff] [blame] | 279 | |
| 280 | /* |
| 281 | * Kernel verified boot block (keyblock+preamble) for the current |
| 282 | * kernel partition. Used only by vb2api_kernel_load_vblock(). |
| 283 | * Contents are allowed to change between calls to that function (to |
| 284 | * allow multiple kernels to be examined). |
| 285 | */ |
| 286 | VB2_RES_KERNEL_VBLOCK, |
Randall Spangler | da2b49c | 2014-06-10 17:03:40 -0700 | [diff] [blame] | 287 | }; |
| 288 | |
Daisuke Nojiri | 62d482e | 2015-01-29 14:37:25 -0800 | [diff] [blame] | 289 | /* Digest ID for vbapi_get_pcr_digest() */ |
| 290 | enum vb2_pcr_digest { |
| 291 | /* Digest based on current developer and recovery mode flags */ |
| 292 | BOOT_MODE_PCR, |
| 293 | |
| 294 | /* SHA-256 hash digest of HWID, from GBB */ |
| 295 | HWID_DIGEST_PCR, |
| 296 | }; |
| 297 | |
Randall Spangler | a7ab8b5 | 2014-06-10 17:05:08 -0700 | [diff] [blame] | 298 | /****************************************************************************** |
| 299 | * APIs provided by verified boot. |
| 300 | * |
| 301 | * At a high level, call functions in the order described below. After each |
| 302 | * call, examine vb2_context.flags to determine whether nvdata or secdata |
| 303 | * needs to be written. |
| 304 | * |
| 305 | * If you need to cause the boot process to fail at any point, call |
| 306 | * vb2api_fail(). Then check vb2_context.flags to see what data needs to be |
| 307 | * written. Then reboot. |
| 308 | * |
| 309 | * Load nvdata from wherever you keep it. |
| 310 | * |
Joel Kitching | fbde3aa | 2019-08-27 17:13:55 +0800 | [diff] [blame^] | 311 | * Load secdata_firmware from wherever you keep it. |
Randall Spangler | a7ab8b5 | 2014-06-10 17:05:08 -0700 | [diff] [blame] | 312 | * |
| 313 | * If it wasn't there at all (for example, this is the first boot |
Joel Kitching | fbde3aa | 2019-08-27 17:13:55 +0800 | [diff] [blame^] | 314 | * of a new system in the factory), call |
| 315 | * vb2api_secdata_firmware_create() to initialize the data. |
Randall Spangler | a7ab8b5 | 2014-06-10 17:05:08 -0700 | [diff] [blame] | 316 | * |
| 317 | * If access to your storage is unreliable (reads/writes may |
Joel Kitching | fbde3aa | 2019-08-27 17:13:55 +0800 | [diff] [blame^] | 318 | * contain corrupt data), you may call |
| 319 | * vb2api_secdata_firmware_check() to determine if the data was |
| 320 | * valid, and retry reading if it wasn't. (In that case, you |
| 321 | * should also read back and check the data after any time you |
| 322 | * write it, to make sure it was written correctly.) |
Randall Spangler | a7ab8b5 | 2014-06-10 17:05:08 -0700 | [diff] [blame] | 323 | * |
| 324 | * Call vb2api_fw_phase1(). At present, this nominally decides whether |
| 325 | * recovery mode is needed this boot. |
| 326 | * |
| 327 | * Call vb2api_fw_phase2(). At present, this nominally decides which |
| 328 | * firmware slot will be attempted (A or B). |
| 329 | * |
| 330 | * Call vb2api_fw_phase3(). At present, this nominally verifies the |
| 331 | * firmware keyblock and preamble. |
| 332 | * |
Joel Kitching | fbde3aa | 2019-08-27 17:13:55 +0800 | [diff] [blame^] | 333 | * Lock down wherever you keep secdata_firmware. It should no longer be |
| 334 | * writable this boot. |
Randall Spangler | a7ab8b5 | 2014-06-10 17:05:08 -0700 | [diff] [blame] | 335 | * |
| 336 | * Verify the hash of each section of code/data you need to boot the RW |
| 337 | * firmware. For each section: |
| 338 | * |
| 339 | * Call vb2_init_hash() to see if the hash exists. |
| 340 | * |
| 341 | * Load the data for the section. Call vb2_extend_hash() on the |
| 342 | * data as you load it. You can load it all at once and make one |
| 343 | * call, or load and hash-extend a block at a time. |
| 344 | * |
| 345 | * Call vb2_check_hash() to see if the hash is valid. |
| 346 | * |
| 347 | * If it is valid, you may use the data and/or execute |
| 348 | * code from that section. |
| 349 | * |
| 350 | * If the hash was invalid, you must reboot. |
| 351 | * |
| 352 | * At this point, firmware verification is done, and vb2_context contains the |
| 353 | * kernel key needed to verify the kernel. That context should be preserved |
Randall Spangler | d7f0f93 | 2015-05-19 13:41:09 -0700 | [diff] [blame] | 354 | * and passed on to kernel selection. The kernel selection process may be |
| 355 | * done by the same firmware image, or may be done by the RW firmware. The |
| 356 | * recommended order is: |
| 357 | * |
Joel Kitching | fbde3aa | 2019-08-27 17:13:55 +0800 | [diff] [blame^] | 358 | * Load secdata_kernel from wherever you keep it. |
Randall Spangler | d7f0f93 | 2015-05-19 13:41:09 -0700 | [diff] [blame] | 359 | * |
| 360 | * If it wasn't there at all (for example, this is the first boot |
Joel Kitching | fbde3aa | 2019-08-27 17:13:55 +0800 | [diff] [blame^] | 361 | * of a new system in the factory), call |
| 362 | * vb2api_secdata_kernel_create() to initialize the data. |
Randall Spangler | d7f0f93 | 2015-05-19 13:41:09 -0700 | [diff] [blame] | 363 | * |
| 364 | * If access to your storage is unreliable (reads/writes may |
Joel Kitching | fbde3aa | 2019-08-27 17:13:55 +0800 | [diff] [blame^] | 365 | * contain corrupt data), you may call |
| 366 | * vb2api_secdata_kernel_check() to determine if the data was |
| 367 | * valid, and retry reading if it wasn't. (In that case, you |
| 368 | * should also read back and check the data after any time you |
| 369 | * write it, to make sure it was written correctly.) |
Randall Spangler | d7f0f93 | 2015-05-19 13:41:09 -0700 | [diff] [blame] | 370 | * |
| 371 | * Call vb2api_kernel_phase1(). At present, this decides which key to |
| 372 | * use to verify kernel data - the recovery key from the GBB, or the |
| 373 | * kernel subkey from the firmware verification stage. |
| 374 | * |
| 375 | * Kernel phase 2 is finding loading, and verifying the kernel partition. |
| 376 | * |
| 377 | * Find a boot device (you're on your own here). |
| 378 | * |
| 379 | * Call vb2api_load_kernel_vblock() for each kernel partition on the |
| 380 | * boot device, until one succeeds. |
| 381 | * |
| 382 | * When that succeeds, call vb2api_get_kernel_size() to determine where |
| 383 | * the kernel is located in the stream and how big it is. Load or map |
| 384 | * the kernel. (Again, you're on your own. This is the responsibility of |
| 385 | * the caller so that the caller can choose whether to allocate a buffer, |
| 386 | * load the kernel data into a predefined area of RAM, or directly map a |
| 387 | * kernel file into the address space. Note that technically it doesn't |
| 388 | * matter whether the kernel data is even in the same file or stream as |
| 389 | * the vblock, as long as the caller loads the right data. |
| 390 | * |
| 391 | * Call vb2api_verify_kernel_data() on the kernel data. |
| 392 | * |
| 393 | * If you ran out of kernels before finding a good one, call vb2api_fail() |
| 394 | * with an appropriate recovery reason. |
| 395 | * |
| 396 | * Set the VB2_CONTEXT_ALLOW_KERNEL_ROLL_FORWARD flag if the current |
| 397 | * kernel partition has the successful flag (that is, it's already known |
| 398 | * or assumed to be a functional kernel partition). |
| 399 | * |
| 400 | * Call vb2api_kernel_phase3(). This cleans up from kernel verification |
| 401 | * and updates the secure data if needed. |
| 402 | * |
Joel Kitching | fbde3aa | 2019-08-27 17:13:55 +0800 | [diff] [blame^] | 403 | * Lock down wherever you keep secdata_kernel. It should no longer be |
| 404 | * writable this boot. |
Randall Spangler | a7ab8b5 | 2014-06-10 17:05:08 -0700 | [diff] [blame] | 405 | */ |
| 406 | |
| 407 | /** |
Joel Kitching | fbde3aa | 2019-08-27 17:13:55 +0800 | [diff] [blame^] | 408 | * Check the validity of the firmware secure storage context. |
Randall Spangler | a7ab8b5 | 2014-06-10 17:05:08 -0700 | [diff] [blame] | 409 | * |
Joel Kitching | 0ff8764 | 2019-08-20 15:00:40 +0800 | [diff] [blame] | 410 | * Checks version and CRC. |
Randall Spangler | a7ab8b5 | 2014-06-10 17:05:08 -0700 | [diff] [blame] | 411 | * |
| 412 | * @param ctx Context pointer |
| 413 | * @return VB2_SUCCESS, or non-zero error code if error. |
| 414 | */ |
Joel Kitching | fbde3aa | 2019-08-27 17:13:55 +0800 | [diff] [blame^] | 415 | vb2_error_t vb2api_secdata_firmware_check(struct vb2_context *ctx); |
Randall Spangler | a7ab8b5 | 2014-06-10 17:05:08 -0700 | [diff] [blame] | 416 | |
| 417 | /** |
Joel Kitching | fbde3aa | 2019-08-27 17:13:55 +0800 | [diff] [blame^] | 418 | * Create fresh data in the firmware secure storage context. |
Randall Spangler | a7ab8b5 | 2014-06-10 17:05:08 -0700 | [diff] [blame] | 419 | * |
| 420 | * Use this only when initializing the secure storage context on a new machine |
Joel Kitching | fbde3aa | 2019-08-27 17:13:55 +0800 | [diff] [blame^] | 421 | * the first time it boots. Do NOT simply use this if |
| 422 | * vb2api_secdata_firmware_check() (or any other API in this library) fails; |
| 423 | * that could allow the secure data to be rolled back to an insecure state. |
Randall Spangler | a7ab8b5 | 2014-06-10 17:05:08 -0700 | [diff] [blame] | 424 | * |
Randall Spangler | a7ab8b5 | 2014-06-10 17:05:08 -0700 | [diff] [blame] | 425 | * @param ctx Context pointer |
| 426 | * @return VB2_SUCCESS, or non-zero error code if error. |
| 427 | */ |
Joel Kitching | fbde3aa | 2019-08-27 17:13:55 +0800 | [diff] [blame^] | 428 | vb2_error_t vb2api_secdata_firmware_create(struct vb2_context *ctx); |
Randall Spangler | a7ab8b5 | 2014-06-10 17:05:08 -0700 | [diff] [blame] | 429 | |
| 430 | /** |
Joel Kitching | fbde3aa | 2019-08-27 17:13:55 +0800 | [diff] [blame^] | 431 | * Check the validity of the kernel secure storage context. |
Randall Spangler | bf9c276 | 2015-05-12 13:44:30 -0700 | [diff] [blame] | 432 | * |
Joel Kitching | 0ff8764 | 2019-08-20 15:00:40 +0800 | [diff] [blame] | 433 | * Checks version, UID, and CRC. |
Randall Spangler | bf9c276 | 2015-05-12 13:44:30 -0700 | [diff] [blame] | 434 | * |
| 435 | * @param ctx Context pointer |
| 436 | * @return VB2_SUCCESS, or non-zero error code if error. |
| 437 | */ |
Joel Kitching | fbde3aa | 2019-08-27 17:13:55 +0800 | [diff] [blame^] | 438 | vb2_error_t vb2api_secdata_kernel_check(struct vb2_context *ctx); |
Randall Spangler | bf9c276 | 2015-05-12 13:44:30 -0700 | [diff] [blame] | 439 | |
| 440 | /** |
Joel Kitching | fbde3aa | 2019-08-27 17:13:55 +0800 | [diff] [blame^] | 441 | * Create fresh data in the kernel secure storage context. |
Randall Spangler | bf9c276 | 2015-05-12 13:44:30 -0700 | [diff] [blame] | 442 | * |
| 443 | * Use this only when initializing the secure storage context on a new machine |
Joel Kitching | fbde3aa | 2019-08-27 17:13:55 +0800 | [diff] [blame^] | 444 | * the first time it boots. Do NOT simply use this if |
| 445 | * vb2api_secdata_kernel_check() (or any other API in this library) fails; that |
| 446 | * could allow the secure data to be rolled back to an insecure state. |
Randall Spangler | bf9c276 | 2015-05-12 13:44:30 -0700 | [diff] [blame] | 447 | * |
Randall Spangler | bf9c276 | 2015-05-12 13:44:30 -0700 | [diff] [blame] | 448 | * @param ctx Context pointer |
| 449 | * @return VB2_SUCCESS, or non-zero error code if error. |
| 450 | */ |
Joel Kitching | fbde3aa | 2019-08-27 17:13:55 +0800 | [diff] [blame^] | 451 | vb2_error_t vb2api_secdata_kernel_create(struct vb2_context *ctx); |
Randall Spangler | bf9c276 | 2015-05-12 13:44:30 -0700 | [diff] [blame] | 452 | |
| 453 | /** |
Randall Spangler | a7ab8b5 | 2014-06-10 17:05:08 -0700 | [diff] [blame] | 454 | * Report firmware failure to vboot. |
| 455 | * |
| 456 | * This may be called before vb2api_phase1() to indicate errors in the boot |
| 457 | * process prior to the start of vboot. |
| 458 | * |
| 459 | * If this is called after vb2api_phase1(), on return, the calling firmware |
| 460 | * should check for updates to secdata and/or nvdata, then reboot. |
| 461 | * |
| 462 | * @param reason Recovery reason |
| 463 | * @param subcode Recovery subcode |
| 464 | */ |
| 465 | void vb2api_fail(struct vb2_context *ctx, uint8_t reason, uint8_t subcode); |
| 466 | |
| 467 | /** |
| 468 | * Firmware selection, phase 1. |
| 469 | * |
Randall Spangler | c8e4854 | 2015-09-17 12:54:51 -0700 | [diff] [blame] | 470 | * If the returned error is VB2_ERROR_API_PHASE1_RECOVERY, the calling firmware |
| 471 | * should jump directly to recovery-mode firmware without rebooting. |
| 472 | * |
| 473 | * For other errors, the calling firmware should check for updates to secdata |
| 474 | * and/or nvdata, then reboot. |
Randall Spangler | a7ab8b5 | 2014-06-10 17:05:08 -0700 | [diff] [blame] | 475 | * |
| 476 | * @param ctx Vboot context |
| 477 | * @return VB2_SUCCESS, or error code on error. |
| 478 | */ |
Joel Kitching | e6700f4 | 2019-07-31 14:12:30 +0800 | [diff] [blame] | 479 | vb2_error_t vb2api_fw_phase1(struct vb2_context *ctx); |
Randall Spangler | a7ab8b5 | 2014-06-10 17:05:08 -0700 | [diff] [blame] | 480 | |
| 481 | /** |
| 482 | * Firmware selection, phase 2. |
| 483 | * |
| 484 | * On error, the calling firmware should check for updates to secdata and/or |
| 485 | * nvdata, then reboot. |
| 486 | * |
| 487 | * @param ctx Vboot context |
| 488 | * @return VB2_SUCCESS, or error code on error. |
| 489 | */ |
Joel Kitching | e6700f4 | 2019-07-31 14:12:30 +0800 | [diff] [blame] | 490 | vb2_error_t vb2api_fw_phase2(struct vb2_context *ctx); |
Randall Spangler | a7ab8b5 | 2014-06-10 17:05:08 -0700 | [diff] [blame] | 491 | |
| 492 | /** |
| 493 | * Firmware selection, phase 3. |
| 494 | * |
| 495 | * On error, the calling firmware should check for updates to secdata and/or |
| 496 | * nvdata, then reboot. |
| 497 | * |
| 498 | * On success, the calling firmware should lock down secdata before continuing |
| 499 | * with the boot process. |
| 500 | * |
| 501 | * @param ctx Vboot context |
| 502 | * @return VB2_SUCCESS, or error code on error. |
| 503 | */ |
Joel Kitching | e6700f4 | 2019-07-31 14:12:30 +0800 | [diff] [blame] | 504 | vb2_error_t vb2api_fw_phase3(struct vb2_context *ctx); |
Randall Spangler | a7ab8b5 | 2014-06-10 17:05:08 -0700 | [diff] [blame] | 505 | |
Randall Spangler | a7ab8b5 | 2014-06-10 17:05:08 -0700 | [diff] [blame] | 506 | /** |
Randall Spangler | 98263a1 | 2016-06-02 16:05:49 -0700 | [diff] [blame] | 507 | * Same, but for new-style structs. |
| 508 | */ |
Joel Kitching | e6700f4 | 2019-07-31 14:12:30 +0800 | [diff] [blame] | 509 | vb2_error_t vb21api_fw_phase3(struct vb2_context *ctx); |
Randall Spangler | 98263a1 | 2016-06-02 16:05:49 -0700 | [diff] [blame] | 510 | |
| 511 | /** |
Randall Spangler | a7ab8b5 | 2014-06-10 17:05:08 -0700 | [diff] [blame] | 512 | * Initialize hashing data for the specified tag. |
| 513 | * |
| 514 | * @param ctx Vboot context |
Randall Spangler | 435c74f | 2014-10-15 13:56:03 -0700 | [diff] [blame] | 515 | * @param tag Tag to start hashing (enum vb2_hash_tag) |
Randall Spangler | a7ab8b5 | 2014-06-10 17:05:08 -0700 | [diff] [blame] | 516 | * @param size If non-null, expected size of data for tag will be |
| 517 | * stored here on output. |
| 518 | * @return VB2_SUCCESS, or error code on error. |
| 519 | */ |
Joel Kitching | e6700f4 | 2019-07-31 14:12:30 +0800 | [diff] [blame] | 520 | vb2_error_t vb2api_init_hash(struct vb2_context *ctx, uint32_t tag, |
| 521 | uint32_t *size); |
Randall Spangler | a7ab8b5 | 2014-06-10 17:05:08 -0700 | [diff] [blame] | 522 | |
| 523 | /** |
Randall Spangler | efa37b8 | 2014-11-12 16:20:50 -0800 | [diff] [blame] | 524 | * Same, but for new-style structs. |
| 525 | */ |
Joel Kitching | e6700f4 | 2019-07-31 14:12:30 +0800 | [diff] [blame] | 526 | vb2_error_t vb21api_init_hash(struct vb2_context *ctx, const struct vb2_id *id, |
| 527 | uint32_t *size); |
Randall Spangler | efa37b8 | 2014-11-12 16:20:50 -0800 | [diff] [blame] | 528 | |
| 529 | /** |
Randall Spangler | a7ab8b5 | 2014-06-10 17:05:08 -0700 | [diff] [blame] | 530 | * Extend the hash started by vb2api_init_hash() with additional data. |
| 531 | * |
Randall Spangler | efa37b8 | 2014-11-12 16:20:50 -0800 | [diff] [blame] | 532 | * (This is the same for both old and new style structs.) |
| 533 | * |
Randall Spangler | a7ab8b5 | 2014-06-10 17:05:08 -0700 | [diff] [blame] | 534 | * @param ctx Vboot context |
| 535 | * @param buf Data to hash |
| 536 | * @param size Size of data in bytes |
| 537 | * @return VB2_SUCCESS, or error code on error. |
| 538 | */ |
Joel Kitching | e6700f4 | 2019-07-31 14:12:30 +0800 | [diff] [blame] | 539 | vb2_error_t vb2api_extend_hash(struct vb2_context *ctx, const void *buf, |
| 540 | uint32_t size); |
Randall Spangler | a7ab8b5 | 2014-06-10 17:05:08 -0700 | [diff] [blame] | 541 | |
| 542 | /** |
| 543 | * Check the hash value started by vb2api_init_hash(). |
| 544 | * |
| 545 | * @param ctx Vboot context |
| 546 | * @return VB2_SUCCESS, or error code on error. |
| 547 | */ |
| 548 | int vb2api_check_hash(struct vb2_context *ctx); |
| 549 | |
Daisuke Nojiri | 62d482e | 2015-01-29 14:37:25 -0800 | [diff] [blame] | 550 | /** |
Randall Spangler | 98263a1 | 2016-06-02 16:05:49 -0700 | [diff] [blame] | 551 | * Same, but for new-style structs. |
| 552 | */ |
Joel Kitching | e6700f4 | 2019-07-31 14:12:30 +0800 | [diff] [blame] | 553 | vb2_error_t vb21api_check_hash(struct vb2_context *ctx); |
Randall Spangler | 98263a1 | 2016-06-02 16:05:49 -0700 | [diff] [blame] | 554 | |
| 555 | /** |
Aaron Durbin | 7cbd1ce | 2016-01-22 15:06:05 -0600 | [diff] [blame] | 556 | * Check the hash value started by vb2api_init_hash() while retrieving |
| 557 | * calculated digest. |
| 558 | * |
| 559 | * @param ctx Vboot context |
| 560 | * @param digest_out optional pointer to buffer to store digest |
| 561 | * @param digest_out_size optional size of buffer to store digest |
| 562 | * @return VB2_SUCCESS, or error code on error. |
| 563 | */ |
Joel Kitching | e6700f4 | 2019-07-31 14:12:30 +0800 | [diff] [blame] | 564 | vb2_error_t vb2api_check_hash_get_digest(struct vb2_context *ctx, |
| 565 | void *digest_out, |
| 566 | uint32_t digest_out_size); |
Aaron Durbin | 7cbd1ce | 2016-01-22 15:06:05 -0600 | [diff] [blame] | 567 | |
| 568 | /** |
Daisuke Nojiri | 62d482e | 2015-01-29 14:37:25 -0800 | [diff] [blame] | 569 | * Get a PCR digest |
| 570 | * |
| 571 | * @param ctx Vboot context |
| 572 | * @param which_digest PCR index of the digest |
| 573 | * @param dest Destination where the digest is copied. |
| 574 | * Recommended size is VB2_PCR_DIGEST_RECOMMENDED_SIZE. |
| 575 | * @param dest_size IN: size of the buffer pointed by dest |
| 576 | * OUT: size of the copied digest |
| 577 | * @return VB2_SUCCESS, or error code on error |
| 578 | */ |
Joel Kitching | e6700f4 | 2019-07-31 14:12:30 +0800 | [diff] [blame] | 579 | vb2_error_t vb2api_get_pcr_digest(struct vb2_context *ctx, |
| 580 | enum vb2_pcr_digest which_digest, |
| 581 | uint8_t *dest, uint32_t *dest_size); |
Daisuke Nojiri | 62d482e | 2015-01-29 14:37:25 -0800 | [diff] [blame] | 582 | |
Randall Spangler | d7f0f93 | 2015-05-19 13:41:09 -0700 | [diff] [blame] | 583 | /** |
| 584 | * Prepare for kernel verification stage. |
| 585 | * |
| 586 | * Must be called before other vb2api kernel functions. |
| 587 | * |
| 588 | * @param ctx Vboot context |
| 589 | * @return VB2_SUCCESS, or error code on error. |
| 590 | */ |
Joel Kitching | e6700f4 | 2019-07-31 14:12:30 +0800 | [diff] [blame] | 591 | vb2_error_t vb2api_kernel_phase1(struct vb2_context *ctx); |
Randall Spangler | d7f0f93 | 2015-05-19 13:41:09 -0700 | [diff] [blame] | 592 | |
| 593 | /** |
| 594 | * Load the verified boot block (vblock) for a kernel. |
| 595 | * |
| 596 | * This function may be called multiple times, to load and verify the |
| 597 | * vblocks from multiple kernel partitions. |
| 598 | * |
| 599 | * @param ctx Vboot context |
| 600 | * @param stream Kernel stream |
| 601 | * @return VB2_SUCCESS, or error code on error. |
| 602 | */ |
Joel Kitching | e6700f4 | 2019-07-31 14:12:30 +0800 | [diff] [blame] | 603 | vb2_error_t vb2api_load_kernel_vblock(struct vb2_context *ctx); |
Randall Spangler | d7f0f93 | 2015-05-19 13:41:09 -0700 | [diff] [blame] | 604 | |
| 605 | /** |
| 606 | * Get the size and offset of the kernel data for the most recent vblock. |
| 607 | * |
| 608 | * Valid after a successful call to vb2api_load_kernel_vblock(). |
| 609 | * |
| 610 | * @param ctx Vboot context |
| 611 | * @param offset_ptr Destination for offset in bytes of kernel data as |
| 612 | * reported by vblock. |
| 613 | * @param size_ptr Destination for size of kernel data in bytes. |
| 614 | * @return VB2_SUCCESS, or error code on error. |
| 615 | */ |
Joel Kitching | e6700f4 | 2019-07-31 14:12:30 +0800 | [diff] [blame] | 616 | vb2_error_t vb2api_get_kernel_size(struct vb2_context *ctx, |
| 617 | uint32_t *offset_ptr, uint32_t *size_ptr); |
Randall Spangler | d7f0f93 | 2015-05-19 13:41:09 -0700 | [diff] [blame] | 618 | |
| 619 | /** |
| 620 | * Verify kernel data using the previously loaded kernel vblock. |
| 621 | * |
| 622 | * Valid after a successful call to vb2api_load_kernel_vblock(). This allows |
| 623 | * the caller to load or map the kernel data, as appropriate, and pass the |
| 624 | * pointer to the kernel data into vboot. |
| 625 | * |
| 626 | * @param ctx Vboot context |
| 627 | * @param buf Pointer to kernel data |
| 628 | * @param size Size of kernel data in bytes |
| 629 | * @return VB2_SUCCESS, or error code on error. |
| 630 | */ |
Joel Kitching | e6700f4 | 2019-07-31 14:12:30 +0800 | [diff] [blame] | 631 | vb2_error_t vb2api_verify_kernel_data(struct vb2_context *ctx, const void *buf, |
| 632 | uint32_t size); |
Randall Spangler | d7f0f93 | 2015-05-19 13:41:09 -0700 | [diff] [blame] | 633 | |
| 634 | /** |
| 635 | * Clean up after kernel verification. |
| 636 | * |
| 637 | * Call this after successfully loading a vblock and verifying kernel data, |
| 638 | * or if you've run out of boot devices and/or kernel partitions. |
| 639 | * |
| 640 | * This cleans up intermediate data structures in the vboot context, and |
| 641 | * updates the version in the secure data if necessary. |
| 642 | */ |
Joel Kitching | e6700f4 | 2019-07-31 14:12:30 +0800 | [diff] [blame] | 643 | vb2_error_t vb2api_kernel_phase3(struct vb2_context *ctx); |
Randall Spangler | d7f0f93 | 2015-05-19 13:41:09 -0700 | [diff] [blame] | 644 | |
Joel Kitching | 3eb00ef | 2019-05-23 15:33:54 +0800 | [diff] [blame] | 645 | /** |
| 646 | * Read the hardware ID from the GBB, and store it onto the given buffer. |
| 647 | * |
| 648 | * @param ctx Vboot context. |
| 649 | * @param hwid Buffer to store HWID, which will be null-terminated. |
| 650 | * @param size Maximum size of HWID including null terminator. HWID |
| 651 | * length may not exceed 256 (VB2_GBB_HWID_MAX_SIZE), so |
| 652 | * this value is suggested. If size is too small, then |
| 653 | * VB2_ERROR_INVALID_PARAMETER is returned. Actual size |
| 654 | * of the output HWID string is returned in this pointer, |
| 655 | * also including null terminator. |
| 656 | * @return VB2_SUCCESS, or error code on error. |
| 657 | */ |
Joel Kitching | e6700f4 | 2019-07-31 14:12:30 +0800 | [diff] [blame] | 658 | vb2_error_t vb2api_gbb_read_hwid(struct vb2_context *ctx, char *hwid, |
| 659 | uint32_t *size); |
Joel Kitching | 3eb00ef | 2019-05-23 15:33:54 +0800 | [diff] [blame] | 660 | |
Joel Kitching | 01b1a94 | 2019-06-14 14:00:10 +0800 | [diff] [blame] | 661 | /** |
| 662 | * Retrieve current GBB flags. |
| 663 | * |
| 664 | * See enum vb2_gbb_flag in 2gbb_flags.h for a list of all GBB flags. |
| 665 | * |
| 666 | * @param ctx Vboot context. |
| 667 | * |
| 668 | * @return vb2_gbb_flags_t representing current GBB flags. |
| 669 | */ |
| 670 | vb2_gbb_flags_t vb2api_gbb_get_flags(struct vb2_context *ctx); |
| 671 | |
Randall Spangler | da2b49c | 2014-06-10 17:03:40 -0700 | [diff] [blame] | 672 | /*****************************************************************************/ |
| 673 | /* APIs provided by the caller to verified boot */ |
| 674 | |
| 675 | /** |
| 676 | * Clear the TPM owner. |
| 677 | * |
| 678 | * @param ctx Vboot context |
| 679 | * @return VB2_SUCCESS, or error code on error. |
| 680 | */ |
Joel Kitching | e6700f4 | 2019-07-31 14:12:30 +0800 | [diff] [blame] | 681 | vb2_error_t vb2ex_tpm_clear_owner(struct vb2_context *ctx); |
Randall Spangler | da2b49c | 2014-06-10 17:03:40 -0700 | [diff] [blame] | 682 | |
| 683 | /** |
| 684 | * Read a verified boot resource. |
| 685 | * |
| 686 | * @param ctx Vboot context |
| 687 | * @param index Resource index to read |
| 688 | * @param offset Byte offset within resource to start at |
| 689 | * @param buf Destination for data |
| 690 | * @param size Amount of data to read |
| 691 | * @return VB2_SUCCESS, or error code on error. |
| 692 | */ |
Joel Kitching | e6700f4 | 2019-07-31 14:12:30 +0800 | [diff] [blame] | 693 | vb2_error_t vb2ex_read_resource(struct vb2_context *ctx, |
| 694 | enum vb2_resource_index index, uint32_t offset, |
| 695 | void *buf, uint32_t size); |
Randall Spangler | da2b49c | 2014-06-10 17:03:40 -0700 | [diff] [blame] | 696 | |
Randall Spangler | a609478 | 2017-01-20 14:54:47 -0800 | [diff] [blame] | 697 | /** |
| 698 | * Print debug output |
| 699 | * |
| 700 | * This should work like printf(). If func!=NULL, it will be a string with |
| 701 | * the current function name; that can be used to generate prettier debug |
| 702 | * output. If func==NULL, don't print any extra header/trailer so that this |
| 703 | * can be used to composite a bigger output string from several calls - for |
| 704 | * example, when doing a hex dump. |
| 705 | * |
| 706 | * @param func Function name generating output, or NULL. |
| 707 | * @param fmt Printf format string |
| 708 | */ |
Daisuke Nojiri | dd5883d | 2014-06-21 18:02:13 -0700 | [diff] [blame] | 709 | void vb2ex_printf(const char *func, const char *fmt, ...); |
Julius Werner | f10e909 | 2014-12-16 19:24:54 -0800 | [diff] [blame] | 710 | |
| 711 | /** |
| 712 | * Initialize the hardware crypto engine to calculate a block-style digest. |
| 713 | * |
| 714 | * @param hash_alg Hash algorithm to use |
| 715 | * @param data_size Expected total size of data to hash |
| 716 | * @return VB2_SUCCESS, or non-zero error code (HWCRYPTO_UNSUPPORTED not fatal). |
| 717 | */ |
Joel Kitching | e6700f4 | 2019-07-31 14:12:30 +0800 | [diff] [blame] | 718 | vb2_error_t vb2ex_hwcrypto_digest_init(enum vb2_hash_algorithm hash_alg, |
| 719 | uint32_t data_size); |
Julius Werner | f10e909 | 2014-12-16 19:24:54 -0800 | [diff] [blame] | 720 | |
| 721 | /** |
| 722 | * Extend the hash in the hardware crypto engine with another block of data. |
| 723 | * |
| 724 | * @param buf Next data block to hash |
| 725 | * @param size Length of data block in bytes |
| 726 | * @return VB2_SUCCESS, or non-zero error code. |
| 727 | */ |
Joel Kitching | e6700f4 | 2019-07-31 14:12:30 +0800 | [diff] [blame] | 728 | vb2_error_t vb2ex_hwcrypto_digest_extend(const uint8_t *buf, uint32_t size); |
Julius Werner | f10e909 | 2014-12-16 19:24:54 -0800 | [diff] [blame] | 729 | |
| 730 | /** |
| 731 | * Finalize the digest in the hardware crypto engine and extract the result. |
| 732 | * |
| 733 | * @param digest Destination buffer for resulting digest |
| 734 | * @param digest_size Length of digest buffer in bytes |
| 735 | * @return VB2_SUCCESS, or non-zero error code. |
| 736 | */ |
Joel Kitching | e6700f4 | 2019-07-31 14:12:30 +0800 | [diff] [blame] | 737 | vb2_error_t vb2ex_hwcrypto_digest_finalize(uint8_t *digest, |
| 738 | uint32_t digest_size); |
Julius Werner | f10e909 | 2014-12-16 19:24:54 -0800 | [diff] [blame] | 739 | |
Matt Delco | 08bf680 | 2019-02-13 15:54:24 -0800 | [diff] [blame] | 740 | /* |
| 741 | * Set the current TPM mode value, and validate that it was changed. If one |
| 742 | * of the following occurs, the function call fails: |
| 743 | * - TPM does not understand the instruction (old version) |
| 744 | * - TPM has already left the TpmModeEnabledTentative mode |
| 745 | * - TPM responds with a mode other than the requested mode |
| 746 | * - Some other communication error occurs |
| 747 | * Otherwise, the function call succeeds. |
| 748 | * |
| 749 | * @param mode_val Desired TPM mode to set. May be one of ENABLED |
| 750 | * or DISABLED from vb2_tpm_mode enum. |
| 751 | * @returns VB2_SUCCESS, or non-zero error code. |
| 752 | */ |
Joel Kitching | e6700f4 | 2019-07-31 14:12:30 +0800 | [diff] [blame] | 753 | vb2_error_t vb2ex_tpm_set_mode(enum vb2_tpm_mode mode_val); |
Matt Delco | 08bf680 | 2019-02-13 15:54:24 -0800 | [diff] [blame] | 754 | |
Joel Kitching | 9adf2aa | 2019-08-20 17:43:50 +0800 | [diff] [blame] | 755 | #endif /* VBOOT_REFERENCE_2API_H_ */ |