• Home
  • Line#
  • Scopes#
  • Navigate#
  • Raw
  • Download
1 /*
2  * Copyright (c) 2024 Huawei Device Co., Ltd.
3  * Licensed under the Apache License, Version 2.0 (the "License");
4  * you may not use this file except in compliance with the License.
5  * You may obtain a copy of the License at
6  *
7  *    http://www.apache.org/licenses/LICENSE-2.0
8  *
9  * Unless required by applicable law or agreed to in writing, software
10  * distributed under the License is distributed on an "AS IS" BASIS,
11  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
12  * See the License for the specific language governing permissions and
13  * limitations under the License.
14  */
15 
16 #ifndef __TEE_OBJECT_API_H
17 #define __TEE_OBJECT_API_H
18 
19 /**
20  * @addtogroup TeeTrusted
21  * @{
22  *
23  * @brief TEE(Trusted Excution Environment) API.
24  * Provides security capability APIs such as trusted storage, encryption and decryption,
25  * and trusted time for trusted application development.
26  *
27  * @since 12
28  */
29 
30 /**
31  * @file tee_object_api.h
32  *
33  * @brief Provides trusted storage APIs.
34  *
35  * You can use these APIs to implement trusted storage features.
36  *
37  * @library NA
38  * @kit TEE Kit
39  * @syscap SystemCapability.Tee.TeeClient
40  * @since 12
41  * @version 1.0
42  */
43 
44 #include "tee_defines.h"
45 
46 #ifdef __cplusplus
47 extern "C" {
48 #endif
49 
50 /**
51  * @brief Defines <b>HANDLE_NULL</b>, which is used to denote the absence of a handle.
52  *
53  * @since 12
54  */
55 #define TEE_HANDLE_NULL 0x00000000
56 
57 /**
58  * @brief Enumerates the usages of the key of the <b>TEE_ObjectHandle</b>.
59  *
60  * @since 12
61  */
62 enum Usage_Constants {
63     /** The object's key is extractable. */
64     TEE_USAGE_EXTRACTABLE = 0x00000001,
65     /** Used for encryption. */
66     TEE_USAGE_ENCRYPT     = 0x00000002,
67     /** Used for decryption. */
68     TEE_USAGE_DECRYPT     = 0x00000004,
69     /** Used for hash calculation. */
70     TEE_USAGE_MAC         = 0x00000008,
71     /** Used for creating a signature. */
72     TEE_USAGE_SIGN        = 0x00000010,
73     /** Used for signature verification. */
74     TEE_USAGE_VERIFY      = 0x00000020,
75     /** Used for key derivation. */
76     TEE_USAGE_DERIVE      = 0x00000040,
77     /** Used for object initialization, with all permissions assigned by default. */
78     TEE_USAGE_DEFAULT     = 0xFFFFFFFF,
79 };
80 
81 /**
82  * @brief Defines information about the object pointed to by the flag of the <b>TEE_ObjectHandle</b>,
83  * for example, whether the object is a persistent object or is initialized.
84  *
85  * @since 12
86  */
87 enum Handle_Flag_Constants {
88     /** The object is a persistent object. */
89     TEE_HANDLE_FLAG_PERSISTENT      = 0x00010000,
90     /** The object is initialized. */
91     TEE_HANDLE_FLAG_INITIALIZED     = 0x00020000,
92     /** Reserved */
93     TEE_HANDLE_FLAG_KEY_SET         = 0x00040000,
94     /** Reserved */
95     TEE_HANDLE_FLAG_EXPECT_TWO_KEYS = 0x00080000,
96 };
97 
98 /**
99  * @brief Defines a value attribute identifier flag.
100  *
101  * @since 12
102  */
103 #define TEE_ATTR_FLAG_VALUE  0x20000000
104 
105 /**
106  * @brief Defines a public attribute identifier flag.
107  *
108  * @since 12
109  */
110 #define TEE_ATTR_FLAG_PUBLIC 0x10000000
111 
112 /**
113  * @brief Check whether the attribute is a buffer.
114  *
115  * @since 12
116  */
117 #define TEE_ATTR_IS_BUFFER(attribute_id) ((((attribute_id) << 2) >> 31) == 0)
118 
119 /**
120  * @brief Check whether the attribute is a value.
121  *
122  * @since 12
123  */
124 #define TEE_ATTR_IS_VALUE(attribute_id)  ((((attribute_id) << 2) >> 31) == 1)
125 
126 /**
127  * @brief Check whether the attribute is protected.
128  *
129  * @since 12
130  */
131 #define TEE_ATTR_IS_PROTECTED(attribute_id) ((((attribute_id) << 3) >> 31) == 0)
132 
133 /**
134  * @brief Check whether the attribute is public.
135  *
136  * @since 12
137  */
138 #define TEE_ATTR_IS_PUBLIC(attribute_id)    ((((attribute_id) << 3) >> 31) == 1)
139 
140 /**
141  * @brief Obtains a buffer attribute from the <b>TEE_Attribute</b> struct of the object pointed
142  * to by <b>TEE_ObjectHandle</b>.
143  *
144  * The members in the <b>TEE_Attribute</b> struct must be <b>ref</b>. If the <b>TEE_Attribute</b> is private,
145  * the <b>Usage_Constants</b> of the object must include <b>TEE_USAGE_EXTRACTABLE</b>.
146  *
147  * @param object Indicates the handle of the object.
148  * @param attributeID Indicates the ID of the attribute to obtain, for example, <b>TEE_ObjectAttribute</b>.
149  * The attribute ID can also be customized.
150  * @param buffer Indicates the pointer to the buffer that stores the attribute obtained.
151  * @param size Indicates the pointer to the length of the content stored.
152  *
153  * @return Returns <b>TEE_SUCCESS</b> if the operation is successful.
154  * @return Returns <b>TEE_ERROR_ITEM_NOT_FOUND</b> if the <b>TEE_Attribute</b> cannot be found in the object
155  * or the object is not initialized.
156  * @return Returns <b>TEE_ERROR_SHORT_BUFFER</b> if the buffer is too small to store the content obtained.
157  *
158  * @since 12
159  * @version 1.0
160  */
161 TEE_Result TEE_GetObjectBufferAttribute(TEE_ObjectHandle object, uint32_t attributeID, void *buffer, size_t *size);
162 
163 /**
164  * @brief Obtains a value attribute from the <b>TEE_Attribute</b> of an object.
165  *
166  * The members of the <b>TEE_Attribute</b> struct must be values. If the <b>TEE_Attribute</b> is private,
167  * the <b>Usage_Constants</b> of the object must include <b>TEE_USAGE_EXTRACTABLE</b>.
168  *
169  * @param object Indicates the handle of the object.
170  * @param attributeID Indicates the ID of the attribute to obtain, for example, <b>TEE_ObjectAttribute</b>.
171  * The attribute ID can also be customized.
172  * @param a Indicates the pointer to the placeholder filled with the attribute field <b>a</b>.
173  * @param b Indicates the pointer to the placeholder filled with the attribute field <b>b</b>.
174  *
175  * @return Returns <b>TEE_SUCCESS</b> if the operation is successful.
176  * @return Returns <b>TEE_ERROR_ITEM_NOT_FOUND</b> if the <b>TEE_Attribute</b> cannot be found in the object
177  * or the object is not initialized.
178  * @return Returns <b>TEE_ERROR_ACCESS_DENIED</b> if <b>TEE_Attribute</b> is private
179  * but the object <b>Usage_Constants</b> does not contain the <b>TEE_USAGE_EXTRACTABLE</b> flag.
180  *
181  * @since 12
182  * @version 1.0
183  */
184 TEE_Result TEE_GetObjectValueAttribute(TEE_ObjectHandle object, uint32_t attributeID, uint32_t *a, uint32_t *b);
185 
186 /**
187  * @brief Closes a <b>TEE_ObjectHandle</b> object.
188  *
189  * The object can be persistent or transient.
190  *
191  * @param object Indicates the <b>TEE_ObjectHandle</b> object to close.
192  *
193  * @since 12
194  * @version 1.0
195  */
196 void TEE_CloseObject(TEE_ObjectHandle object);
197 
198 /**
199  * @brief Allocates an uninitialized object to store keys.
200  *
201  * <b>objectType</b> and <b>maxObjectSize</b> must be specified.
202  *
203  * @param objectType Indicates the type of the object to create. The value is <b>TEE_ObjectType</b>.
204  * @param maxObjectSize Indicates the maximum number of bytes of the object.
205  * @param object Indicates the pointer to the handle of the newly created object.
206  *
207  * @return Returns <b>TEE_SUCCESS</b> if the operation is successful.
208  * @return Returns <b>TEE_ERROR_OUT_OF_MEMORY</b> if the memory is insufficient.
209  * @return Returns <b>TEE_ERROR_NOT_SUPPORTED</b> if the object type is not supported.
210  *
211  * @since 12
212  * @version 1.0
213  */
214 TEE_Result TEE_AllocateTransientObject(uint32_t objectType, uint32_t maxObjectSize, TEE_ObjectHandle *object);
215 
216 /**
217  * @brief Releases a transient object that is previously allocated with <b>TEE_AllocateTransientObject</b>.
218  *
219  * After the function is called, the handle becomes invalid and all allocated resources are released.
220  * <b>TEE_FreeTransientObject</b> and <b>TEE_AllocateTransientObject</b> are used in pairs.
221  *
222  * @param object Indicates the <b>TEE_ObjectHandle</b> to release.
223  *
224  * @since 12
225  * @version 1.0
226  */
227 void TEE_FreeTransientObject(TEE_ObjectHandle object);
228 
229 /**
230  * @brief Resets a transient object to its initial state after allocation.
231  *
232  * You can use an allocated object, which has not been initialized or used to store a key, to store a key.
233  *
234  * @param object Indicates the <b>TEE_ObjectHandle</b> to reset.
235  *
236  * @since 12
237  * @version 1.0
238  */
239 void TEE_ResetTransientObject(TEE_ObjectHandle object);
240 
241 /**
242  * @brief Populates an uninitialized object with object attributes passed by the TA in the <b>attrs</b> parameter.
243  *
244  * The object must be uninitialized. \n
245  * The <b>attrs</b> parameter is passed by a TA.
246  *
247  * @param object Indicates the handle on a created but uninitialized object.
248  * @param attrs Indicates the pointer to an array of object attributes, which can be one or more <b>TEE_Attribute</b>s.
249  * @param attrCount Indicates the number of members in the attribute array.
250  *
251  * @return Returns <b>TEE_SUCCESS</b> if the operation is successful.
252  * @return Returns <b>TEE_ERROR_BAD_PARAMETERS</b> if an incorrect or inconsistent attribute value is detected.
253  *
254  * @since 12
255  * @version 1.0
256  */
257 TEE_Result TEE_PopulateTransientObject(TEE_ObjectHandle object, TEE_Attribute *attrs, uint32_t attrCount);
258 
259 /**
260  * @brief Initializes the <b>TEE_Attribute</b> of the buffer type.
261  *
262  * The members in the <b>TEE_Attribute</b> struct must be <b>ref</b>.
263  *
264  * @param attr Indicates the pointer to the <b>TEE_Attribute</b> initialized.
265  * @param attributeID Indicates the ID assigned to the <b>TEE_Attribute</b>.
266  * @param buffer Indicates the pointer to the buffer that stores the content to be allocated.
267  * @param length Indicates the length of the assigned value, in bytes.
268  *
269  * @since 12
270  * @version 1.0
271  */
272 void TEE_InitRefAttribute(TEE_Attribute *attr, uint32_t attributeID, void *buffer, size_t length);
273 
274 /**
275  * @brief Initializes a <b>TEE_Attribute</b>.
276  *
277  * @param attr Indicates the pointer to the <b>TEE_Attribute</b> initialized.
278  * @param attributeID Indicates the ID assigned to the <b>TEE_Attribute</b>.
279  * @param a Indicates the value to be assigned to the member <b>a</b> in the <b>TEE_Attribute</b>.
280  * @param b Indicates the value to be assigned to the member <b>b</b> in the <b>TEE_Attribute</b>.
281  *
282  * @since 12
283  * @version 1.0
284  */
285 void TEE_InitValueAttribute(TEE_Attribute *attr, uint32_t attributeID, uint32_t a, uint32_t b);
286 
287 /**
288  * @brief Generates a random key or a key pair and populates a transient key object with the generated key.
289  *
290  * @param object Indicates a transient object used to hold the generated key.
291  * @param keySize Indicates the number of bytes of the key.
292  * @param params Indicates the pointer to the parameters for key generation.
293  * @param paramCount Indicates the number of parameters required for key generation.
294  *
295  * @return Returns <b>TEE_SUCCESS</b> if the operation is successful.
296  * @return Returns <b>TEE_ERROR_BAD_PARAMETERS</b> if the type of the key generated does not match
297  * the key that can be held in the transient object.
298  *
299  * @since 12
300  * @version 1.0
301  */
302 TEE_Result TEE_GenerateKey(TEE_ObjectHandle object, uint32_t keySize, TEE_Attribute *params, uint32_t paramCount);
303 
304 /**
305  * @brief Get the information of the object data part, the total length of the data part and the current
306  * position of the data stream.
307  *
308  * @param object Indicates the handle of the object.
309  * @param pos Indicates the data stream position.
310  * @param len Indicates the data stream length.
311  *
312  * @return Returns <b>TEE_SUCCESS</b> if the operation is successful.
313  * @return Returns others if the operation is failed.
314  *
315  * @since 12
316  * @version 1.0
317  */
318 TEE_Result TEE_InfoObjectData(TEE_ObjectHandle object, uint32_t *pos, uint32_t *len);
319 
320 /**
321  * @brief Obtains <b>TEE_ObjectInfo</b>.
322  *
323  * This function obtains <b>TEE_ObjectInfo</b> and copies the obtained information to the pre-allocated space
324  * pointed to by <b>objectInfo</b>.
325  *
326  * @param object Indicates the handle of the object.
327  * @param objectInfo Indicates the pointer to the <b>TEE_ObjectInfo</b> obtained.
328  *
329  * @return Returns <b>TEE_SUCCESS</b> if the operation is successful.
330  * @return Returns <b>TEE_ERROR_CORRUPT_OBJECT</b> if the object is corrupted and the object handle will be closed.
331  * @return Returns <b>TEE_ERROR_STORAGE_NOT_AVAILABLE</b> if the object is stored
332  * in a storage area that is inaccessible currently.
333  *
334  * @since 12
335  * @version 1.0
336  */
337 TEE_Result TEE_GetObjectInfo1(TEE_ObjectHandle object, TEE_ObjectInfo *objectInfo);
338 
339 /**
340  * @brief Assigns the <b>TEE_Attribute</b> of an initialized object to an uninitialized object.
341  *
342  * This function populates an uninitialized object with <b>TEE_Attribute</b>.
343  * That is, it copies <b>TEE_Attribute</b> of <b>srcobject</b> to <b>destobject</b>.
344  * The <b>TEE_Attribute</b> types and IDs of the two objects must match.
345  *
346  * @param destObject Indicates the uninitialized object.
347  * @param srcObject Indicates the initialized object.
348  *
349  * @return Returns <b>TEE_SUCCESS</b> if the operation is successful.
350  * @return Returns <b>TEE_ERROR_CORRUPT_OBJECT</b> if the object is corrupted and the object handle will be closed.
351  * @return Returns <b>TEE_ERROR_STORAGE_NOT_AVAILABLE</b> if the object is stored
352  * in a storage area that is inaccessible currently.
353  *
354  * @since 12
355  * @version 1.0
356  */
357 TEE_Result TEE_CopyObjectAttributes1(TEE_ObjectHandle destObject, TEE_ObjectHandle srcObject);
358 
359 /**
360  * @brief Restricts the <b>objectUse</b> bit of an object.
361  *
362  * This bit determines the usage of the key in the object. The value range is <b>Usage_Constant</b>.
363  * The bit in the <b>objectUse</b> parameter can be set as follows: \n
364  * If it is set to <b>1</b>, the corresponding usage flag in the object is left unchanged. \n
365  * If it is set to <b>0</b>, the corresponding usage flag in the object is cleared. \n
366  * The newly created object contains all <b>Usage_Constant</b>, and the usage flag can be cleared only.
367  *
368  * @param object Indicates the <b>TEE_ObjectHandle</b> of the target object.
369  * @param objectUsage Indicates the new object usage.
370  *
371  * @return Returns <b>TEE_SUCCESS</b> if the operation is successful.
372  * @return Returns <b>TEE_ERROR_CORRUPT_OBJECT</b> if the object is corrupted and the object handle will be closed.
373  * @return Returns <b>TEE_ERROR_STORAGE_NOT_AVAILABLE</b> if the object is stored
374  * in a storage area that is inaccessible currently.
375  *
376  * @since 12
377  * @version 1.0
378  */
379 TEE_Result TEE_RestrictObjectUsage1(TEE_ObjectHandle object, uint32_t objectUsage);
380 #ifdef __cplusplus
381 }
382 #endif
383 /** @} */
384 #endif
385