1 /* Microsoft Reference Implementation for TPM 2.0 2 * 3 * The copyright in this software is being made available under the BSD License, 4 * included below. This software may be subject to other third party and 5 * contributor rights, including patent rights, and no such rights are granted 6 * under this license. 7 * 8 * Copyright (c) Microsoft Corporation 9 * 10 * All rights reserved. 11 * 12 * BSD License 13 * 14 * Redistribution and use in source and binary forms, with or without modification, 15 * are permitted provided that the following conditions are met: 16 * 17 * Redistributions of source code must retain the above copyright notice, this list 18 * of conditions and the following disclaimer. 19 * 20 * Redistributions in binary form must reproduce the above copyright notice, this 21 * list of conditions and the following disclaimer in the documentation and/or 22 * other materials provided with the distribution. 23 * 24 * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS ""AS IS"" 25 * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 26 * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE 27 * DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR 28 * ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES 29 * (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; 30 * LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON 31 * ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT 32 * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS 33 * SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. 34 */ 35 /*(Auto-generated) 36 * Created by TpmPrototypes; Version 3.0 July 18, 2017 37 * Date: Mar 4, 2020 Time: 02:36:44PM 38 */ 39 40 #ifndef _SESSION_FP_H_ 41 #define _SESSION_FP_H_ 42 43 //** Startup Function -- SessionStartup() 44 // This function initializes the session subsystem on TPM2_Startup(). 45 BOOL 46 SessionStartup( 47 STARTUP_TYPE type 48 ); 49 50 //*** SessionIsLoaded() 51 // This function test a session handle references a loaded session. The handle 52 // must have previously been checked to make sure that it is a valid handle for 53 // an authorization session. 54 // NOTE: A PWAP authorization does not have a session. 55 // 56 // Return Type: BOOL 57 // TRUE(1) session is loaded 58 // FALSE(0) session is not loaded 59 // 60 BOOL 61 SessionIsLoaded( 62 TPM_HANDLE handle // IN: session handle 63 ); 64 65 //*** SessionIsSaved() 66 // This function test a session handle references a saved session. The handle 67 // must have previously been checked to make sure that it is a valid handle for 68 // an authorization session. 69 // NOTE: An password authorization does not have a session. 70 // 71 // This function requires that the handle be a valid session handle. 72 // 73 // Return Type: BOOL 74 // TRUE(1) session is saved 75 // FALSE(0) session is not saved 76 // 77 BOOL 78 SessionIsSaved( 79 TPM_HANDLE handle // IN: session handle 80 ); 81 82 //*** SequenceNumberForSavedContextIsValid() 83 // This function validates that the sequence number and handle value within a 84 // saved context are valid. 85 BOOL 86 SequenceNumberForSavedContextIsValid( 87 TPMS_CONTEXT *context // IN: pointer to a context structure to be 88 // validated 89 ); 90 91 //*** SessionPCRValueIsCurrent() 92 // 93 // This function is used to check if PCR values have been updated since the 94 // last time they were checked in a policy session. 95 // 96 // This function requires the session is loaded. 97 // Return Type: BOOL 98 // TRUE(1) PCR value is current 99 // FALSE(0) PCR value is not current 100 BOOL 101 SessionPCRValueIsCurrent( 102 SESSION *session // IN: session structure 103 ); 104 105 //*** SessionGet() 106 // This function returns a pointer to the session object associated with a 107 // session handle. 108 // 109 // The function requires that the session is loaded. 110 SESSION * 111 SessionGet( 112 TPM_HANDLE handle // IN: session handle 113 ); 114 115 //*** SessionCreate() 116 // 117 // This function does the detailed work for starting an authorization session. 118 // This is done in a support routine rather than in the action code because 119 // the session management may differ in implementations. This implementation 120 // uses a fixed memory allocation to hold sessions and a fixed allocation 121 // to hold the contextID for the saved contexts. 122 // 123 // Return Type: TPM_RC 124 // TPM_RC_CONTEXT_GAP need to recycle sessions 125 // TPM_RC_SESSION_HANDLE active session space is full 126 // TPM_RC_SESSION_MEMORY loaded session space is full 127 TPM_RC 128 SessionCreate( 129 TPM_SE sessionType, // IN: the session type 130 TPMI_ALG_HASH authHash, // IN: the hash algorithm 131 TPM2B_NONCE *nonceCaller, // IN: initial nonceCaller 132 TPMT_SYM_DEF *symmetric, // IN: the symmetric algorithm 133 TPMI_DH_ENTITY bind, // IN: the bind object 134 TPM2B_DATA *seed, // IN: seed data 135 TPM_HANDLE *sessionHandle, // OUT: the session handle 136 TPM2B_NONCE *nonceTpm // OUT: the session nonce 137 ); 138 139 //*** SessionContextSave() 140 // This function is called when a session context is to be saved. The 141 // contextID of the saved session is returned. If no contextID can be 142 // assigned, then the routine returns TPM_RC_CONTEXT_GAP. 143 // If the function completes normally, the session slot will be freed. 144 // 145 // This function requires that 'handle' references a loaded session. 146 // Otherwise, it should not be called at the first place. 147 // 148 // Return Type: TPM_RC 149 // TPM_RC_CONTEXT_GAP a contextID could not be assigned 150 // TPM_RC_TOO_MANY_CONTEXTS the counter maxed out 151 // 152 TPM_RC 153 SessionContextSave( 154 TPM_HANDLE handle, // IN: session handle 155 CONTEXT_COUNTER *contextID // OUT: assigned contextID 156 ); 157 158 //*** SessionContextLoad() 159 // This function is used to load a session from saved context. The session 160 // handle must be for a saved context. 161 // 162 // If the gap is at a maximum, then the only session that can be loaded is 163 // the oldest session, otherwise TPM_RC_CONTEXT_GAP is returned. 164 /// 165 // This function requires that 'handle' references a valid saved session. 166 // 167 // Return Type: TPM_RC 168 // TPM_RC_SESSION_MEMORY no free session slots 169 // TPM_RC_CONTEXT_GAP the gap count is maximum and this 170 // is not the oldest saved context 171 // 172 TPM_RC 173 SessionContextLoad( 174 SESSION_BUF *session, // IN: session structure from saved context 175 TPM_HANDLE *handle // IN/OUT: session handle 176 ); 177 178 //*** SessionFlush() 179 // This function is used to flush a session referenced by its handle. If the 180 // session associated with 'handle' is loaded, the session array entry is 181 // marked as available. 182 // 183 // This function requires that 'handle' be a valid active session. 184 // 185 void 186 SessionFlush( 187 TPM_HANDLE handle // IN: loaded or saved session handle 188 ); 189 190 //*** SessionComputeBoundEntity() 191 // This function computes the binding value for a session. The binding value 192 // for a reserved handle is the handle itself. For all the other entities, 193 // the authValue at the time of binding is included to prevent squatting. 194 // For those values, the Name and the authValue are concatenated 195 // into the bind buffer. If they will not both fit, the will be overlapped 196 // by XORing bytes. If XOR is required, the bind value will be full. 197 void 198 SessionComputeBoundEntity( 199 TPMI_DH_ENTITY entityHandle, // IN: handle of entity 200 TPM2B_NAME *bind // OUT: binding value 201 ); 202 203 //*** SessionSetStartTime() 204 // This function is used to initialize the session timing 205 void 206 SessionSetStartTime( 207 SESSION *session // IN: the session to update 208 ); 209 210 //*** SessionResetPolicyData() 211 // This function is used to reset the policy data without changing the nonce 212 // or the start time of the session. 213 void 214 SessionResetPolicyData( 215 SESSION *session // IN: the session to reset 216 ); 217 218 //*** SessionCapGetLoaded() 219 // This function returns a list of handles of loaded session, started 220 // from input 'handle' 221 // 222 // 'Handle' must be in valid loaded session handle range, but does not 223 // have to point to a loaded session. 224 // Return Type: TPMI_YES_NO 225 // YES if there are more handles available 226 // NO all the available handles has been returned 227 TPMI_YES_NO 228 SessionCapGetLoaded( 229 TPMI_SH_POLICY handle, // IN: start handle 230 UINT32 count, // IN: count of returned handles 231 TPML_HANDLE *handleList // OUT: list of handle 232 ); 233 234 //*** SessionCapGetSaved() 235 // This function returns a list of handles for saved session, starting at 236 // 'handle'. 237 // 238 // 'Handle' must be in a valid handle range, but does not have to point to a 239 // saved session 240 // 241 // Return Type: TPMI_YES_NO 242 // YES if there are more handles available 243 // NO all the available handles has been returned 244 TPMI_YES_NO 245 SessionCapGetSaved( 246 TPMI_SH_HMAC handle, // IN: start handle 247 UINT32 count, // IN: count of returned handles 248 TPML_HANDLE *handleList // OUT: list of handle 249 ); 250 251 //*** SessionCapGetLoadedNumber() 252 // This function return the number of authorization sessions currently 253 // loaded into TPM RAM. 254 UINT32 255 SessionCapGetLoadedNumber( 256 void 257 ); 258 259 //*** SessionCapGetLoadedAvail() 260 // This function returns the number of additional authorization sessions, of 261 // any type, that could be loaded into TPM RAM. 262 // NOTE: In other implementations, this number may just be an estimate. The only 263 // requirement for the estimate is, if it is one or more, then at least one 264 // session must be loadable. 265 UINT32 266 SessionCapGetLoadedAvail( 267 void 268 ); 269 270 //*** SessionCapGetActiveNumber() 271 // This function returns the number of active authorization sessions currently 272 // being tracked by the TPM. 273 UINT32 274 SessionCapGetActiveNumber( 275 void 276 ); 277 278 //*** SessionCapGetActiveAvail() 279 // This function returns the number of additional authorization sessions, of any 280 // type, that could be created. This not the number of slots for sessions, but 281 // the number of additional sessions that the TPM is capable of tracking. 282 UINT32 283 SessionCapGetActiveAvail( 284 void 285 ); 286 287 #endif // _SESSION_FP_H_ 288