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_INTERNAL_SE_API_H
17#define TEE_INTERNAL_SE_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_internal_se_api.h
32 *
33 * @brief Provides APIs related to the TEE Secure Element.
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
48struct __TEE_SEServiceHandle;
49struct __TEE_SEReaderHandle;
50struct __TEE_SESessionHandle;
51struct __TEE_SEChannelHandle;
52
53typedef struct __TEE_SEServiceHandle *TEE_SEServiceHandle;
54typedef struct __TEE_SEReaderHandle *TEE_SEReaderHandle;
55typedef struct __TEE_SESessionHandle *TEE_SESessionHandle;
56typedef struct __TEE_SEChannelHandle *TEE_SEChannelHandle;
57
58#define ATR_LEN_MAX 32U
59#define AID_LEN_MIN 5U
60#define AID_LEN_MAX 16U
61
62/**
63 * @brief Defines the maximum of the logic channel.
64 *
65 * @since 12
66 */
67#define SE_LOGIC_CHANNEL_MAX 8U
68
69#define TEE_SC_TYPE_SCP03 0x01
70
71#define BYTE_LEN 8
72
73/**
74 * @brief Represents the properties of the SE reader.
75 *
76 * @since 12
77 */
78typedef struct __TEE_SEReaderProperties {
79    /** If an SE is present in the reader, the value is true. */
80    bool sePresent;
81    /** If this reader is only accessible via the TEE, the value is true. */
82    bool teeOnly;
83    /** If the response to a SELECT is available in the TEE, the value is true.*/
84    bool selectResponseEnable;
85} TEE_SEReaderProperties;
86
87/**
88 * @brief Defines the SE AID.
89 *
90 * @since 12
91 */
92typedef struct __TEE_SEAID {
93    /** The value of the applet's AID. */
94    uint8_t *buffer;
95    /** The lenght of the applet's AID. */
96    uint32_t bufferLen;
97} TEE_SEAID;
98
99/**
100 * @brief Enumerates the types of the key.
101 *
102 * @since 12
103 */
104typedef enum {
105    /** A base key acc. to SCP02. */
106    TEE_SC_BASE_KEY = 0,
107    /** A key set (key-MAC, key_ENC) acc. to SCP02, SCP03. */
108    TEE_SC_KEY_SET = 1
109} TEE_SC_KeyType;
110
111typedef struct __TEE_SC_KeySetRef {
112    /** Key-ENC (Static encryption key). */
113    TEE_ObjectHandle scKeyEncHandle;
114    /** Key-MAC (Static MAC key). */
115    TEE_ObjectHandle scKeyMacHandle;
116} TEE_SC_KeySetRef;
117
118/**
119 * @brief Enumerates the levels of the security.
120 *
121 * @since 12
122 */
123typedef enum {
124    /** Nothing will be applied. */
125    TEE_SC_NO_SECURE_MESSAGING = 0x00,
126    /** Command and response APDU not be secured. */
127    TEE_SC_AUTHENTICATE        = 0x80,
128    /** Command APDU shall be MAC protected. */
129    TEE_SC_C_MAC               = 0x01,
130    /** Response APDU shall be MAC protected. */
131    TEE_SC_R_MAC               = 0x10,
132    /** Command and response APDU shall be MAC protected. */
133    TEE_SC_CR_MAC              = 0x11,
134     /** Command APDU shall be encrypted and MAC protected. */
135    TEE_SC_C_ENC_MAC           = 0x03,
136    /** Response APDU shall be encrypted and MAC protected. */
137    TEE_SC_R_ENC_MAC           = 0x30,
138    /** Command and response APDU shall be encrypted and MAC protected. */
139    TEE_SC_CR_ENC_MAC          = 0x33,
140    /** Command APDU shall be encrypted, and the command and response APDU shall be MAC protected.*/
141    TEE_SC_C_ENC_CR_MAC        = 0x13
142} TEE_SC_SecurityLevel;
143
144#define TEE_AUTHENTICATE TEE_SC_AUTHENTICATE
145
146/**
147 * @brief Represents the reference about SC card key.
148 *
149 * @since 12
150 */
151typedef struct __TEE_SC_CardKeyRef {
152    /** The key identifier of the SC card key. */
153    uint8_t scKeyID;
154    /** The key version if the SC card key. */
155    uint8_t scKeyVersion;
156} TEE_SC_CardKeyRef;
157
158/**
159 * @brief Represents the reference about the SC device key.
160 *
161 * @since 12
162 */
163typedef struct __TEE_SC_DeviceKeyRef {
164    TEE_SC_KeyType scKeyType;
165    union {
166        TEE_ObjectHandle scBaseKeyHandle;
167        TEE_SC_KeySetRef scKeySetRef;
168    } __TEE_key;
169} TEE_SC_DeviceKeyRef;
170
171/**
172 * @brief Defines the OID of the SC.
173 *
174 * @since 12
175 */
176typedef struct __TEE_SC_OID {
177    /** The value of the OID. */
178    uint8_t *buffer;
179    /** The length of the OID. */
180    uint32_t bufferLen;
181} TEE_SC_OID;
182
183/**
184 * @brief Represents the paramaters about the SC.
185 *
186 * @since 12
187 */
188typedef struct __TEE_SC_Params {
189    /** The SC type. */
190    uint8_t scType;
191    /** The SC type defined by OID. */
192    TEE_SC_OID scOID;
193    /** The SC security level. */
194    TEE_SC_SecurityLevel scSecurityLevel;
195    /** Reference to SC card keys. */
196    TEE_SC_CardKeyRef scCardKeyRef;
197    /** Reference to SC device keys. */
198    TEE_SC_DeviceKeyRef scDeviceKeyRef;
199} TEE_SC_Params;
200
201/**
202 * @brief Open the SE service.
203 *
204 * @param se_service_handle [IN] Indicates the handle of SE service.
205 *
206 * @return Returns {@code TEE_SUCCESS} if the operation is successful.
207 *         Returns {@code TEE_ERROR_BAD_PARAMETERS} if input parameter is incorrect.
208 *         Returns {@code TEE_ERROR_ACCESS_CONFLICT} if failed to access the SE service due to conflict.
209 *
210 * @since 12
211 * @version 1.0
212 */
213TEE_Result TEE_SEServiceOpen(TEE_SEServiceHandle *se_service_handle);
214
215/**
216 * @brief Close the SE service.
217 *
218 * @param se_service_handle [IN] Indicates the handle of SE service.
219 *
220 * @since 12
221 * @version 1.0
222 */
223void TEE_SEServiceClose(TEE_SEServiceHandle se_service_handle);
224
225/**
226 * @brief Get the available readers handle of the SE service.
227 *
228 * @param se_service_handle [IN] Indicates the handle of SE service.
229 * @param se_reader_handle_list [OUT] Indicates the available readers handle list.
230 * @param se_reader_handle_list_len [OUT] Indicates the length of the handle list.
231 *
232 * @return Returns {@code TEE_SUCCESS} if the operation is successful.
233 *         Returns {@code TEE_ERROR_BAD_PARAMETERS} if input parameter is incorrect.
234 *         Returns {@code TEE_ITEM_NOT_FOUND} if cannot find the input SE service handle.
235 *         Returns {@code TEE_ERROR_SHORT_BUFFER} if the provided buffer is too small to store the readers handle.
236 *
237 * @since 12
238 * @version 1.0
239 */
240TEE_Result TEE_SEServiceGetReaders(TEE_SEServiceHandle se_service_handle, TEE_SEReaderHandle *se_reader_handle_list,
241                                   uint32_t *se_reader_handle_list_len);
242
243/**
244 * @brief Get the available readers handle of the SE service.
245 *
246 * @param se_reader_handle [IN] Indicates the SE readers handle.
247 * @param reader_properties [OUT] Indicates the reader's properties.
248 *
249 * @since 12
250 * @version 1.0
251 */
252void TEE_SEReaderGetProperties(TEE_SEReaderHandle se_reader_handle, TEE_SEReaderProperties *reader_properties);
253
254/**
255 * @brief Get the SE reader's name.
256 *
257 * @param se_reader_handle [IN] Indicates the SE readers handle.
258 * @param reader_name [OUT] Indicates the SE reader's name.
259 * @param reader_name_len [OUT] Indicates the length of the reader's name.
260 *
261 * @return Returns {@code TEE_SUCCESS} if the operation is successful.
262 *         Returns {@code TEE_ERROR_BAD_PARAMETERS} if input parameter is incorrect.
263 *         Returns {@code TEE_ITEM_NOT_FOUND} if cannot find the input SE reader handle.
264 *         Returns {@code TEE_ERROR_BAD_FORMAT} if the input se_reader_handle points to the reader illegally.
265 *         Returns {@code TEE_ERROR_SHORT_BUFFER} if the reader_name_len is too small to store the readers name.
266 *         Returns {@code TEE_ERROR_SECURITY} if the security error is detected.
267 *
268 * @since 12
269 * @version 1.0
270 */
271TEE_Result TEE_SEReaderGetName(TEE_SEReaderHandle se_reader_handle, char *reader_name, uint32_t *reader_name_len);
272
273/**
274 * @brief Open a session between the SE reader to the SE.
275 *
276 * @param se_reader_handle  Indicates the SE readers handle.
277 * @param se_session_handle Indicates the session handle.
278 *
279 * @return Returns {@code TEE_SUCCESS} if the operation is successful.
280 *         Returns {@code TEE_ERROR_BAD_PARAMETERS} if input parameter is incorrect.
281 *         Returns {@code TEE_ITEM_NOT_FOUND} if cannot find the input SE reader handle.
282 *         Returns {@code TEE_ERROR_COMMUNICATION} if communicte failed with the SE.
283 *
284 * @since 12
285 * @version 1.0
286 */
287TEE_Result TEE_SEReaderOpenSession(TEE_SEReaderHandle se_reader_handle, TEE_SESessionHandle *se_session_handle);
288
289/**
290 * @brief Close sessions between the SE reader to the SE.
291 *
292 * @param se_reader_handle  Indicates the SE readers handle.
293 *
294 * @since 12
295 * @version 1.0
296 */
297void TEE_SEReaderCloseSessions(TEE_SEReaderHandle se_reader_handle);
298
299/**
300 * @brief Get the SE ATR.
301 *
302 * @param se_session_handle  Indicates the session handle.
303 * @param atr  Indicates the SE ATR.
304 * @param atrLen  Indicates the length of ATR.
305 *
306 * @return Returns {@code TEE_SUCCESS} if the operation is successful.
307 *         Returns {@code TEE_ERROR_BAD_PARAMETERS} if input parameter is incorrect.
308 *         Returns {@code TEE_ERROR_SHORT_BUFFER} if the provided buffer is too small to store the ATR.
309 *
310 * @since 12
311 * @version 1.0
312 */
313TEE_Result TEE_SESessionGetATR(TEE_SESessionHandle se_session_handle, void *atr, uint32_t *atrLen);
314
315/**
316 * @brief Check whether the session is closed.
317 *
318 * @param se_session_handle  Indicates the session handle.
319 *
320 * @return Returns {@code TEE_SUCCESS} if the session is closed or the input handle is invalid.
321 *         Returns {@code TEE_ERROR_COMMUNICATION} if session state is invalid.
322 *         Returns {@code TEE_ERROR_BAD_STATE} if the session is opened.
323 *
324 * @since 12
325 * @version 1.0
326 */
327TEE_Result TEE_SESessionIsClosed(TEE_SESessionHandle se_session_handle);
328
329/**
330 * @brief Close the SE session.
331 *
332 * @param se_session_handle  Indicates the session handle.
333 *
334 * @since 12
335 * @version 1.0
336 */
337void TEE_SESessionClose(TEE_SESessionHandle se_session_handle);
338
339/**
340 * @brief Close all channels which pointed to by the SE session.
341 *
342 * @param se_session_handle  Indicates the session handle.
343 *
344 * @since 12
345 * @version 1.0
346 */
347void TEE_SESessionCloseChannels(TEE_SESessionHandle se_session_handle);
348
349/**
350 * @brief Open a basic channel which pointed to by the SE session.
351 *
352 * @param se_session_handle  Indicates the session handle.
353 * @param se_aid  Indicates the SE AID.
354 * @param se_channel_handle  Indicates the SE channel handle.
355 *
356 * @return Returns {@code TEE_SUCCESS} if the operation is successful.
357 *         Returns {@code TEE_ERROR_BAD_STATE} if the session is closed.
358 *         Returns {@code TEE_ERROR_BAD_PARAMETERS} if input parameter is incorrect.
359 *         Returns {@code TEE_ITEM_NOT_FOUND} if cannot find the input SE reader handle.
360 *         Returns other when SE responding to the abnormal status word.
361 *
362 * @since 12
363 * @version 1.0
364 */
365TEE_Result TEE_SESessionOpenBasicChannel(TEE_SESessionHandle se_session_handle, TEE_SEAID *se_aid,
366                                         TEE_SEChannelHandle *se_channel_handle);
367
368/**
369 * @brief Open a logical channel which pointed to by the SE session.
370 *
371 * @param se_session_handle  Indicates the session handle.
372 * @param se_aid  Indicates the SE AID.
373 * @param se_channel_handle  Indicates the SE channel handle.
374 *
375 * @return Returns {@code TEE_SUCCESS} if the operation is successful.
376 *         Returns {@code TEE_ERROR_BAD_STATE} if the session is closed.
377 *         Returns {@code TEE_ERROR_BAD_PARAMETERS} if input parameter is incorrect.
378 *         Returns {@code TEE_ITEM_NOT_FOUND} if cannot find the input SE reader handle.
379 *         Returns other when SE responding to the abnormal status word.
380 *
381 * @since 12
382 * @version 1.0
383 */
384TEE_Result TEE_SESessionOpenLogicalChannel(TEE_SESessionHandle se_session_handle, TEE_SEAID *se_aid,
385                                           TEE_SEChannelHandle *se_channel_handle);
386
387/**
388 * @brief Close the channel which pointed to by the channel handle.
389 *
390 * @param se_channel_handle  Indicates the SE channel handle.
391 *
392 * @since 12
393 * @version 1.0
394 */
395void TEE_SEChannelClose(TEE_SEChannelHandle se_channel_handle);
396
397/**
398 * @brief Select the next SE service which pointed to by the channel handle.
399 *
400 * @param se_channel_handle  Indicates the SE channel handle.
401 *
402 * @return Returns {@code TEE_SUCCESS} if the operation is successful.
403 *         Returns {@code TEE_ERROR_BAD_PARAMETERS} if input parameter is invalid or the mode of SE is wrong.
404 *         Returns other when SE responding to the abnormal status word.
405 *
406 * @since 12
407 * @version 1.0
408 */
409TEE_Result TEE_SEChannelSelectNext(TEE_SEChannelHandle se_channel_handle);
410
411/**
412 * @brief Get the SELECT command response of SE when open the channel handle.
413 *
414 * @param se_channel_handle  Indicates the SE channel handle.
415 * @param response  Indicates the response of SE.
416 * @param response_len  Indicates the length of the response.
417 *
418 * @return Returns {@code TEE_SUCCESS} if the operation is successful.
419 *         Returns {@code TEE_ERROR_BAD_PARAMETERS} if input parameter is invalid.
420 *         Returns {@code TEE_ERROR_SHORT_BUFFER} if the provided buffer is too small to store the response.
421 *
422 * @since 12
423 * @version 1.0
424 */
425TEE_Result TEE_SEChannelGetSelectResponse(TEE_SEChannelHandle se_channel_handle, void *response,
426                                          uint32_t *response_len);
427
428/**
429 * @brief Transmit the command through the channle.
430 *
431 * @param se_channel_handle  Indicates the SE channel handle.
432 * @param command  Indicates the transmitted command.
433 * @param command_len  Indicates the length of the command.
434 * @param response  Indicates the response of SE.
435 * @param response_len  Indicates the length of the response.
436 *
437 * @return Returns {@code TEE_SUCCESS} if the operation is successful.
438 *         Returns {@code TEE_ERROR_COMMUNICATION} if length of command is less than 4.
439 *         Returns {@code TEE_ERROR_BAD_PARAMETERS} if input parameter is invalid.
440 *         Returns {@code TEE_ERROR_BAD_STATE} if the channel is closed.
441 *
442 * @since 12
443 * @version 1.0
444 */
445TEE_Result TEE_SEChannelTransmit(TEE_SEChannelHandle se_channel_handle, void *command, uint32_t command_len,
446                                 void *response, uint32_t *response_len);
447
448/**
449 * @brief Open a SE secure channel based on the input channel handle.
450 * Thereafter, when the {@code TEE_SEChannelTransmit} is called, all APDUs(ENC/MAC protected) transmitted based on
451 * the handle are automatically protected based on the defined secure channel parameter options.
452 * Currently, only SCP03 is supported.
453 *
454 * @param se_channel_handle  Indicates the SE channel handle.
455 * @param sc_params  Indicates the parameter reference for the secure channel protocol.
456 *
457 * @return Returns {@code TEE_SUCCESS} if the operation is successful.
458 *         Returns {@code TEE_ERROR_COMMUNICATION} if communicate failed with the SE.
459 *         Returns {@code TEE_ERROR_BAD_PARAMETERS} if input parameter is invalid or the mode of SE is wrong.
460 *         Returns {@code TEE_ERROR_NOT_SUPPORTED} if the parameter of the sc_params is not supported
461 *         Returns {@code TEE_ERROR_MAC_INVALID} if the verification failed.
462 *
463 * @since 12
464 * @version 1.0
465 */
466TEE_Result TEE_SESecureChannelOpen(TEE_SEChannelHandle se_channel_handle, TEE_SC_Params *sc_params);
467
468/**
469 * @brief Close the SE secure channel based on the input channel handle.
470 * The channel, which pointed to by the input channel handle, is not closed.
471 * It can be used for insecure communication, but the APDU that calls {@code TEE_SEChannelTransmit}
472 * transmission is not secure.
473 *
474 * @param se_channel_handle  Indicates the SE channel handle.
475 *
476 * @since 12
477 * @version 1.0
478 */
479void TEE_SESecureChannelClose(TEE_SEChannelHandle se_channel_handle);
480
481/**
482 * @brief Get the channel Id which pointed to by the input channel handle.
483 *
484 * @param se_channel_handle  Indicates the SE channel handle.
485 * @param channel_id  Indicates the SE channel Id.
486 *
487 * @return Returns {@code TEE_SUCCESS} if the operation is successful.
488 *         Returns {@code TEE_ERROR_BAD_PARAMETERS} if input parameter is invalid.
489 *
490 * @since 12
491 * @version 1.0
492 */
493TEE_Result TEE_SEChannelGetID(TEE_SEChannelHandle se_channel_handle, uint8_t *channel_id);
494#ifdef __cplusplus
495}
496#endif
497/** @} */
498#endif