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 _OBJECT_FP_H_ 41 #define _OBJECT_FP_H_ 42 43 //*** ObjectFlush() 44 // This function marks an object slot as available. 45 // Since there is no checking of the input parameters, it should be used 46 // judiciously. 47 // Note: This could be converted to a macro. 48 void 49 ObjectFlush( 50 OBJECT *object 51 ); 52 53 //*** ObjectSetInUse() 54 // This access function sets the occupied attribute of an object slot. 55 void 56 ObjectSetInUse( 57 OBJECT *object 58 ); 59 60 //*** ObjectStartup() 61 // This function is called at TPM2_Startup() to initialize the object subsystem. 62 BOOL 63 ObjectStartup( 64 void 65 ); 66 67 //*** ObjectCleanupEvict() 68 // 69 // In this implementation, a persistent object is moved from NV into an object slot 70 // for processing. It is flushed after command execution. This function is called 71 // from ExecuteCommand(). 72 void 73 ObjectCleanupEvict( 74 void 75 ); 76 77 //*** IsObjectPresent() 78 // This function checks to see if a transient handle references a loaded 79 // object. This routine should not be called if the handle is not a 80 // transient handle. The function validates that the handle is in the 81 // implementation-dependent allowed in range for loaded transient objects. 82 // Return Type: BOOL 83 // TRUE(1) handle references a loaded object 84 // FALSE(0) handle is not an object handle, or it does not 85 // reference to a loaded object 86 BOOL 87 IsObjectPresent( 88 TPMI_DH_OBJECT handle // IN: handle to be checked 89 ); 90 91 //*** ObjectIsSequence() 92 // This function is used to check if the object is a sequence object. This function 93 // should not be called if the handle does not reference a loaded object. 94 // Return Type: BOOL 95 // TRUE(1) object is an HMAC, hash, or event sequence object 96 // FALSE(0) object is not an HMAC, hash, or event sequence object 97 BOOL 98 ObjectIsSequence( 99 OBJECT *object // IN: handle to be checked 100 ); 101 102 //*** HandleToObject() 103 // This function is used to find the object structure associated with a handle. 104 // 105 // This function requires that 'handle' references a loaded object or a permanent 106 // handle. 107 OBJECT* 108 HandleToObject( 109 TPMI_DH_OBJECT handle // IN: handle of the object 110 ); 111 112 //*** GetQualifiedName() 113 // This function returns the Qualified Name of the object. In this implementation, 114 // the Qualified Name is computed when the object is loaded and is saved in the 115 // internal representation of the object. The alternative would be to retain the 116 // Name of the parent and compute the QN when needed. This would take the same 117 // amount of space so it is not recommended that the alternate be used. 118 // 119 // This function requires that 'handle' references a loaded object. 120 void 121 GetQualifiedName( 122 TPMI_DH_OBJECT handle, // IN: handle of the object 123 TPM2B_NAME *qualifiedName // OUT: qualified name of the object 124 ); 125 126 //*** ObjectGetHierarchy() 127 // This function returns the handle for the hierarchy of an object. 128 TPMI_RH_HIERARCHY 129 ObjectGetHierarchy( 130 OBJECT *object // IN :object 131 ); 132 133 //*** GetHierarchy() 134 // This function returns the handle of the hierarchy to which a handle belongs. 135 // This function is similar to ObjectGetHierarchy() but this routine takes 136 // a handle but ObjectGetHierarchy() takes an pointer to an object. 137 // 138 // This function requires that 'handle' references a loaded object. 139 TPMI_RH_HIERARCHY 140 GetHierarchy( 141 TPMI_DH_OBJECT handle // IN :object handle 142 ); 143 144 //*** FindEmptyObjectSlot() 145 // This function finds an open object slot, if any. It will clear the attributes 146 // but will not set the occupied attribute. This is so that a slot may be used 147 // and discarded if everything does not go as planned. 148 // Return Type: OBJECT * 149 // NULL no open slot found 150 // != NULL pointer to available slot 151 OBJECT * 152 FindEmptyObjectSlot( 153 TPMI_DH_OBJECT *handle // OUT: (optional) 154 ); 155 156 //*** ObjectAllocateSlot() 157 // This function is used to allocate a slot in internal object array. 158 OBJECT * 159 ObjectAllocateSlot( 160 TPMI_DH_OBJECT *handle // OUT: handle of allocated object 161 ); 162 163 //*** ObjectSetLoadedAttributes() 164 // This function sets the internal attributes for a loaded object. It is called to 165 // finalize the OBJECT attributes (not the TPMA_OBJECT attributes) for a loaded 166 // object. 167 void 168 ObjectSetLoadedAttributes( 169 OBJECT *object, // IN: object attributes to finalize 170 TPM_HANDLE parentHandle // IN: the parent handle 171 ); 172 173 //*** ObjectLoad() 174 // Common function to load an object. A loaded object has its public area validated 175 // (unless its 'nameAlg' is TPM_ALG_NULL). If a sensitive part is loaded, it is 176 // verified to be correct and if both public and sensitive parts are loaded, then 177 // the cryptographic binding between the objects is validated. This function does 178 // not cause the allocated slot to be marked as in use. 179 TPM_RC 180 ObjectLoad( 181 OBJECT *object, // IN: pointer to object slot 182 // object 183 OBJECT *parent, // IN: (optional) the parent object 184 TPMT_PUBLIC *publicArea, // IN: public area to be installed in the object 185 TPMT_SENSITIVE *sensitive, // IN: (optional) sensitive area to be 186 // installed in the object 187 TPM_RC blamePublic, // IN: parameter number to associate with the 188 // publicArea errors 189 TPM_RC blameSensitive,// IN: parameter number to associate with the 190 // sensitive area errors 191 TPM2B_NAME *name // IN: (optional) 192 ); 193 194 #if CC_HMAC_Start || CC_MAC_Start 195 //*** ObjectCreateHMACSequence() 196 // This function creates an internal HMAC sequence object. 197 // Return Type: TPM_RC 198 // TPM_RC_OBJECT_MEMORY if there is no free slot for an object 199 TPM_RC 200 ObjectCreateHMACSequence( 201 TPMI_ALG_HASH hashAlg, // IN: hash algorithm 202 OBJECT *keyObject, // IN: the object containing the HMAC key 203 TPM2B_AUTH *auth, // IN: authValue 204 TPMI_DH_OBJECT *newHandle // OUT: HMAC sequence object handle 205 ); 206 #endif 207 208 //*** ObjectCreateHashSequence() 209 // This function creates a hash sequence object. 210 // Return Type: TPM_RC 211 // TPM_RC_OBJECT_MEMORY if there is no free slot for an object 212 TPM_RC 213 ObjectCreateHashSequence( 214 TPMI_ALG_HASH hashAlg, // IN: hash algorithm 215 TPM2B_AUTH *auth, // IN: authValue 216 TPMI_DH_OBJECT *newHandle // OUT: sequence object handle 217 ); 218 219 //*** ObjectCreateEventSequence() 220 // This function creates an event sequence object. 221 // Return Type: TPM_RC 222 // TPM_RC_OBJECT_MEMORY if there is no free slot for an object 223 TPM_RC 224 ObjectCreateEventSequence( 225 TPM2B_AUTH *auth, // IN: authValue 226 TPMI_DH_OBJECT *newHandle // OUT: sequence object handle 227 ); 228 229 //*** ObjectTerminateEvent() 230 // This function is called to close out the event sequence and clean up the hash 231 // context states. 232 void 233 ObjectTerminateEvent( 234 void 235 ); 236 237 //*** ObjectContextLoad() 238 // This function loads an object from a saved object context. 239 // Return Type: OBJECT * 240 // NULL if there is no free slot for an object 241 // != NULL points to the loaded object 242 OBJECT * 243 ObjectContextLoad( 244 ANY_OBJECT_BUFFER *object, // IN: pointer to object structure in saved 245 // context 246 TPMI_DH_OBJECT *handle // OUT: object handle 247 ); 248 249 //*** FlushObject() 250 // This function frees an object slot. 251 // 252 // This function requires that the object is loaded. 253 void 254 FlushObject( 255 TPMI_DH_OBJECT handle // IN: handle to be freed 256 ); 257 258 //*** ObjectFlushHierarchy() 259 // This function is called to flush all the loaded transient objects associated 260 // with a hierarchy when the hierarchy is disabled. 261 void 262 ObjectFlushHierarchy( 263 TPMI_RH_HIERARCHY hierarchy // IN: hierarchy to be flush 264 ); 265 266 //*** ObjectLoadEvict() 267 // This function loads a persistent object into a transient object slot. 268 // 269 // This function requires that 'handle' is associated with a persistent object. 270 // Return Type: TPM_RC 271 // TPM_RC_HANDLE the persistent object does not exist 272 // or the associated hierarchy is disabled. 273 // TPM_RC_OBJECT_MEMORY no object slot 274 TPM_RC 275 ObjectLoadEvict( 276 TPM_HANDLE *handle, // IN:OUT: evict object handle. If success, it 277 // will be replace by the loaded object handle 278 COMMAND_INDEX commandIndex // IN: the command being processed 279 ); 280 281 //*** ObjectComputeName() 282 // This does the name computation from a public area (can be marshaled or not). 283 TPM2B_NAME * 284 ObjectComputeName( 285 UINT32 size, // IN: the size of the area to digest 286 BYTE *publicArea, // IN: the public area to digest 287 TPM_ALG_ID nameAlg, // IN: the hash algorithm to use 288 TPM2B_NAME *name // OUT: Computed name 289 ); 290 291 //*** PublicMarshalAndComputeName() 292 // This function computes the Name of an object from its public area. 293 TPM2B_NAME * 294 PublicMarshalAndComputeName( 295 TPMT_PUBLIC *publicArea, // IN: public area of an object 296 TPM2B_NAME *name // OUT: name of the object 297 ); 298 299 //*** ComputeQualifiedName() 300 // This function computes the qualified name of an object. 301 void 302 ComputeQualifiedName( 303 TPM_HANDLE parentHandle, // IN: parent's handle 304 TPM_ALG_ID nameAlg, // IN: name hash 305 TPM2B_NAME *name, // IN: name of the object 306 TPM2B_NAME *qualifiedName // OUT: qualified name of the object 307 ); 308 309 //*** ObjectIsStorage() 310 // This function determines if an object has the attributes associated 311 // with a parent. A parent is an asymmetric or symmetric block cipher key 312 // that has its 'restricted' and 'decrypt' attributes SET, and 'sign' CLEAR. 313 // Return Type: BOOL 314 // TRUE(1) object is a storage key 315 // FALSE(0) object is not a storage key 316 BOOL 317 ObjectIsStorage( 318 TPMI_DH_OBJECT handle // IN: object handle 319 ); 320 321 //*** ObjectCapGetLoaded() 322 // This function returns a a list of handles of loaded object, starting from 323 // 'handle'. 'Handle' must be in the range of valid transient object handles, 324 // but does not have to be the handle of a loaded transient object. 325 // Return Type: TPMI_YES_NO 326 // YES if there are more handles available 327 // NO all the available handles has been returned 328 TPMI_YES_NO 329 ObjectCapGetLoaded( 330 TPMI_DH_OBJECT handle, // IN: start handle 331 UINT32 count, // IN: count of returned handles 332 TPML_HANDLE *handleList // OUT: list of handle 333 ); 334 335 //*** ObjectCapGetTransientAvail() 336 // This function returns an estimate of the number of additional transient 337 // objects that could be loaded into the TPM. 338 UINT32 339 ObjectCapGetTransientAvail( 340 void 341 ); 342 343 //*** ObjectGetPublicAttributes() 344 // Returns the attributes associated with an object handles. 345 TPMA_OBJECT 346 ObjectGetPublicAttributes( 347 TPM_HANDLE handle 348 ); 349 350 OBJECT_ATTRIBUTES 351 ObjectGetProperties( 352 TPM_HANDLE handle 353 ); 354 355 #endif // _OBJECT_FP_H_ 356