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 45 extern "C" { 46 #endif 47 48 struct __TEE_SEServiceHandle; 49 struct __TEE_SEReaderHandle; 50 struct __TEE_SESessionHandle; 51 struct __TEE_SEChannelHandle; 52 53 typedef struct __TEE_SEServiceHandle *TEE_SEServiceHandle; 54 typedef struct __TEE_SEReaderHandle *TEE_SEReaderHandle; 55 typedef struct __TEE_SESessionHandle *TEE_SESessionHandle; 56 typedef 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 */ 78 typedef 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 */ 92 typedef 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 */ 104 typedef 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 111 typedef 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 */ 123 typedef 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 */ 151 typedef 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 */ 163 typedef 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 */ 176 typedef 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 */ 188 typedef 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 */ 213 TEE_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 */ 223 void 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 */ 240 TEE_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 */ 252 void 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 */ 271 TEE_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 */ 287 TEE_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 */ 297 void 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 */ 313 TEE_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 */ 327 TEE_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 */ 337 void 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 */ 347 void 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 */ 365 TEE_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 */ 384 TEE_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 */ 395 void 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 */ 409 TEE_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 */ 425 TEE_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 */ 445 TEE_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 */ 466 TEE_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 */ 479 void 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 */ 493 TEE_Result TEE_SEChannelGetID(TEE_SEChannelHandle se_channel_handle, uint8_t *channel_id); 494 #ifdef __cplusplus 495 } 496 #endif 497 /** @} */ 498 #endif