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_PROPERTY_API_H
17#define TEE_PROPERTY_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_property_api.h
32 *
33 * @brief Reference of TEE object api definitions.
34 *
35 * @library NA
36 * @kit TEEKit
37 * @syscap SystemCapability.Tee.TeeClient
38 * @since 12
39 * @version 1.0
40 */
41
42#include "tee_defines.h"
43
44#ifdef __cplusplus
45extern "C" {
46#endif
47/**
48 * The definitions below are defined by Global Platform or Platform SDK released previously
49 * for compatibility.
50 * Do not make any change to the content below.
51 */
52
53/**
54 * @brief Enumerates the types of the property set.
55 *
56 * @since 12
57 */
58typedef enum {
59    TEE_PROPSET_UNKNOW             = 0,
60    TEE_PROPSET_TEE_IMPLEMENTATION = 0xFFFFFFFD,
61    TEE_PROPSET_CURRENT_CLIENT     = 0xFFFFFFFE,
62    TEE_PROPSET_CURRENT_TA         = 0xFFFFFFFF,
63} Pseudo_PropSetHandle;
64
65typedef uint32_t TEE_PropSetHandle;
66
67/**
68 * @brief Obtains a property from a property set and converts its value into a printable string.
69 *
70 *
71 * @param propsetOrEnumerator Indicates one of the TEE_PROPSET_XXX pseudo-handles or a handle on a property enumerator.
72 * @param name Indicates the pointer to the zero-terminated string containing the name of the property to obtain.
73 * @param valueBuffer Indicates the pointer to the buffer for holding the property value obtained.
74 * @param valueBufferLen Indicates the pointer to the buffer length.
75 *
76 * @return Returns <b>TEE_SUCCESS</b> if the operation is successful.
77 * @return Returns <b>TEE_ERROR_ITEM_NOT_FOUND</b> if the target property cannot be obtained.
78 * @return Returns <b>TEE_ERROR_SHORT_BUFFER</b> if the value buffer is too small to hold the property value obtained.
79 *
80 * @since 12
81 * @version 1.0
82 */
83TEE_Result TEE_GetPropertyAsString(TEE_PropSetHandle propsetOrEnumerator, const char *name, char *valueBuffer,
84                                   size_t *valueBufferLen);
85
86/**
87 * @brief Obtains a property from a property set and converts its value into a Boolean value.
88 *
89 * @param propsetOrEnumerator Indicates one of the TEE_PROPSET_XXX pseudo-handles or a handle on a property enumerator.
90 * @param name Indicates the pointer to the zero-terminated string containing the name of the property to obtain.
91 * @param value Indicates the pointer to the variable that holds the property value obtained.
92 *
93 * @return Returns <b>TEE_SUCCESS</b> if the operation is successful.
94 * @return Returns <b>TEE_ERROR_ITEM_NOT_FOUND</b> if the target property cannot be obtained.
95 *
96 * @since 12
97 * @version 1.0
98 */
99TEE_Result TEE_GetPropertyAsBool(TEE_PropSetHandle propsetOrEnumerator, const char *name, bool *value);
100
101/**
102 * @brief Obtains a property from a property set and converts its value into a 32-bit unsigned integer.
103 *
104 * @param propsetOrEnumerator Indicates one of the TEE_PROPSET_XXX pseudo-handles or a handle on a property enumerator.
105 * @param name Indicates the pointer to the zero-terminated string containing the name of the property to obtain.
106 * @param value Indicates the pointer to the variable that holds the property value obtained.
107 *
108 * @return Returns <b>TEE_SUCCESS</b> if the operation is successful.
109 * @return Returns <b>TEE_ERROR_ITEM_NOT_FOUND</b> if the target property cannot be obtained.
110 *
111 * @since 12
112 * @version 1.0
113 */
114TEE_Result TEE_GetPropertyAsU32(TEE_PropSetHandle propsetOrEnumerator, const char *name, uint32_t *value);
115
116#if defined(API_LEVEL) && (API_LEVEL >= API_LEVEL1_2)
117/**
118 * @brief Obtains a property from a property set and converts its value into a 64-bit unsigned integer.
119 *
120 * @param propsetOrEnumerator Indicates one of the TEE_PROPSET_XXX pseudo-handles or a handle on a property enumerator.
121 * @param name Indicates the pointer to the zero-terminated string containing the name of the property to obtain.
122 * @param value Indicates the pointer to the variable that holds the property value obtained.
123 *
124 * @return Returns <b>TEE_SUCCESS</b> if the operation is successful.
125 * @return Returns <b>TEE_ERROR_ITEM_NOT_FOUND</b> if the target property cannot be obtained.
126 *
127 * @since 12
128 * @version 1.0
129 */
130TEE_Result TEE_GetPropertyAsU64(TEE_PropSetHandle propsetOrEnumerator, const char *name, uint64_t *value);
131#endif // API_LEVEL
132
133/**
134 * @brief Obtains a property from a property set and converts its value into a binary block.
135 *
136 * @param propsetOrEnumerator Indicates one of the TEE_PROPSET_XXX pseudo-handles or a handle on a property enumerator.
137 * @param name Indicates the pointer to the zero-terminated string containing the name of the property to obtain.
138 * @param valueBuffer Indicates the pointer to the buffer for holding the property value obtained.
139 * @param valueBufferLen Indicates the pointer to the buffer length.
140 *
141 * @return Returns <b>TEE_SUCCESS</b> if the operation is successful.
142 * @return Returns <b>TEE_ERROR_ITEM_NOT_FOUND</b> if the target property cannot be obtained.
143 * @return TEE_ERROR_SHORT_BUFFER the value buffer is not large enough to hold the whole property value
144 *
145 * @since 12
146 * @version 1.0
147 */
148TEE_Result TEE_GetPropertyAsBinaryBlock(TEE_PropSetHandle propsetOrEnumerator, const char *name, void *valueBuffer,
149                                        size_t *valueBufferLen);
150
151/**
152 * @brief Obtains a property from a property set and converts its value to the <b>TEE_UUID</b> struct.
153 *
154 * @param propsetOrEnumerator Indicates one of the TEE_PROPSET_XXX pseudo-handles or a handle on a property enumerator.
155 * @param name Indicates the pointer to the zero-terminated string containing the name of the property to obtain.
156 * @param value Indicates the pointer to the variable that holds the property value obtained.
157 *
158 * @return Returns <b>TEE_SUCCESS</b> if the operation is successful.
159 * @return Returns <b>TEE_ERROR_ITEM_NOT_FOUND</b> if the target property cannot be obtained.
160 *
161 * @since 12
162 * @version 1.0
163 */
164TEE_Result TEE_GetPropertyAsUUID(TEE_PropSetHandle propsetOrEnumerator, const char *name, TEE_UUID *value);
165
166/**
167 * @brief Obtains a property from a property set and converts its value to the <b>TEE_Identity</b> struct.
168 *
169 * @param propsetOrEnumerator Indicates one of the TEE_PROPSET_XXX pseudo-handles or a handle on a property enumerator.
170 * @param name Indicates the pointer to the zero-terminated string containing the name of the property to obtain.
171 * @param value Indicates the pointer to the variable that holds the property value obtained.
172 *
173 * @return Returns <b>TEE_SUCCESS</b> if the operation is successful.
174 * @return Returns <b>TEE_ERROR_ITEM_NOT_FOUND</b> if the target property cannot be obtained.
175 *
176 * @since 12
177 * @version 1.0
178 */
179TEE_Result TEE_GetPropertyAsIdentity(TEE_PropSetHandle propsetOrEnumerator, const char *name, TEE_Identity *value);
180
181/**
182 * @brief Allocates a property enumerator object.
183 *
184 * @param enumerator Indicates the pointer to the property enumerator filled with an opaque handle.
185 *
186 * @return Returns <b>TEE_SUCCESS</b> if the operation is successful.
187 * @return Returns <b>TEE_ERROR_OUT_OF_MEMORY</b> if there is no enough resources to allocate the property enumerator.
188 *
189 * @since 12
190 * @version 1.0
191 */
192TEE_Result TEE_AllocatePropertyEnumerator(TEE_PropSetHandle *enumerator);
193
194/**
195 * @brief Releases a property enumerator object.
196 *
197 * @param enumerator Indicates the handle on the property enumerator to release.
198 *
199 * @return void
200 *
201 * @since 12
202 * @version 1.0
203 */
204void TEE_FreePropertyEnumerator(TEE_PropSetHandle enumerator);
205
206/**
207 * @brief Starts to enumerate the properties in an enumerator.
208 *
209 * @param enumerator Indicates the handle on the enumerator.
210 * @param propSet Indicates the pseudo-handle on the property set to enumerate.
211 *
212 * @return void
213 *
214 * @since 12
215 * @version 1.0
216 */
217void TEE_StartPropertyEnumerator(TEE_PropSetHandle enumerator, TEE_PropSetHandle propSet);
218
219/**
220 * @brief Resets a property enumerator immediately after allocation.
221 *
222 * @param enumerator Indicates the handle on the enumerator to reset.
223 *
224 * @return void
225 *
226 * @since 12
227 * @version 1.0
228 */
229void TEE_ResetPropertyEnumerator(TEE_PropSetHandle enumerator);
230
231/**
232 * @brief Obtains the name of this property in an enumerator.
233 *
234 * @param enumerator Indicates the handle on the enumerator.
235 * @param nameBuffer Indicates the pointer to the buffer that stores the property name obtained.
236 * @param nameBufferLen Indicates the pointer to the buffer length.
237 *
238 * @return Returns <b>TEE_SUCCESS</b> if the operation is successful.
239 * @return Returns <b>TEE_ERROR_ITEM_NOT_FOUND</b> if the property is not found because the enumerator has not started
240 * or has reached the end of the property set.
241 * @return Returns <b>TEE_ERROR_SHORT_BUFFER</b> if the buffer is too small to hold the property name.
242 *
243 * @since 12
244 * @version 1.0
245 */
246TEE_Result TEE_GetPropertyName(TEE_PropSetHandle enumerator, void *nameBuffer, size_t *nameBufferLen);
247
248/**
249 * @brief Obtains the next property in an enumerator.
250 *
251 * @param enumerator Indicates the handle on the enumerator.
252 *
253 * @return Returns <b>TEE_SUCCESS</b> if the operation is successful.
254 * @return Returns <b>TEE_ERROR_ITEM_NOT_FOUND</b> if the property is not found because the enumerator
255 * has not started or has reached the end of the property set.
256 *
257 * @since 12
258 * @version 1.0
259 */
260TEE_Result TEE_GetNextProperty(TEE_PropSetHandle enumerator);
261
262#ifdef __cplusplus
263}
264#endif
265/** @} */
266#endif