1 /* Copyright 2013 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 * TPM Lightweight Command Library. 6 * 7 * A low-level library for interfacing to TPM hardware or an emulator. 8 */ 9 10 #ifndef VBOOT_REFERENCE_TLCL_H_ 11 #define VBOOT_REFERENCE_TLCL_H_ 12 13 #include <stddef.h> 14 #include <stdint.h> 15 16 #include "tss_constants.h" 17 18 #ifdef __cplusplus 19 extern "C" { 20 #endif 21 22 /*****************************************************************************/ 23 /* Functions implemented in tlcl.c */ 24 25 /** 26 * Call this first. Returns 0 if success, nonzero if error. 27 */ 28 uint32_t TlclLibInit(void); 29 30 /** 31 * Call this on shutdown. Returns 0 if success, nonzero if error. 32 */ 33 uint32_t TlclLibClose(void); 34 35 /* Low-level operations */ 36 37 /** 38 * Perform a raw TPM request/response transaction. 39 */ 40 uint32_t TlclSendReceive(const uint8_t *request, uint8_t *response, 41 int max_length); 42 43 /** 44 * Return the size of a TPM request or response packet. 45 */ 46 int TlclPacketSize(const uint8_t *packet); 47 48 /* Commands */ 49 50 /** 51 * Send a TPM_Startup(ST_CLEAR). The TPM error code is returned (0 for 52 * success). 53 */ 54 uint32_t TlclStartup(void); 55 56 /** 57 * Save the TPM state. Normally done by the kernel before a suspend, included 58 * here for tests. The TPM error code is returned (0 for success). 59 */ 60 uint32_t TlclSaveState(void); 61 62 /** 63 * Resume by sending a TPM_Startup(ST_STATE). The TPM error code is returned 64 * (0 for success). 65 */ 66 uint32_t TlclResume(void); 67 68 /** 69 * Run the self test. 70 * 71 * Note---this is synchronous. To run this in parallel with other firmware, 72 * use ContinueSelfTest(). The TPM error code is returned. 73 */ 74 uint32_t TlclSelfTestFull(void); 75 76 /** 77 * Run the self test in the background. 78 */ 79 uint32_t TlclContinueSelfTest(void); 80 81 /** 82 * Define a space with permission [perm]. [index] is the index for the space, 83 * [size] the usable data size. The TPM error code is returned. 84 */ 85 uint32_t TlclDefineSpace(uint32_t index, uint32_t perm, uint32_t size); 86 87 /** 88 * Define a space using owner authorization secret [owner_auth]. The space is 89 * set up to have permission [perm]. [index] is the index for the space, [size] 90 * the usable data size. Optional auth policy (such as PCR selections) can be 91 * passed via [auth_policy]. The TPM error code is returned. 92 */ 93 uint32_t TlclDefineSpaceEx(const uint8_t* owner_auth, uint32_t owner_auth_size, 94 uint32_t index, uint32_t perm, uint32_t size, 95 const void* auth_policy, uint32_t auth_policy_size); 96 97 /** 98 * Initializes [auth_policy] to require PCR binding of the given 99 * [pcr_selection_bitmap]. The PCR values are passed in the [pcr_values] 100 * parameter with each entry corresponding to the sequence of indexes that 101 * corresponds to the bits that are set in [pcr_selection_bitmap]. Returns 102 * TPM_SUCCESS if successful, TPM_E_BUFFER_SIZE if the provided buffer is too 103 * short. The actual size of the policy will be set in [auth_policy_size] upon 104 * return, also for the case of insufficient buffer size. 105 */ 106 uint32_t TlclInitNvAuthPolicy(uint32_t pcr_selection_bitmap, 107 const uint8_t pcr_values[][TPM_PCR_DIGEST], 108 void* auth_policy, uint32_t* auth_policy_size); 109 110 /** 111 * Write [length] bytes of [data] to space at [index]. The TPM error code is 112 * returned. 113 */ 114 uint32_t TlclWrite(uint32_t index, const void *data, uint32_t length); 115 116 /** 117 * Read [length] bytes from space at [index] into [data]. The TPM error code 118 * is returned. 119 */ 120 uint32_t TlclRead(uint32_t index, void *data, uint32_t length); 121 122 /** 123 * Read PCR at [index] into [data]. [length] must be TPM_PCR_DIGEST or 124 * larger. The TPM error code is returned. 125 */ 126 uint32_t TlclPCRRead(uint32_t index, void *data, uint32_t length); 127 128 /** 129 * Write-lock space at [index]. The TPM error code is returned. 130 */ 131 uint32_t TlclWriteLock(uint32_t index); 132 133 /** 134 * Read-lock space at [index]. The TPM error code is returned. 135 */ 136 uint32_t TlclReadLock(uint32_t index); 137 138 /** 139 * Assert physical presence in software. The TPM error code is returned. 140 */ 141 uint32_t TlclAssertPhysicalPresence(void); 142 143 /** 144 * Enable the physical presence command. The TPM error code is returned. 145 */ 146 uint32_t TlclPhysicalPresenceCMDEnable(void); 147 148 /** 149 * Finalize the physical presence settings: sofware PP is enabled, hardware PP 150 * is disabled, and the lifetime lock is set. The TPM error code is returned. 151 */ 152 uint32_t TlclFinalizePhysicalPresence(void); 153 154 uint32_t TlclAssertPhysicalPresenceResult(void); 155 156 /** 157 * Turn off physical presence and locks it off until next reboot. The TPM 158 * error code is returned. 159 */ 160 uint32_t TlclLockPhysicalPresence(void); 161 162 /** 163 * Set the nvLocked bit. The TPM error code is returned. 164 */ 165 uint32_t TlclSetNvLocked(void); 166 167 /** 168 * Return 1 if the TPM is owned, 0 otherwise. 169 */ 170 int TlclIsOwned(void); 171 172 /** 173 * Issue a ForceClear. The TPM error code is returned. 174 */ 175 uint32_t TlclForceClear(void); 176 177 /** 178 * Issue a PhysicalEnable. The TPM error code is returned. 179 */ 180 uint32_t TlclSetEnable(void); 181 182 /** 183 * Issue a PhysicalDisable. The TPM error code is returned. 184 */ 185 uint32_t TlclClearEnable(void); 186 187 /** 188 * Issue a SetDeactivated. Pass 0 to activate. Returns result code. 189 */ 190 uint32_t TlclSetDeactivated(uint8_t flag); 191 192 /** 193 * Get flags of interest. Pointers for flags you aren't interested in may 194 * be NULL. The TPM error code is returned. 195 */ 196 uint32_t TlclGetFlags(uint8_t *disable, uint8_t *deactivated, 197 uint8_t *nvlocked); 198 199 /** 200 * Set the bGlobalLock flag, which only a reboot can clear. The TPM error 201 * code is returned. 202 */ 203 uint32_t TlclSetGlobalLock(void); 204 205 /** 206 * Perform a TPM_Extend. 207 */ 208 uint32_t TlclExtend(int pcr_num, const uint8_t *in_digest, uint8_t *out_digest); 209 210 /** 211 * Get the permission bits for the NVRAM space with |index|. 212 */ 213 uint32_t TlclGetPermissions(uint32_t index, uint32_t *permissions); 214 215 /** 216 * Get the public information about the NVRAM space identified by |index|. All 217 * other parameters are filled in with the respective information. 218 * |auth_policy_size| is both an input an output parameter. It should contain 219 * the available buffer size in |auth_policy| and will be updated to indicate 220 * the size of the filled in auth policy upon return. If the buffer size is not 221 * sufficient, the return value will be TPM_E_BUFFER_SIZE. 222 */ 223 uint32_t TlclGetSpaceInfo(uint32_t index, uint32_t *attributes, uint32_t *size, 224 void* auth_policy, uint32_t* auth_policy_size); 225 226 /** 227 * Get the entire set of permanent flags. 228 */ 229 uint32_t TlclGetPermanentFlags(TPM_PERMANENT_FLAGS *pflags); 230 231 /** 232 * Get the entire set of volatile (ST_CLEAR) flags. 233 */ 234 uint32_t TlclGetSTClearFlags(TPM_STCLEAR_FLAGS *pflags); 235 236 /** 237 * Get the ownership flag. The TPM error code is returned. 238 */ 239 uint32_t TlclGetOwnership(uint8_t *owned); 240 241 /** 242 * Request [length] bytes from TPM RNG to be stored in [data]. Actual number of 243 * bytes read is stored in [size]. The TPM error code is returned. 244 */ 245 uint32_t TlclGetRandom(uint8_t *data, uint32_t length, uint32_t *size); 246 247 /** 248 * Requests version information from the TPM. 249 * If vendor_specific_buf_size != NULL, requests also the vendor-specific 250 * variable-length part of the version: 251 * if vendor_specific_buf == NULL, determines its size and returns in 252 * *vendor_specific_buf_size; 253 * if vendor_specific_buf != NULL, fills the buffer until either the 254 * end of the vendor specific data or the end of the buffer, sets 255 * *vendor_specific_buf_size to the length of the filled data. 256 */ 257 uint32_t TlclGetVersion(uint32_t* vendor, uint64_t* firmware_version, 258 uint8_t* vendor_specific_buf, 259 size_t* vendor_specific_buf_size); 260 261 /** 262 * Issues the IFX specific FieldUpgradeInfoRequest2 TPM_FieldUpgrade subcommand 263 * and fills in [info] with results. 264 */ 265 uint32_t TlclIFXFieldUpgradeInfo(TPM_IFX_FIELDUPGRADEINFO *info); 266 267 /** 268 * Read the public area of object. Put at most [length] bytes public area 269 * into [data], and the format of [data] is TPMT_PUBLIC. The TPM error code 270 * is returned. 271 */ 272 uint32_t TlclReadPublic(uint32_t handle, uint8_t *data, uint32_t *length); 273 274 /** 275 * Allow certain Transient Objects to be made persistent or a persistent object 276 * to be evicted. If [object_handle] is a transient object handle, then 277 * [persistent_handle] is the persistent handle for the object. If 278 * [object_handle] is a persistent object handle, then it shall be the same 279 * value as [persistent_handle]. 280 */ 281 uint32_t TlclEvictControl(uint32_t auth_handle, uint32_t object_handle, 282 uint32_t persistent_handle); 283 284 /** 285 * Create a primary object under one of the primary seeds or a temporary object 286 * under TPM_RH_NULL. The command uses a TPMT_PUBLIC as a template[tmpl]] for 287 * the object to be created, and fills the result handle in [object_handle]. The 288 * TPM error code is returned. 289 */ 290 uint32_t TlclCreatePrimary(uint32_t primary_handle, const void *tmpl, 291 uint32_t tmpl_length, uint32_t *object_handle); 292 293 #ifdef CHROMEOS_ENVIRONMENT 294 295 /** 296 * Undefine the space. [index] is the index for the space. The TPM error code 297 * is returned. 298 */ 299 uint32_t TlclUndefineSpace(uint32_t index); 300 301 /** 302 * Undefine a space. For TPM 2.0, it will use platform authrorization when the 303 * space is created by TPMA_NV_PLATFORMCREATE flag, or use owner authorization 304 * secret [owner_auth] otherwise. For TPM 1.2, only avaible when physical 305 * presence is set or TPM_PERMANENT_FLAGS->nvLocked is not set. 306 * [index] is the index for the space 307 * The TPM error code is returned. 308 */ 309 uint32_t TlclUndefineSpaceEx(const uint8_t* owner_auth, 310 uint32_t owner_auth_size, 311 uint32_t index); 312 313 #ifndef TPM2_MODE 314 315 /** 316 * Read the public half of the EK. 317 */ 318 uint32_t TlclReadPubek(uint32_t* public_exponent, 319 uint8_t* modulus, 320 uint32_t* modulus_size); 321 322 /** 323 * Takes ownership of the TPM. [enc_owner_auth] and [enc_srk_auth] are the owner 324 * and SRK authorization secrets encrypted under the endorsement key. The clear 325 * text [owner_auth] needs to be passed as well for command auth. 326 */ 327 uint32_t TlclTakeOwnership(const uint8_t enc_owner_auth[TPM_RSA_2048_LEN], 328 const uint8_t enc_srk_auth[TPM_RSA_2048_LEN], 329 const uint8_t owner_auth[TPM_AUTH_DATA_LEN]); 330 331 /** 332 * Create a delegation family with the specified [family_label]. 333 */ 334 uint32_t TlclCreateDelegationFamily(uint8_t family_label); 335 336 /** 337 * Read the delegation family table. Entries are stored in [table]. The size of 338 * the family table array must be specified in [table_size]. [table_size] gets 339 * updated to indicate actual number of table entries available. 340 */ 341 uint32_t TlclReadDelegationFamilyTable(TPM_FAMILY_TABLE_ENTRY *table, 342 uint32_t* table_size); 343 344 #endif /* TPM2_MODE */ 345 #endif /* CHROMEOS_ENVIRONMENT */ 346 347 #ifdef __cplusplus 348 } 349 #endif 350 351 #endif /* VBOOT_REFERENCE_TLCL_H_ */ 352