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