2api.h revision 7c1eee09eff54c6e60a3b261e6df790c11331695
13333e578497aafc4eb8c6e1e359f6e2b1dee633aRandall Spangler/* Copyright (c) 2013 The Chromium OS Authors. All rights reserved. 23333e578497aafc4eb8c6e1e359f6e2b1dee633aRandall Spangler * Use of this source code is governed by a BSD-style license that can be 33333e578497aafc4eb8c6e1e359f6e2b1dee633aRandall Spangler * found in the LICENSE file. 43333e578497aafc4eb8c6e1e359f6e2b1dee633aRandall Spangler */ 53333e578497aafc4eb8c6e1e359f6e2b1dee633aRandall Spangler 63333e578497aafc4eb8c6e1e359f6e2b1dee633aRandall Spangler/* APIs between calling firmware and vboot_reference 73333e578497aafc4eb8c6e1e359f6e2b1dee633aRandall Spangler * 83333e578497aafc4eb8c6e1e359f6e2b1dee633aRandall Spangler * General notes: 93333e578497aafc4eb8c6e1e359f6e2b1dee633aRandall Spangler * 103333e578497aafc4eb8c6e1e359f6e2b1dee633aRandall Spangler * TODO: split this file into a vboot_entry_points.h file which contains the 113333e578497aafc4eb8c6e1e359f6e2b1dee633aRandall Spangler * entry points for the firmware to call vboot_reference, and a 123333e578497aafc4eb8c6e1e359f6e2b1dee633aRandall Spangler * vboot_firmware_exports.h which contains the APIs to be implemented by the 133333e578497aafc4eb8c6e1e359f6e2b1dee633aRandall Spangler * calling firmware and exported to vboot_reference. 143333e578497aafc4eb8c6e1e359f6e2b1dee633aRandall Spangler * 153333e578497aafc4eb8c6e1e359f6e2b1dee633aRandall Spangler * Notes: 163333e578497aafc4eb8c6e1e359f6e2b1dee633aRandall Spangler * * Assumes this code is never called in the S3 resume path. TPM resume 173333e578497aafc4eb8c6e1e359f6e2b1dee633aRandall Spangler * must be done elsewhere, and VB2_NV_DEBUG_RESET_MODE is ignored. 183333e578497aafc4eb8c6e1e359f6e2b1dee633aRandall Spangler */ 193333e578497aafc4eb8c6e1e359f6e2b1dee633aRandall Spangler 203333e578497aafc4eb8c6e1e359f6e2b1dee633aRandall Spangler#ifndef VBOOT_2_API_H_ 213333e578497aafc4eb8c6e1e359f6e2b1dee633aRandall Spangler#define VBOOT_2_API_H_ 223333e578497aafc4eb8c6e1e359f6e2b1dee633aRandall Spangler#include <stdint.h> 233333e578497aafc4eb8c6e1e359f6e2b1dee633aRandall Spangler 24435c74f1ec8a522e41c034cd5fd7a424356dbfb7Randall Spangler#include "2fw_hash_tags.h" 257c1eee09eff54c6e60a3b261e6df790c11331695Randall Spangler#include "2guid.h" 263333e578497aafc4eb8c6e1e359f6e2b1dee633aRandall Spangler#include "2recovery_reasons.h" 273333e578497aafc4eb8c6e1e359f6e2b1dee633aRandall Spangler#include "2return_codes.h" 283333e578497aafc4eb8c6e1e359f6e2b1dee633aRandall Spangler 293333e578497aafc4eb8c6e1e359f6e2b1dee633aRandall Spangler/* Size of non-volatile data used by vboot */ 303333e578497aafc4eb8c6e1e359f6e2b1dee633aRandall Spangler#define VB2_NVDATA_SIZE 16 313333e578497aafc4eb8c6e1e359f6e2b1dee633aRandall Spangler 323333e578497aafc4eb8c6e1e359f6e2b1dee633aRandall Spangler/* Size of secure data used by vboot */ 333333e578497aafc4eb8c6e1e359f6e2b1dee633aRandall Spangler#define VB2_SECDATA_SIZE 10 343333e578497aafc4eb8c6e1e359f6e2b1dee633aRandall Spangler 353333e578497aafc4eb8c6e1e359f6e2b1dee633aRandall Spangler/* 363333e578497aafc4eb8c6e1e359f6e2b1dee633aRandall Spangler * Recommended size of work buffer. 373333e578497aafc4eb8c6e1e359f6e2b1dee633aRandall Spangler * 383333e578497aafc4eb8c6e1e359f6e2b1dee633aRandall Spangler * TODO: The recommended size really depends on which key algorithms are 393333e578497aafc4eb8c6e1e359f6e2b1dee633aRandall Spangler * used. Should have a better / more accurate recommendation than this. 403333e578497aafc4eb8c6e1e359f6e2b1dee633aRandall Spangler */ 413333e578497aafc4eb8c6e1e359f6e2b1dee633aRandall Spangler#define VB2_WORKBUF_RECOMMENDED_SIZE (12 * 1024) 423333e578497aafc4eb8c6e1e359f6e2b1dee633aRandall Spangler 433333e578497aafc4eb8c6e1e359f6e2b1dee633aRandall Spangler/* Flags for vb2_context. 443333e578497aafc4eb8c6e1e359f6e2b1dee633aRandall Spangler * 453333e578497aafc4eb8c6e1e359f6e2b1dee633aRandall Spangler * Unless otherwise noted, flags are set by verified boot and may be read (but 463333e578497aafc4eb8c6e1e359f6e2b1dee633aRandall Spangler * not set or cleared) by the caller. 473333e578497aafc4eb8c6e1e359f6e2b1dee633aRandall Spangler */ 483333e578497aafc4eb8c6e1e359f6e2b1dee633aRandall Spanglerenum vb2_context_flags { 493333e578497aafc4eb8c6e1e359f6e2b1dee633aRandall Spangler 503333e578497aafc4eb8c6e1e359f6e2b1dee633aRandall Spangler /* 513333e578497aafc4eb8c6e1e359f6e2b1dee633aRandall Spangler * Verified boot has changed nvdata[]. Caller must save nvdata[] back 523333e578497aafc4eb8c6e1e359f6e2b1dee633aRandall Spangler * to its underlying storage, then may clear this flag. 533333e578497aafc4eb8c6e1e359f6e2b1dee633aRandall Spangler */ 543333e578497aafc4eb8c6e1e359f6e2b1dee633aRandall Spangler VB2_CONTEXT_NVDATA_CHANGED = (1 << 0), 553333e578497aafc4eb8c6e1e359f6e2b1dee633aRandall Spangler 563333e578497aafc4eb8c6e1e359f6e2b1dee633aRandall Spangler /* 573333e578497aafc4eb8c6e1e359f6e2b1dee633aRandall Spangler * Verified boot has changed secdata[]. Caller must save secdata[] 583333e578497aafc4eb8c6e1e359f6e2b1dee633aRandall Spangler * back to its underlying storage, then may clear this flag. 593333e578497aafc4eb8c6e1e359f6e2b1dee633aRandall Spangler */ 603333e578497aafc4eb8c6e1e359f6e2b1dee633aRandall Spangler VB2_CONTEXT_SECDATA_CHANGED = (1 << 1), 613333e578497aafc4eb8c6e1e359f6e2b1dee633aRandall Spangler 623333e578497aafc4eb8c6e1e359f6e2b1dee633aRandall Spangler /* Recovery mode is requested this boot */ 633333e578497aafc4eb8c6e1e359f6e2b1dee633aRandall Spangler VB2_CONTEXT_RECOVERY_MODE = (1 << 2), 643333e578497aafc4eb8c6e1e359f6e2b1dee633aRandall Spangler 653333e578497aafc4eb8c6e1e359f6e2b1dee633aRandall Spangler /* Developer mode is requested this boot */ 663333e578497aafc4eb8c6e1e359f6e2b1dee633aRandall Spangler VB2_CONTEXT_DEVELOPER_MODE = (1 << 3), 673333e578497aafc4eb8c6e1e359f6e2b1dee633aRandall Spangler 683333e578497aafc4eb8c6e1e359f6e2b1dee633aRandall Spangler /* 693333e578497aafc4eb8c6e1e359f6e2b1dee633aRandall Spangler * Force recovery mode due to physical user request. Caller may set 703333e578497aafc4eb8c6e1e359f6e2b1dee633aRandall Spangler * this flag when initializing the context. 713333e578497aafc4eb8c6e1e359f6e2b1dee633aRandall Spangler */ 723333e578497aafc4eb8c6e1e359f6e2b1dee633aRandall Spangler VB2_CONTEXT_FORCE_RECOVERY_MODE = (1 << 4), 733333e578497aafc4eb8c6e1e359f6e2b1dee633aRandall Spangler 743333e578497aafc4eb8c6e1e359f6e2b1dee633aRandall Spangler /* 753333e578497aafc4eb8c6e1e359f6e2b1dee633aRandall Spangler * Force developer mode enabled. Caller may set this flag when 763333e578497aafc4eb8c6e1e359f6e2b1dee633aRandall Spangler * initializing the context. 773333e578497aafc4eb8c6e1e359f6e2b1dee633aRandall Spangler */ 783333e578497aafc4eb8c6e1e359f6e2b1dee633aRandall Spangler VB2_CONTEXT_FORCE_DEVELOPER_MODE = (1 << 5), 793333e578497aafc4eb8c6e1e359f6e2b1dee633aRandall Spangler 803333e578497aafc4eb8c6e1e359f6e2b1dee633aRandall Spangler /* Using firmware slot B. If this flag is clear, using slot A. */ 813333e578497aafc4eb8c6e1e359f6e2b1dee633aRandall Spangler VB2_CONTEXT_FW_SLOT_B = (1 << 6), 823333e578497aafc4eb8c6e1e359f6e2b1dee633aRandall Spangler 833333e578497aafc4eb8c6e1e359f6e2b1dee633aRandall Spangler /* RAM should be cleared by caller this boot */ 843333e578497aafc4eb8c6e1e359f6e2b1dee633aRandall Spangler VB2_CONTEXT_CLEAR_RAM = (1 << 7), 853333e578497aafc4eb8c6e1e359f6e2b1dee633aRandall Spangler}; 863333e578497aafc4eb8c6e1e359f6e2b1dee633aRandall Spangler 873333e578497aafc4eb8c6e1e359f6e2b1dee633aRandall Spangler/* 883333e578497aafc4eb8c6e1e359f6e2b1dee633aRandall Spangler * Context for firmware verification. Pass this to all vboot APIs. 893333e578497aafc4eb8c6e1e359f6e2b1dee633aRandall Spangler * 903333e578497aafc4eb8c6e1e359f6e2b1dee633aRandall Spangler * Caller may relocate this between calls to vboot APIs. 913333e578497aafc4eb8c6e1e359f6e2b1dee633aRandall Spangler */ 923333e578497aafc4eb8c6e1e359f6e2b1dee633aRandall Spanglerstruct vb2_context { 933333e578497aafc4eb8c6e1e359f6e2b1dee633aRandall Spangler /********************************************************************** 943333e578497aafc4eb8c6e1e359f6e2b1dee633aRandall Spangler * Fields which must be initialized by caller. 953333e578497aafc4eb8c6e1e359f6e2b1dee633aRandall Spangler */ 963333e578497aafc4eb8c6e1e359f6e2b1dee633aRandall Spangler 973333e578497aafc4eb8c6e1e359f6e2b1dee633aRandall Spangler /* 983333e578497aafc4eb8c6e1e359f6e2b1dee633aRandall Spangler * Flags; see vb2_context_flags. Some flags may only be set by caller 993333e578497aafc4eb8c6e1e359f6e2b1dee633aRandall Spangler * prior to calling vboot functions. 1003333e578497aafc4eb8c6e1e359f6e2b1dee633aRandall Spangler */ 1013333e578497aafc4eb8c6e1e359f6e2b1dee633aRandall Spangler uint32_t flags; 1023333e578497aafc4eb8c6e1e359f6e2b1dee633aRandall Spangler 1033333e578497aafc4eb8c6e1e359f6e2b1dee633aRandall Spangler /* 1043333e578497aafc4eb8c6e1e359f6e2b1dee633aRandall Spangler * Work buffer, and length in bytes. Caller may relocate this between 1053333e578497aafc4eb8c6e1e359f6e2b1dee633aRandall Spangler * calls to vboot APIs; it contains no internal pointers. Caller must 1063333e578497aafc4eb8c6e1e359f6e2b1dee633aRandall Spangler * not examine the contents of this work buffer directly. 1073333e578497aafc4eb8c6e1e359f6e2b1dee633aRandall Spangler */ 1083333e578497aafc4eb8c6e1e359f6e2b1dee633aRandall Spangler uint8_t *workbuf; 1093333e578497aafc4eb8c6e1e359f6e2b1dee633aRandall Spangler uint32_t workbuf_size; 1103333e578497aafc4eb8c6e1e359f6e2b1dee633aRandall Spangler 1113333e578497aafc4eb8c6e1e359f6e2b1dee633aRandall Spangler /* 1123333e578497aafc4eb8c6e1e359f6e2b1dee633aRandall Spangler * Non-volatile data. Caller must fill this from some non-volatile 1133333e578497aafc4eb8c6e1e359f6e2b1dee633aRandall Spangler * location. If the VB2_CONTEXT_NVDATA_CHANGED flag is set when a 1143333e578497aafc4eb8c6e1e359f6e2b1dee633aRandall Spangler * vb2api function returns, caller must save the data back to the 1153333e578497aafc4eb8c6e1e359f6e2b1dee633aRandall Spangler * non-volatile location and then clear the flag. 1163333e578497aafc4eb8c6e1e359f6e2b1dee633aRandall Spangler */ 1173333e578497aafc4eb8c6e1e359f6e2b1dee633aRandall Spangler uint8_t nvdata[VB2_NVDATA_SIZE]; 1183333e578497aafc4eb8c6e1e359f6e2b1dee633aRandall Spangler 1193333e578497aafc4eb8c6e1e359f6e2b1dee633aRandall Spangler /* 1203333e578497aafc4eb8c6e1e359f6e2b1dee633aRandall Spangler * Secure data. Caller must fill this from some secure non-volatile 1213333e578497aafc4eb8c6e1e359f6e2b1dee633aRandall Spangler * location. If the VB2_CONTEXT_SECDATA_CHANGED flag is set when a 1223333e578497aafc4eb8c6e1e359f6e2b1dee633aRandall Spangler * function returns, caller must save the data back to the secure 1233333e578497aafc4eb8c6e1e359f6e2b1dee633aRandall Spangler * non-volatile location and then clear the flag. 1243333e578497aafc4eb8c6e1e359f6e2b1dee633aRandall Spangler */ 1253333e578497aafc4eb8c6e1e359f6e2b1dee633aRandall Spangler uint8_t secdata[VB2_SECDATA_SIZE]; 1263333e578497aafc4eb8c6e1e359f6e2b1dee633aRandall Spangler 1273333e578497aafc4eb8c6e1e359f6e2b1dee633aRandall Spangler /* 1283333e578497aafc4eb8c6e1e359f6e2b1dee633aRandall Spangler * Context pointer for use by caller. Verified boot never looks at 1293333e578497aafc4eb8c6e1e359f6e2b1dee633aRandall Spangler * this. Put context here if you need it for APIs that verified boot 1303333e578497aafc4eb8c6e1e359f6e2b1dee633aRandall Spangler * may call (vb2ex_...() functions). 1313333e578497aafc4eb8c6e1e359f6e2b1dee633aRandall Spangler */ 1323333e578497aafc4eb8c6e1e359f6e2b1dee633aRandall Spangler void *non_vboot_context; 1333333e578497aafc4eb8c6e1e359f6e2b1dee633aRandall Spangler 1343333e578497aafc4eb8c6e1e359f6e2b1dee633aRandall Spangler /********************************************************************** 1353333e578497aafc4eb8c6e1e359f6e2b1dee633aRandall Spangler * Fields caller may examine after calling vb2api_fw_phase1(). Caller 1363333e578497aafc4eb8c6e1e359f6e2b1dee633aRandall Spangler * must set these fields to 0 before calling any vboot functions. 1373333e578497aafc4eb8c6e1e359f6e2b1dee633aRandall Spangler */ 1383333e578497aafc4eb8c6e1e359f6e2b1dee633aRandall Spangler 1393333e578497aafc4eb8c6e1e359f6e2b1dee633aRandall Spangler /* 1403333e578497aafc4eb8c6e1e359f6e2b1dee633aRandall Spangler * Amount of work buffer used so far. Verified boot sub-calls use 1413333e578497aafc4eb8c6e1e359f6e2b1dee633aRandall Spangler * this to know where the unused work area starts. Caller may use 1423333e578497aafc4eb8c6e1e359f6e2b1dee633aRandall Spangler * this between calls to vboot APIs to know how much data must be 1433333e578497aafc4eb8c6e1e359f6e2b1dee633aRandall Spangler * copied when relocating the work buffer. 1443333e578497aafc4eb8c6e1e359f6e2b1dee633aRandall Spangler */ 1453333e578497aafc4eb8c6e1e359f6e2b1dee633aRandall Spangler uint32_t workbuf_used; 1463333e578497aafc4eb8c6e1e359f6e2b1dee633aRandall Spangler}; 1473333e578497aafc4eb8c6e1e359f6e2b1dee633aRandall Spangler 148da2b49cf08a27551fd910626f669910a636378d4Randall Spanglerenum vb2_resource_index { 149da2b49cf08a27551fd910626f669910a636378d4Randall Spangler 150da2b49cf08a27551fd910626f669910a636378d4Randall Spangler /* Google binary block */ 151da2b49cf08a27551fd910626f669910a636378d4Randall Spangler VB2_RES_GBB, 152da2b49cf08a27551fd910626f669910a636378d4Randall Spangler 153da2b49cf08a27551fd910626f669910a636378d4Randall Spangler /* 154da2b49cf08a27551fd910626f669910a636378d4Randall Spangler * Verified boot block (keyblock+preamble). Use VB2_CONTEXT_FW_SLOT_B 155da2b49cf08a27551fd910626f669910a636378d4Randall Spangler * to determine whether this refers to slot A or slot B; vboot will 156da2b49cf08a27551fd910626f669910a636378d4Randall Spangler * set that flag to the proper state before reading the vblock. 157da2b49cf08a27551fd910626f669910a636378d4Randall Spangler */ 158da2b49cf08a27551fd910626f669910a636378d4Randall Spangler VB2_RES_FW_VBLOCK, 159da2b49cf08a27551fd910626f669910a636378d4Randall Spangler}; 160da2b49cf08a27551fd910626f669910a636378d4Randall Spangler 161a7ab8b50b8923afcfd7a9e6181892c4c8a2de250Randall Spangler/****************************************************************************** 162a7ab8b50b8923afcfd7a9e6181892c4c8a2de250Randall Spangler * APIs provided by verified boot. 163a7ab8b50b8923afcfd7a9e6181892c4c8a2de250Randall Spangler * 164a7ab8b50b8923afcfd7a9e6181892c4c8a2de250Randall Spangler * At a high level, call functions in the order described below. After each 165a7ab8b50b8923afcfd7a9e6181892c4c8a2de250Randall Spangler * call, examine vb2_context.flags to determine whether nvdata or secdata 166a7ab8b50b8923afcfd7a9e6181892c4c8a2de250Randall Spangler * needs to be written. 167a7ab8b50b8923afcfd7a9e6181892c4c8a2de250Randall Spangler * 168a7ab8b50b8923afcfd7a9e6181892c4c8a2de250Randall Spangler * If you need to cause the boot process to fail at any point, call 169a7ab8b50b8923afcfd7a9e6181892c4c8a2de250Randall Spangler * vb2api_fail(). Then check vb2_context.flags to see what data needs to be 170a7ab8b50b8923afcfd7a9e6181892c4c8a2de250Randall Spangler * written. Then reboot. 171a7ab8b50b8923afcfd7a9e6181892c4c8a2de250Randall Spangler * 172a7ab8b50b8923afcfd7a9e6181892c4c8a2de250Randall Spangler * Load nvdata from wherever you keep it. 173a7ab8b50b8923afcfd7a9e6181892c4c8a2de250Randall Spangler * 174a7ab8b50b8923afcfd7a9e6181892c4c8a2de250Randall Spangler * Load secdata from wherever you keep it. 175a7ab8b50b8923afcfd7a9e6181892c4c8a2de250Randall Spangler * 176a7ab8b50b8923afcfd7a9e6181892c4c8a2de250Randall Spangler * If it wasn't there at all (for example, this is the first boot 177a7ab8b50b8923afcfd7a9e6181892c4c8a2de250Randall Spangler * of a new system in the factory), call vb2api_secdata_create() 178a7ab8b50b8923afcfd7a9e6181892c4c8a2de250Randall Spangler * to initialize the data. 179a7ab8b50b8923afcfd7a9e6181892c4c8a2de250Randall Spangler * 180a7ab8b50b8923afcfd7a9e6181892c4c8a2de250Randall Spangler * If access to your storage is unreliable (reads/writes may 181a7ab8b50b8923afcfd7a9e6181892c4c8a2de250Randall Spangler * contain corrupt data), you may call vb2api_secdata_check() to 182a7ab8b50b8923afcfd7a9e6181892c4c8a2de250Randall Spangler * determine if the data was valid, and retry reading if it 183a7ab8b50b8923afcfd7a9e6181892c4c8a2de250Randall Spangler * wasn't. (In that case, you should also read back and check the 184a7ab8b50b8923afcfd7a9e6181892c4c8a2de250Randall Spangler * data after any time you write it, to make sure it was written 185a7ab8b50b8923afcfd7a9e6181892c4c8a2de250Randall Spangler * correctly.) 186a7ab8b50b8923afcfd7a9e6181892c4c8a2de250Randall Spangler * 187a7ab8b50b8923afcfd7a9e6181892c4c8a2de250Randall Spangler * Call vb2api_fw_phase1(). At present, this nominally decides whether 188a7ab8b50b8923afcfd7a9e6181892c4c8a2de250Randall Spangler * recovery mode is needed this boot. 189a7ab8b50b8923afcfd7a9e6181892c4c8a2de250Randall Spangler * 190a7ab8b50b8923afcfd7a9e6181892c4c8a2de250Randall Spangler * Call vb2api_fw_phase2(). At present, this nominally decides which 191a7ab8b50b8923afcfd7a9e6181892c4c8a2de250Randall Spangler * firmware slot will be attempted (A or B). 192a7ab8b50b8923afcfd7a9e6181892c4c8a2de250Randall Spangler * 193a7ab8b50b8923afcfd7a9e6181892c4c8a2de250Randall Spangler * Call vb2api_fw_phase3(). At present, this nominally verifies the 194a7ab8b50b8923afcfd7a9e6181892c4c8a2de250Randall Spangler * firmware keyblock and preamble. 195a7ab8b50b8923afcfd7a9e6181892c4c8a2de250Randall Spangler * 196a7ab8b50b8923afcfd7a9e6181892c4c8a2de250Randall Spangler * Lock down wherever you keep secdata. It should no longer be writable 197a7ab8b50b8923afcfd7a9e6181892c4c8a2de250Randall Spangler * this boot. 198a7ab8b50b8923afcfd7a9e6181892c4c8a2de250Randall Spangler * 199a7ab8b50b8923afcfd7a9e6181892c4c8a2de250Randall Spangler * Verify the hash of each section of code/data you need to boot the RW 200a7ab8b50b8923afcfd7a9e6181892c4c8a2de250Randall Spangler * firmware. For each section: 201a7ab8b50b8923afcfd7a9e6181892c4c8a2de250Randall Spangler * 202a7ab8b50b8923afcfd7a9e6181892c4c8a2de250Randall Spangler * Call vb2_init_hash() to see if the hash exists. 203a7ab8b50b8923afcfd7a9e6181892c4c8a2de250Randall Spangler * 204a7ab8b50b8923afcfd7a9e6181892c4c8a2de250Randall Spangler * Load the data for the section. Call vb2_extend_hash() on the 205a7ab8b50b8923afcfd7a9e6181892c4c8a2de250Randall Spangler * data as you load it. You can load it all at once and make one 206a7ab8b50b8923afcfd7a9e6181892c4c8a2de250Randall Spangler * call, or load and hash-extend a block at a time. 207a7ab8b50b8923afcfd7a9e6181892c4c8a2de250Randall Spangler * 208a7ab8b50b8923afcfd7a9e6181892c4c8a2de250Randall Spangler * Call vb2_check_hash() to see if the hash is valid. 209a7ab8b50b8923afcfd7a9e6181892c4c8a2de250Randall Spangler * 210a7ab8b50b8923afcfd7a9e6181892c4c8a2de250Randall Spangler * If it is valid, you may use the data and/or execute 211a7ab8b50b8923afcfd7a9e6181892c4c8a2de250Randall Spangler * code from that section. 212a7ab8b50b8923afcfd7a9e6181892c4c8a2de250Randall Spangler * 213a7ab8b50b8923afcfd7a9e6181892c4c8a2de250Randall Spangler * If the hash was invalid, you must reboot. 214a7ab8b50b8923afcfd7a9e6181892c4c8a2de250Randall Spangler * 215a7ab8b50b8923afcfd7a9e6181892c4c8a2de250Randall Spangler * At this point, firmware verification is done, and vb2_context contains the 216a7ab8b50b8923afcfd7a9e6181892c4c8a2de250Randall Spangler * kernel key needed to verify the kernel. That context should be preserved 217a7ab8b50b8923afcfd7a9e6181892c4c8a2de250Randall Spangler * and passed on to kernel selection. For now, that requires translating it 218a7ab8b50b8923afcfd7a9e6181892c4c8a2de250Randall Spangler * into the old VbSharedData format (via a func which does not yet exist...) 219a7ab8b50b8923afcfd7a9e6181892c4c8a2de250Randall Spangler */ 220a7ab8b50b8923afcfd7a9e6181892c4c8a2de250Randall Spangler 221a7ab8b50b8923afcfd7a9e6181892c4c8a2de250Randall Spangler/** 222a7ab8b50b8923afcfd7a9e6181892c4c8a2de250Randall Spangler * Sanity-check the contents of the secure storage context. 223a7ab8b50b8923afcfd7a9e6181892c4c8a2de250Randall Spangler * 224a7ab8b50b8923afcfd7a9e6181892c4c8a2de250Randall Spangler * Use this if reading from secure storage may be flaky, and you want to retry 225a7ab8b50b8923afcfd7a9e6181892c4c8a2de250Randall Spangler * reading it several times. 226a7ab8b50b8923afcfd7a9e6181892c4c8a2de250Randall Spangler * 227a7ab8b50b8923afcfd7a9e6181892c4c8a2de250Randall Spangler * This may be called before vb2api_phase1(). 228a7ab8b50b8923afcfd7a9e6181892c4c8a2de250Randall Spangler * 229a7ab8b50b8923afcfd7a9e6181892c4c8a2de250Randall Spangler * @param ctx Context pointer 230a7ab8b50b8923afcfd7a9e6181892c4c8a2de250Randall Spangler * @return VB2_SUCCESS, or non-zero error code if error. 231a7ab8b50b8923afcfd7a9e6181892c4c8a2de250Randall Spangler */ 232a7ab8b50b8923afcfd7a9e6181892c4c8a2de250Randall Spanglerint vb2api_secdata_check(const struct vb2_context *ctx); 233a7ab8b50b8923afcfd7a9e6181892c4c8a2de250Randall Spangler 234a7ab8b50b8923afcfd7a9e6181892c4c8a2de250Randall Spangler/** 235a7ab8b50b8923afcfd7a9e6181892c4c8a2de250Randall Spangler * Create fresh data in the secure storage context. 236a7ab8b50b8923afcfd7a9e6181892c4c8a2de250Randall Spangler * 237a7ab8b50b8923afcfd7a9e6181892c4c8a2de250Randall Spangler * Use this only when initializing the secure storage context on a new machine 238a7ab8b50b8923afcfd7a9e6181892c4c8a2de250Randall Spangler * the first time it boots. Do NOT simply use this if vb2api_secdata_check() 239a7ab8b50b8923afcfd7a9e6181892c4c8a2de250Randall Spangler * (or any other API in this library) fails; that could allow the secure data 240a7ab8b50b8923afcfd7a9e6181892c4c8a2de250Randall Spangler * to be rolled back to an insecure state. 241a7ab8b50b8923afcfd7a9e6181892c4c8a2de250Randall Spangler * 242a7ab8b50b8923afcfd7a9e6181892c4c8a2de250Randall Spangler * This may be called before vb2api_phase1(). 243a7ab8b50b8923afcfd7a9e6181892c4c8a2de250Randall Spangler * 244a7ab8b50b8923afcfd7a9e6181892c4c8a2de250Randall Spangler * @param ctx Context pointer 245a7ab8b50b8923afcfd7a9e6181892c4c8a2de250Randall Spangler * @return VB2_SUCCESS, or non-zero error code if error. 246a7ab8b50b8923afcfd7a9e6181892c4c8a2de250Randall Spangler */ 247a7ab8b50b8923afcfd7a9e6181892c4c8a2de250Randall Spanglerint vb2api_secdata_create(struct vb2_context *ctx); 248a7ab8b50b8923afcfd7a9e6181892c4c8a2de250Randall Spangler 249a7ab8b50b8923afcfd7a9e6181892c4c8a2de250Randall Spangler/** 250a7ab8b50b8923afcfd7a9e6181892c4c8a2de250Randall Spangler * Report firmware failure to vboot. 251a7ab8b50b8923afcfd7a9e6181892c4c8a2de250Randall Spangler * 252a7ab8b50b8923afcfd7a9e6181892c4c8a2de250Randall Spangler * This may be called before vb2api_phase1() to indicate errors in the boot 253a7ab8b50b8923afcfd7a9e6181892c4c8a2de250Randall Spangler * process prior to the start of vboot. 254a7ab8b50b8923afcfd7a9e6181892c4c8a2de250Randall Spangler * 255a7ab8b50b8923afcfd7a9e6181892c4c8a2de250Randall Spangler * If this is called after vb2api_phase1(), on return, the calling firmware 256a7ab8b50b8923afcfd7a9e6181892c4c8a2de250Randall Spangler * should check for updates to secdata and/or nvdata, then reboot. 257a7ab8b50b8923afcfd7a9e6181892c4c8a2de250Randall Spangler * 258a7ab8b50b8923afcfd7a9e6181892c4c8a2de250Randall Spangler * @param reason Recovery reason 259a7ab8b50b8923afcfd7a9e6181892c4c8a2de250Randall Spangler * @param subcode Recovery subcode 260a7ab8b50b8923afcfd7a9e6181892c4c8a2de250Randall Spangler */ 261a7ab8b50b8923afcfd7a9e6181892c4c8a2de250Randall Spanglervoid vb2api_fail(struct vb2_context *ctx, uint8_t reason, uint8_t subcode); 262a7ab8b50b8923afcfd7a9e6181892c4c8a2de250Randall Spangler 263a7ab8b50b8923afcfd7a9e6181892c4c8a2de250Randall Spangler/** 264a7ab8b50b8923afcfd7a9e6181892c4c8a2de250Randall Spangler * Firmware selection, phase 1. 265a7ab8b50b8923afcfd7a9e6181892c4c8a2de250Randall Spangler * 266a7ab8b50b8923afcfd7a9e6181892c4c8a2de250Randall Spangler * On error, the calling firmware should jump directly to recovery-mode 267a7ab8b50b8923afcfd7a9e6181892c4c8a2de250Randall Spangler * firmware without rebooting. 268a7ab8b50b8923afcfd7a9e6181892c4c8a2de250Randall Spangler * 269a7ab8b50b8923afcfd7a9e6181892c4c8a2de250Randall Spangler * @param ctx Vboot context 270a7ab8b50b8923afcfd7a9e6181892c4c8a2de250Randall Spangler * @return VB2_SUCCESS, or error code on error. 271a7ab8b50b8923afcfd7a9e6181892c4c8a2de250Randall Spangler */ 272a7ab8b50b8923afcfd7a9e6181892c4c8a2de250Randall Spanglerint vb2api_fw_phase1(struct vb2_context *ctx); 273a7ab8b50b8923afcfd7a9e6181892c4c8a2de250Randall Spangler 274a7ab8b50b8923afcfd7a9e6181892c4c8a2de250Randall Spangler/** 275a7ab8b50b8923afcfd7a9e6181892c4c8a2de250Randall Spangler * Firmware selection, phase 2. 276a7ab8b50b8923afcfd7a9e6181892c4c8a2de250Randall Spangler * 277a7ab8b50b8923afcfd7a9e6181892c4c8a2de250Randall Spangler * On error, the calling firmware should check for updates to secdata and/or 278a7ab8b50b8923afcfd7a9e6181892c4c8a2de250Randall Spangler * nvdata, then reboot. 279a7ab8b50b8923afcfd7a9e6181892c4c8a2de250Randall Spangler * 280a7ab8b50b8923afcfd7a9e6181892c4c8a2de250Randall Spangler * @param ctx Vboot context 281a7ab8b50b8923afcfd7a9e6181892c4c8a2de250Randall Spangler * @return VB2_SUCCESS, or error code on error. 282a7ab8b50b8923afcfd7a9e6181892c4c8a2de250Randall Spangler */ 283a7ab8b50b8923afcfd7a9e6181892c4c8a2de250Randall Spanglerint vb2api_fw_phase2(struct vb2_context *ctx); 284a7ab8b50b8923afcfd7a9e6181892c4c8a2de250Randall Spangler 285a7ab8b50b8923afcfd7a9e6181892c4c8a2de250Randall Spangler/** 286a7ab8b50b8923afcfd7a9e6181892c4c8a2de250Randall Spangler * Firmware selection, phase 3. 287a7ab8b50b8923afcfd7a9e6181892c4c8a2de250Randall Spangler * 288a7ab8b50b8923afcfd7a9e6181892c4c8a2de250Randall Spangler * On error, the calling firmware should check for updates to secdata and/or 289a7ab8b50b8923afcfd7a9e6181892c4c8a2de250Randall Spangler * nvdata, then reboot. 290a7ab8b50b8923afcfd7a9e6181892c4c8a2de250Randall Spangler * 291a7ab8b50b8923afcfd7a9e6181892c4c8a2de250Randall Spangler * On success, the calling firmware should lock down secdata before continuing 292a7ab8b50b8923afcfd7a9e6181892c4c8a2de250Randall Spangler * with the boot process. 293a7ab8b50b8923afcfd7a9e6181892c4c8a2de250Randall Spangler * 294a7ab8b50b8923afcfd7a9e6181892c4c8a2de250Randall Spangler * @param ctx Vboot context 295a7ab8b50b8923afcfd7a9e6181892c4c8a2de250Randall Spangler * @return VB2_SUCCESS, or error code on error. 296a7ab8b50b8923afcfd7a9e6181892c4c8a2de250Randall Spangler */ 297a7ab8b50b8923afcfd7a9e6181892c4c8a2de250Randall Spanglerint vb2api_fw_phase3(struct vb2_context *ctx); 298a7ab8b50b8923afcfd7a9e6181892c4c8a2de250Randall Spangler 299a7ab8b50b8923afcfd7a9e6181892c4c8a2de250Randall Spangler/** 300a7ab8b50b8923afcfd7a9e6181892c4c8a2de250Randall Spangler * Initialize hashing data for the specified tag. 301a7ab8b50b8923afcfd7a9e6181892c4c8a2de250Randall Spangler * 302a7ab8b50b8923afcfd7a9e6181892c4c8a2de250Randall Spangler * @param ctx Vboot context 303435c74f1ec8a522e41c034cd5fd7a424356dbfb7Randall Spangler * @param tag Tag to start hashing (enum vb2_hash_tag) 304a7ab8b50b8923afcfd7a9e6181892c4c8a2de250Randall Spangler * @param size If non-null, expected size of data for tag will be 305a7ab8b50b8923afcfd7a9e6181892c4c8a2de250Randall Spangler * stored here on output. 306a7ab8b50b8923afcfd7a9e6181892c4c8a2de250Randall Spangler * @return VB2_SUCCESS, or error code on error. 307a7ab8b50b8923afcfd7a9e6181892c4c8a2de250Randall Spangler */ 308a7ab8b50b8923afcfd7a9e6181892c4c8a2de250Randall Spanglerint vb2api_init_hash(struct vb2_context *ctx, uint32_t tag, uint32_t *size); 309a7ab8b50b8923afcfd7a9e6181892c4c8a2de250Randall Spangler 310a7ab8b50b8923afcfd7a9e6181892c4c8a2de250Randall Spangler/** 311a7ab8b50b8923afcfd7a9e6181892c4c8a2de250Randall Spangler * Extend the hash started by vb2api_init_hash() with additional data. 312a7ab8b50b8923afcfd7a9e6181892c4c8a2de250Randall Spangler * 313a7ab8b50b8923afcfd7a9e6181892c4c8a2de250Randall Spangler * @param ctx Vboot context 314a7ab8b50b8923afcfd7a9e6181892c4c8a2de250Randall Spangler * @param buf Data to hash 315a7ab8b50b8923afcfd7a9e6181892c4c8a2de250Randall Spangler * @param size Size of data in bytes 316a7ab8b50b8923afcfd7a9e6181892c4c8a2de250Randall Spangler * @return VB2_SUCCESS, or error code on error. 317a7ab8b50b8923afcfd7a9e6181892c4c8a2de250Randall Spangler */ 318a7ab8b50b8923afcfd7a9e6181892c4c8a2de250Randall Spanglerint vb2api_extend_hash(struct vb2_context *ctx, 319a7ab8b50b8923afcfd7a9e6181892c4c8a2de250Randall Spangler const void *buf, 320a7ab8b50b8923afcfd7a9e6181892c4c8a2de250Randall Spangler uint32_t size); 321a7ab8b50b8923afcfd7a9e6181892c4c8a2de250Randall Spangler 322a7ab8b50b8923afcfd7a9e6181892c4c8a2de250Randall Spangler/** 323a7ab8b50b8923afcfd7a9e6181892c4c8a2de250Randall Spangler * Check the hash value started by vb2api_init_hash(). 324a7ab8b50b8923afcfd7a9e6181892c4c8a2de250Randall Spangler * 325a7ab8b50b8923afcfd7a9e6181892c4c8a2de250Randall Spangler * @param ctx Vboot context 326a7ab8b50b8923afcfd7a9e6181892c4c8a2de250Randall Spangler * @return VB2_SUCCESS, or error code on error. 327a7ab8b50b8923afcfd7a9e6181892c4c8a2de250Randall Spangler */ 328a7ab8b50b8923afcfd7a9e6181892c4c8a2de250Randall Spanglerint vb2api_check_hash(struct vb2_context *ctx); 329a7ab8b50b8923afcfd7a9e6181892c4c8a2de250Randall Spangler 330a7ab8b50b8923afcfd7a9e6181892c4c8a2de250Randall Spanglerint vb2api_get_kernel_subkey(struct vb2_context *ctx, 331a7ab8b50b8923afcfd7a9e6181892c4c8a2de250Randall Spangler uint8_t *buf, 332a7ab8b50b8923afcfd7a9e6181892c4c8a2de250Randall Spangler uint32_t *size); 333a7ab8b50b8923afcfd7a9e6181892c4c8a2de250Randall Spangler 334da2b49cf08a27551fd910626f669910a636378d4Randall Spangler/*****************************************************************************/ 335da2b49cf08a27551fd910626f669910a636378d4Randall Spangler/* APIs provided by the caller to verified boot */ 336da2b49cf08a27551fd910626f669910a636378d4Randall Spangler 337da2b49cf08a27551fd910626f669910a636378d4Randall Spangler/** 338da2b49cf08a27551fd910626f669910a636378d4Randall Spangler * Clear the TPM owner. 339da2b49cf08a27551fd910626f669910a636378d4Randall Spangler * 340da2b49cf08a27551fd910626f669910a636378d4Randall Spangler * @param ctx Vboot context 341da2b49cf08a27551fd910626f669910a636378d4Randall Spangler * @return VB2_SUCCESS, or error code on error. 342da2b49cf08a27551fd910626f669910a636378d4Randall Spangler */ 343da2b49cf08a27551fd910626f669910a636378d4Randall Spanglerint vb2ex_tpm_clear_owner(struct vb2_context *ctx); 344da2b49cf08a27551fd910626f669910a636378d4Randall Spangler 345da2b49cf08a27551fd910626f669910a636378d4Randall Spangler/** 346da2b49cf08a27551fd910626f669910a636378d4Randall Spangler * Read a verified boot resource. 347da2b49cf08a27551fd910626f669910a636378d4Randall Spangler * 348da2b49cf08a27551fd910626f669910a636378d4Randall Spangler * @param ctx Vboot context 349da2b49cf08a27551fd910626f669910a636378d4Randall Spangler * @param index Resource index to read 350da2b49cf08a27551fd910626f669910a636378d4Randall Spangler * @param offset Byte offset within resource to start at 351da2b49cf08a27551fd910626f669910a636378d4Randall Spangler * @param buf Destination for data 352da2b49cf08a27551fd910626f669910a636378d4Randall Spangler * @param size Amount of data to read 353da2b49cf08a27551fd910626f669910a636378d4Randall Spangler * @return VB2_SUCCESS, or error code on error. 354da2b49cf08a27551fd910626f669910a636378d4Randall Spangler */ 355da2b49cf08a27551fd910626f669910a636378d4Randall Spanglerint vb2ex_read_resource(struct vb2_context *ctx, 356da2b49cf08a27551fd910626f669910a636378d4Randall Spangler enum vb2_resource_index index, 357da2b49cf08a27551fd910626f669910a636378d4Randall Spangler uint32_t offset, 358da2b49cf08a27551fd910626f669910a636378d4Randall Spangler void *buf, 359da2b49cf08a27551fd910626f669910a636378d4Randall Spangler uint32_t size); 360da2b49cf08a27551fd910626f669910a636378d4Randall Spangler 361dd5883dee60a06995bb167badc2352bf42a8aee5Daisuke Nojirivoid vb2ex_printf(const char *func, const char *fmt, ...); 3623333e578497aafc4eb8c6e1e359f6e2b1dee633aRandall Spangler#endif /* VBOOT_2_API_H_ */ 363