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 /* 7 * TPM Lightweight Command Library. 8 * 9 * A low-level library for interfacing to TPM hardware or an emulator. 10 */ 11 12 #ifndef TPM_LITE_TLCL_H_ 13 #define TPM_LITE_TLCL_H_ 14 #include <stdint.h> 15 16 #include "tss_constants.h" 17 18 /*****************************************************************************/ 19 /* Functions implemented in tlcl.c */ 20 21 /** 22 * Call this first. Returns 0 if success, nonzero if error. 23 */ 24 uint32_t TlclLibInit(void); 25 26 /** 27 * Call this on shutdown. Returns 0 if success, nonzero if error. 28 */ 29 uint32_t TlclLibClose(void); 30 31 /* Low-level operations */ 32 33 /** 34 * Perform a raw TPM request/response transaction. 35 */ 36 uint32_t TlclSendReceive(const uint8_t *request, uint8_t *response, 37 int max_length); 38 39 /** 40 * Return the size of a TPM request or response packet. 41 */ 42 int TlclPacketSize(const uint8_t *packet); 43 44 /* Commands */ 45 46 /** 47 * Send a TPM_Startup(ST_CLEAR). The TPM error code is returned (0 for 48 * success). 49 */ 50 uint32_t TlclStartup(void); 51 52 /** 53 * Save the TPM state. Normally done by the kernel before a suspend, included 54 * here for tests. The TPM error code is returned (0 for success). 55 */ 56 uint32_t TlclSaveState(void); 57 58 /** 59 * Resume by sending a TPM_Startup(ST_STATE). The TPM error code is returned 60 * (0 for success). 61 */ 62 uint32_t TlclResume(void); 63 64 /** 65 * Run the self test. 66 * 67 * Note---this is synchronous. To run this in parallel with other firmware, 68 * use ContinueSelfTest(). The TPM error code is returned. 69 */ 70 uint32_t TlclSelfTestFull(void); 71 72 /** 73 * Run the self test in the background. 74 */ 75 uint32_t TlclContinueSelfTest(void); 76 77 /** 78 * Define a space with permission [perm]. [index] is the index for the space, 79 * [size] the usable data size. The TPM error code is returned. 80 */ 81 uint32_t TlclDefineSpace(uint32_t index, uint32_t perm, uint32_t size); 82 83 /** 84 * Write [length] bytes of [data] to space at [index]. The TPM error code is 85 * returned. 86 */ 87 uint32_t TlclWrite(uint32_t index, const void *data, uint32_t length); 88 89 /** 90 * Read [length] bytes from space at [index] into [data]. The TPM error code 91 * is returned. 92 */ 93 uint32_t TlclRead(uint32_t index, void *data, uint32_t length); 94 95 /** 96 * Read PCR at [index] into [data]. [length] must be TPM_PCR_DIGEST or 97 * larger. The TPM error code is returned. 98 */ 99 uint32_t TlclPCRRead(uint32_t index, void *data, uint32_t length); 100 101 /** 102 * Write-lock space at [index]. The TPM error code is returned. 103 */ 104 uint32_t TlclWriteLock(uint32_t index); 105 106 /** 107 * Read-lock space at [index]. The TPM error code is returned. 108 */ 109 uint32_t TlclReadLock(uint32_t index); 110 111 /** 112 * Assert physical presence in software. The TPM error code is returned. 113 */ 114 uint32_t TlclAssertPhysicalPresence(void); 115 116 /** 117 * Enable the physical presence command. The TPM error code is returned. 118 */ 119 uint32_t TlclPhysicalPresenceCMDEnable(void); 120 121 /** 122 * Finalize the physical presence settings: sofware PP is enabled, hardware PP 123 * is disabled, and the lifetime lock is set. The TPM error code is returned. 124 */ 125 uint32_t TlclFinalizePhysicalPresence(void); 126 127 uint32_t TlclAssertPhysicalPresenceResult(void); 128 129 /** 130 * Turn off physical presence and locks it off until next reboot. The TPM 131 * error code is returned. 132 */ 133 uint32_t TlclLockPhysicalPresence(void); 134 135 /** 136 * Set the nvLocked bit. The TPM error code is returned. 137 */ 138 uint32_t TlclSetNvLocked(void); 139 140 /** 141 * Return 1 if the TPM is owned, 0 otherwise. 142 */ 143 int TlclIsOwned(void); 144 145 /** 146 * Issue a ForceClear. The TPM error code is returned. 147 */ 148 uint32_t TlclForceClear(void); 149 150 /** 151 * Issue a PhysicalEnable. The TPM error code is returned. 152 */ 153 uint32_t TlclSetEnable(void); 154 155 /** 156 * Issue a PhysicalDisable. The TPM error code is returned. 157 */ 158 uint32_t TlclClearEnable(void); 159 160 /** 161 * Issue a SetDeactivated. Pass 0 to activate. Returns result code. 162 */ 163 uint32_t TlclSetDeactivated(uint8_t flag); 164 165 /** 166 * Get flags of interest. Pointers for flags you aren't interested in may 167 * be NULL. The TPM error code is returned. 168 */ 169 uint32_t TlclGetFlags(uint8_t *disable, uint8_t *deactivated, 170 uint8_t *nvlocked); 171 172 /** 173 * Set the bGlobalLock flag, which only a reboot can clear. The TPM error 174 * code is returned. 175 */ 176 uint32_t TlclSetGlobalLock(void); 177 178 /** 179 * Perform a TPM_Extend. 180 */ 181 uint32_t TlclExtend(int pcr_num, const uint8_t *in_digest, uint8_t *out_digest); 182 183 /** 184 * Get the permission bits for the NVRAM space with |index|. 185 */ 186 uint32_t TlclGetPermissions(uint32_t index, uint32_t *permissions); 187 188 /** 189 * Get the entire set of permanent flags. 190 */ 191 uint32_t TlclGetPermanentFlags(TPM_PERMANENT_FLAGS *pflags); 192 193 /** 194 * Get the entire set of volatile (ST_CLEAR) flags. 195 */ 196 uint32_t TlclGetSTClearFlags(TPM_STCLEAR_FLAGS *pflags); 197 198 /** 199 * Get the ownership flag. The TPM error code is returned. 200 */ 201 uint32_t TlclGetOwnership(uint8_t *owned); 202 203 /** 204 * Request [length] bytes from TPM RNG to be stored in [data]. Actual number of 205 * bytes read is stored in [size]. The TPM error code is returned. 206 */ 207 uint32_t TlclGetRandom(uint8_t *data, uint32_t length, uint32_t *size); 208 209 #endif /* TPM_LITE_TLCL_H_ */ 210