xref: /aosp_15_r20/external/ms-tpm-20-ref/TPMCmd/tpm/include/prototypes/Object_fp.h (revision 5c591343844d1f9da7da26467c4bf7efc8a7a413)
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