1 /* SPDX-License-Identifier: BSD-2-Clause */ 2 /* 3 * Copyright (c) 2014, STMicroelectronics International N.V. 4 */ 5 6 /* Based on GP TEE Internal API Specification Version 0.27 */ 7 #ifndef TEE_INTERNAL_API_H 8 #define TEE_INTERNAL_API_H 9 10 #ifdef __TEE_API_COMPAT_H 11 #error "<tee_api_compat.h> must not be included before <tee_internal_api.h>" 12 #endif 13 14 #include <compiler.h> 15 #include <stddef.h> 16 #include <tee_api_defines.h> 17 #include <tee_api_types.h> 18 #include <trace.h> 19 20 /* Property access functions */ 21 22 TEE_Result TEE_GetPropertyAsString(TEE_PropSetHandle propsetOrEnumerator, 23 const char *name, char *valueBuffer, 24 uint32_t *valueBufferLen); 25 26 TEE_Result TEE_GetPropertyAsBool(TEE_PropSetHandle propsetOrEnumerator, 27 const char *name, bool *value); 28 29 TEE_Result TEE_GetPropertyAsU32(TEE_PropSetHandle propsetOrEnumerator, 30 const char *name, uint32_t *value); 31 32 TEE_Result TEE_GetPropertyAsBinaryBlock(TEE_PropSetHandle propsetOrEnumerator, 33 const char *name, void *valueBuffer, 34 uint32_t *valueBufferLen); 35 36 TEE_Result TEE_GetPropertyAsUUID(TEE_PropSetHandle propsetOrEnumerator, 37 const char *name, TEE_UUID *value); 38 39 TEE_Result TEE_GetPropertyAsIdentity(TEE_PropSetHandle propsetOrEnumerator, 40 const char *name, TEE_Identity *value); 41 42 TEE_Result TEE_AllocatePropertyEnumerator(TEE_PropSetHandle *enumerator); 43 44 void TEE_FreePropertyEnumerator(TEE_PropSetHandle enumerator); 45 46 void TEE_StartPropertyEnumerator(TEE_PropSetHandle enumerator, 47 TEE_PropSetHandle propSet); 48 49 void TEE_ResetPropertyEnumerator(TEE_PropSetHandle enumerator); 50 51 TEE_Result TEE_GetPropertyName(TEE_PropSetHandle enumerator, 52 void *nameBuffer, uint32_t *nameBufferLen); 53 54 TEE_Result TEE_GetNextProperty(TEE_PropSetHandle enumerator); 55 56 /* System API - Misc */ 57 58 void TEE_Panic(TEE_Result panicCode); 59 60 /* System API - Internal Client API */ 61 62 TEE_Result TEE_OpenTASession(const TEE_UUID *destination, 63 uint32_t cancellationRequestTimeout, 64 uint32_t paramTypes, 65 TEE_Param params[TEE_NUM_PARAMS], 66 TEE_TASessionHandle *session, 67 uint32_t *returnOrigin); 68 TEE_Result __GP11_TEE_OpenTASession(const TEE_UUID *destination, 69 uint32_t cancellationRequestTimeout, 70 uint32_t paramTypes, 71 __GP11_TEE_Param params[TEE_NUM_PARAMS], 72 TEE_TASessionHandle *session, 73 uint32_t *returnOrigin); 74 75 void TEE_CloseTASession(TEE_TASessionHandle session); 76 77 TEE_Result TEE_InvokeTACommand(TEE_TASessionHandle session, 78 uint32_t cancellationRequestTimeout, 79 uint32_t commandID, uint32_t paramTypes, 80 TEE_Param params[TEE_NUM_PARAMS], 81 uint32_t *returnOrigin); 82 TEE_Result __GP11_TEE_InvokeTACommand(TEE_TASessionHandle session, 83 uint32_t cancellationRequestTimeout, 84 uint32_t commandID, uint32_t paramTypes, 85 __GP11_TEE_Param params[TEE_NUM_PARAMS], 86 uint32_t *returnOrigin); 87 88 /* System API - Cancellations */ 89 90 bool TEE_GetCancellationFlag(void); 91 92 bool TEE_UnmaskCancellation(void); 93 94 bool TEE_MaskCancellation(void); 95 96 /* System API - Memory Management */ 97 98 TEE_Result TEE_CheckMemoryAccessRights(uint32_t accessFlags, void *buffer, 99 uint32_t size); 100 101 void TEE_SetInstanceData(const void *instanceData); 102 103 const void *TEE_GetInstanceData(void); 104 105 void *TEE_Malloc(uint32_t size, uint32_t hint); 106 107 void *TEE_Realloc(void *buffer, uint32_t newSize); 108 109 void TEE_Free(void *buffer); 110 111 void *TEE_MemMove(void *dest, const void *src, uint32_t size); 112 113 /* 114 * Note: TEE_MemCompare() has a constant-time implementation (execution time 115 * does not depend on buffer content but only on buffer size). It is the main 116 * difference with memcmp(). 117 */ 118 int32_t TEE_MemCompare(const void *buffer1, const void *buffer2, uint32_t size); 119 120 void TEE_MemFill(void *buff, uint32_t x, uint32_t size); 121 122 /* Data and Key Storage API - Generic Object Functions */ 123 124 void TEE_GetObjectInfo(TEE_ObjectHandle object, TEE_ObjectInfo *objectInfo); 125 void __GP11_TEE_GetObjectInfo(TEE_ObjectHandle object, 126 __GP11_TEE_ObjectInfo *objectInfo); 127 128 TEE_Result TEE_GetObjectInfo1(TEE_ObjectHandle object, 129 TEE_ObjectInfo *objectInfo); 130 TEE_Result __GP11_TEE_GetObjectInfo1(TEE_ObjectHandle object, 131 __GP11_TEE_ObjectInfo *objectInfo); 132 133 void TEE_RestrictObjectUsage(TEE_ObjectHandle object, uint32_t objectUsage); 134 TEE_Result TEE_RestrictObjectUsage1(TEE_ObjectHandle object, 135 uint32_t objectUsage); 136 137 TEE_Result TEE_GetObjectBufferAttribute(TEE_ObjectHandle object, 138 uint32_t attributeID, void *buffer, 139 uint32_t *size); 140 141 TEE_Result TEE_GetObjectValueAttribute(TEE_ObjectHandle object, 142 uint32_t attributeID, uint32_t *a, 143 uint32_t *b); 144 145 void TEE_CloseObject(TEE_ObjectHandle object); 146 147 /* Data and Key Storage API - Transient Object Functions */ 148 149 TEE_Result TEE_AllocateTransientObject(TEE_ObjectType objectType, 150 uint32_t maxKeySize, 151 TEE_ObjectHandle *object); 152 153 void TEE_FreeTransientObject(TEE_ObjectHandle object); 154 155 void TEE_ResetTransientObject(TEE_ObjectHandle object); 156 157 TEE_Result TEE_PopulateTransientObject(TEE_ObjectHandle object, 158 const TEE_Attribute *attrs, 159 uint32_t attrCount); 160 TEE_Result __GP11_TEE_PopulateTransientObject(TEE_ObjectHandle object, 161 const __GP11_TEE_Attribute *attrs, 162 uint32_t attrCount); 163 164 void TEE_InitRefAttribute(TEE_Attribute *attr, uint32_t attributeID, 165 const void *buffer, uint32_t length); 166 void __GP11_TEE_InitRefAttribute(__GP11_TEE_Attribute *attr, 167 uint32_t attributeID, 168 const void *buffer, uint32_t length); 169 170 void TEE_InitValueAttribute(TEE_Attribute *attr, uint32_t attributeID, 171 uint32_t a, uint32_t b); 172 void __GP11_TEE_InitValueAttribute(__GP11_TEE_Attribute *attr, 173 uint32_t attributeID, 174 uint32_t a, uint32_t b); 175 176 void TEE_CopyObjectAttributes(TEE_ObjectHandle destObject, 177 TEE_ObjectHandle srcObject); 178 179 TEE_Result TEE_CopyObjectAttributes1(TEE_ObjectHandle destObject, 180 TEE_ObjectHandle srcObject); 181 182 TEE_Result TEE_GenerateKey(TEE_ObjectHandle object, uint32_t keySize, 183 const TEE_Attribute *params, uint32_t paramCount); 184 TEE_Result __GP11_TEE_GenerateKey(TEE_ObjectHandle object, uint32_t keySize, 185 const __GP11_TEE_Attribute *params, 186 uint32_t paramCount); 187 188 /* Data and Key Storage API - Persistent Object Functions */ 189 190 TEE_Result TEE_OpenPersistentObject(uint32_t storageID, const void *objectID, 191 uint32_t objectIDLen, uint32_t flags, 192 TEE_ObjectHandle *object); 193 194 TEE_Result TEE_CreatePersistentObject(uint32_t storageID, const void *objectID, 195 uint32_t objectIDLen, uint32_t flags, 196 TEE_ObjectHandle attributes, 197 const void *initialData, 198 uint32_t initialDataLen, 199 TEE_ObjectHandle *object); 200 201 void TEE_CloseAndDeletePersistentObject(TEE_ObjectHandle object); 202 203 TEE_Result TEE_CloseAndDeletePersistentObject1(TEE_ObjectHandle object); 204 205 TEE_Result TEE_RenamePersistentObject(TEE_ObjectHandle object, 206 const void *newObjectID, 207 uint32_t newObjectIDLen); 208 209 TEE_Result TEE_AllocatePersistentObjectEnumerator(TEE_ObjectEnumHandle * 210 objectEnumerator); 211 212 void TEE_FreePersistentObjectEnumerator(TEE_ObjectEnumHandle objectEnumerator); 213 214 void TEE_ResetPersistentObjectEnumerator(TEE_ObjectEnumHandle objectEnumerator); 215 216 TEE_Result TEE_StartPersistentObjectEnumerator(TEE_ObjectEnumHandle 217 objectEnumerator, 218 uint32_t storageID); 219 220 TEE_Result TEE_GetNextPersistentObject(TEE_ObjectEnumHandle objectEnumerator, 221 TEE_ObjectInfo *objectInfo, 222 void *objectID, uint32_t *objectIDLen); 223 TEE_Result 224 __GP11_TEE_GetNextPersistentObject(TEE_ObjectEnumHandle objectEnumerator, 225 __GP11_TEE_ObjectInfo *objectInfo, 226 void *objectID, uint32_t *objectIDLen); 227 228 /* Data and Key Storage API - Data Stream Access Functions */ 229 230 TEE_Result TEE_ReadObjectData(TEE_ObjectHandle object, void *buffer, 231 uint32_t size, uint32_t *count); 232 233 TEE_Result TEE_WriteObjectData(TEE_ObjectHandle object, const void *buffer, 234 uint32_t size); 235 236 TEE_Result TEE_TruncateObjectData(TEE_ObjectHandle object, uint32_t size); 237 238 TEE_Result TEE_SeekObjectData(TEE_ObjectHandle object, int32_t offset, 239 TEE_Whence whence); 240 241 /* Cryptographic Operations API - Generic Operation Functions */ 242 243 TEE_Result TEE_AllocateOperation(TEE_OperationHandle *operation, 244 uint32_t algorithm, uint32_t mode, 245 uint32_t maxKeySize); 246 247 void TEE_FreeOperation(TEE_OperationHandle operation); 248 249 void TEE_GetOperationInfo(TEE_OperationHandle operation, 250 TEE_OperationInfo *operationInfo); 251 252 TEE_Result 253 TEE_GetOperationInfoMultiple(TEE_OperationHandle operation, 254 TEE_OperationInfoMultiple *operationInfoMultiple, 255 uint32_t *operationSize); 256 257 void TEE_ResetOperation(TEE_OperationHandle operation); 258 259 TEE_Result TEE_SetOperationKey(TEE_OperationHandle operation, 260 TEE_ObjectHandle key); 261 262 TEE_Result TEE_SetOperationKey2(TEE_OperationHandle operation, 263 TEE_ObjectHandle key1, TEE_ObjectHandle key2); 264 265 void TEE_CopyOperation(TEE_OperationHandle dstOperation, 266 TEE_OperationHandle srcOperation); 267 268 TEE_Result TEE_IsAlgorithmSupported(uint32_t algId, uint32_t element); 269 270 /* Cryptographic Operations API - Message Digest Functions */ 271 272 void TEE_DigestUpdate(TEE_OperationHandle operation, 273 const void *chunk, uint32_t chunkSize); 274 275 TEE_Result TEE_DigestDoFinal(TEE_OperationHandle operation, const void *chunk, 276 uint32_t chunkLen, void *hash, uint32_t *hashLen); 277 278 /* Cryptographic Operations API - Symmetric Cipher Functions */ 279 280 void TEE_CipherInit(TEE_OperationHandle operation, const void *IV, 281 uint32_t IVLen); 282 283 TEE_Result TEE_CipherUpdate(TEE_OperationHandle operation, const void *srcData, 284 uint32_t srcLen, void *destData, uint32_t *destLen); 285 286 TEE_Result TEE_CipherDoFinal(TEE_OperationHandle operation, 287 const void *srcData, uint32_t srcLen, 288 void *destData, uint32_t *destLen); 289 290 /* Cryptographic Operations API - MAC Functions */ 291 292 void TEE_MACInit(TEE_OperationHandle operation, const void *IV, 293 uint32_t IVLen); 294 295 void TEE_MACUpdate(TEE_OperationHandle operation, const void *chunk, 296 uint32_t chunkSize); 297 298 TEE_Result TEE_MACComputeFinal(TEE_OperationHandle operation, 299 const void *message, uint32_t messageLen, 300 void *mac, uint32_t *macLen); 301 302 TEE_Result TEE_MACCompareFinal(TEE_OperationHandle operation, 303 const void *message, uint32_t messageLen, 304 const void *mac, uint32_t macLen); 305 306 /* Cryptographic Operations API - Authenticated Encryption Functions */ 307 308 TEE_Result TEE_AEInit(TEE_OperationHandle operation, const void *nonce, 309 uint32_t nonceLen, uint32_t tagLen, uint32_t AADLen, 310 uint32_t payloadLen); 311 312 void TEE_AEUpdateAAD(TEE_OperationHandle operation, const void *AADdata, 313 uint32_t AADdataLen); 314 315 TEE_Result TEE_AEUpdate(TEE_OperationHandle operation, const void *srcData, 316 uint32_t srcLen, void *destData, uint32_t *destLen); 317 318 TEE_Result TEE_AEEncryptFinal(TEE_OperationHandle operation, 319 const void *srcData, uint32_t srcLen, 320 void *destData, uint32_t *destLen, void *tag, 321 uint32_t *tagLen); 322 323 TEE_Result TEE_AEDecryptFinal(TEE_OperationHandle operation, 324 const void *srcData, uint32_t srcLen, 325 void *destData, uint32_t *destLen, void *tag, 326 uint32_t tagLen); 327 328 /* Cryptographic Operations API - Asymmetric Functions */ 329 330 TEE_Result TEE_AsymmetricEncrypt(TEE_OperationHandle operation, 331 const TEE_Attribute *params, 332 uint32_t paramCount, const void *srcData, 333 uint32_t srcLen, void *destData, 334 uint32_t *destLen); 335 TEE_Result __GP11_TEE_AsymmetricEncrypt(TEE_OperationHandle operation, 336 const __GP11_TEE_Attribute *params, 337 uint32_t paramCount, 338 const void *srcData, uint32_t srcLen, 339 void *destData, uint32_t *destLen); 340 341 TEE_Result TEE_AsymmetricDecrypt(TEE_OperationHandle operation, 342 const TEE_Attribute *params, 343 uint32_t paramCount, const void *srcData, 344 uint32_t srcLen, void *destData, 345 uint32_t *destLen); 346 TEE_Result __GP11_TEE_AsymmetricDecrypt(TEE_OperationHandle operation, 347 const __GP11_TEE_Attribute *params, 348 uint32_t paramCount, 349 const void *srcData, uint32_t srcLen, 350 void *destData, uint32_t *destLen); 351 352 TEE_Result TEE_AsymmetricSignDigest(TEE_OperationHandle operation, 353 const TEE_Attribute *params, 354 uint32_t paramCount, const void *digest, 355 uint32_t digestLen, void *signature, 356 uint32_t *signatureLen); 357 TEE_Result __GP11_TEE_AsymmetricSignDigest(TEE_OperationHandle operation, 358 const __GP11_TEE_Attribute *params, 359 uint32_t paramCount, 360 const void *digest, 361 uint32_t digestLen, void *signature, 362 uint32_t *signatureLen); 363 364 TEE_Result TEE_AsymmetricVerifyDigest(TEE_OperationHandle operation, 365 const TEE_Attribute *params, 366 uint32_t paramCount, const void *digest, 367 uint32_t digestLen, const void *signature, 368 uint32_t signatureLen); 369 TEE_Result __GP11_TEE_AsymmetricVerifyDigest(TEE_OperationHandle operation, 370 const __GP11_TEE_Attribute *params, 371 uint32_t paramCount, 372 const void *digest, 373 uint32_t digestLen, 374 const void *signature, 375 uint32_t signatureLen); 376 377 /* Cryptographic Operations API - Key Derivation Functions */ 378 379 void TEE_DeriveKey(TEE_OperationHandle operation, 380 const TEE_Attribute *params, uint32_t paramCount, 381 TEE_ObjectHandle derivedKey); 382 void __GP11_TEE_DeriveKey(TEE_OperationHandle operation, 383 const __GP11_TEE_Attribute *params, 384 uint32_t paramCount, TEE_ObjectHandle derivedKey); 385 386 /* Cryptographic Operations API - Random Number Generation Functions */ 387 388 void TEE_GenerateRandom(void *randomBuffer, uint32_t randomBufferLen); 389 390 /* Date & Time API */ 391 392 void TEE_GetSystemTime(TEE_Time *time); 393 394 TEE_Result TEE_Wait(uint32_t timeout); 395 396 TEE_Result TEE_GetTAPersistentTime(TEE_Time *time); 397 398 TEE_Result TEE_SetTAPersistentTime(const TEE_Time *time); 399 400 void TEE_GetREETime(TEE_Time *time); 401 402 /* TEE Arithmetical API - Memory allocation and size of objects */ 403 404 uint32_t TEE_BigIntFMMSizeInU32(uint32_t modulusSizeInBits); 405 406 uint32_t TEE_BigIntFMMContextSizeInU32(uint32_t modulusSizeInBits); 407 408 /* TEE Arithmetical API - Initialization functions */ 409 410 void TEE_BigIntInit(TEE_BigInt *bigInt, uint32_t len); 411 412 void TEE_BigIntInitFMMContext(TEE_BigIntFMMContext *context, uint32_t len, 413 const TEE_BigInt *modulus); 414 415 void TEE_BigIntInitFMM(TEE_BigIntFMM *bigIntFMM, uint32_t len); 416 417 /* TEE Arithmetical API - Converter functions */ 418 419 TEE_Result TEE_BigIntConvertFromOctetString(TEE_BigInt *dest, 420 const uint8_t *buffer, 421 uint32_t bufferLen, 422 int32_t sign); 423 424 TEE_Result TEE_BigIntConvertToOctetString(uint8_t *buffer, uint32_t *bufferLen, 425 const TEE_BigInt *bigInt); 426 427 void TEE_BigIntConvertFromS32(TEE_BigInt *dest, int32_t shortVal); 428 429 TEE_Result TEE_BigIntConvertToS32(int32_t *dest, const TEE_BigInt *src); 430 431 /* TEE Arithmetical API - Logical operations */ 432 433 int32_t TEE_BigIntCmp(const TEE_BigInt *op1, const TEE_BigInt *op2); 434 435 int32_t TEE_BigIntCmpS32(const TEE_BigInt *op, int32_t shortVal); 436 437 void TEE_BigIntShiftRight(TEE_BigInt *dest, const TEE_BigInt *op, 438 size_t bits); 439 440 bool TEE_BigIntGetBit(const TEE_BigInt *src, uint32_t bitIndex); 441 442 uint32_t TEE_BigIntGetBitCount(const TEE_BigInt *src); 443 444 void TEE_BigIntAdd(TEE_BigInt *dest, const TEE_BigInt *op1, 445 const TEE_BigInt *op2); 446 447 void TEE_BigIntSub(TEE_BigInt *dest, const TEE_BigInt *op1, 448 const TEE_BigInt *op2); 449 450 void TEE_BigIntNeg(TEE_BigInt *dest, const TEE_BigInt *op); 451 452 void TEE_BigIntMul(TEE_BigInt *dest, const TEE_BigInt *op1, 453 const TEE_BigInt *op2); 454 455 void TEE_BigIntSquare(TEE_BigInt *dest, const TEE_BigInt *op); 456 457 void TEE_BigIntDiv(TEE_BigInt *dest_q, TEE_BigInt *dest_r, 458 const TEE_BigInt *op1, const TEE_BigInt *op2); 459 460 /* TEE Arithmetical API - Modular arithmetic operations */ 461 462 void TEE_BigIntMod(TEE_BigInt *dest, const TEE_BigInt *op, 463 const TEE_BigInt *n); 464 465 void TEE_BigIntAddMod(TEE_BigInt *dest, const TEE_BigInt *op1, 466 const TEE_BigInt *op2, const TEE_BigInt *n); 467 468 void TEE_BigIntSubMod(TEE_BigInt *dest, const TEE_BigInt *op1, 469 const TEE_BigInt *op2, const TEE_BigInt *n); 470 471 void TEE_BigIntMulMod(TEE_BigInt *dest, const TEE_BigInt *op1, 472 const TEE_BigInt *op2, const TEE_BigInt *n); 473 474 void TEE_BigIntSquareMod(TEE_BigInt *dest, const TEE_BigInt *op, 475 const TEE_BigInt *n); 476 477 void TEE_BigIntInvMod(TEE_BigInt *dest, const TEE_BigInt *op, 478 const TEE_BigInt *n); 479 480 /* TEE Arithmetical API - Other arithmetic operations */ 481 482 bool TEE_BigIntRelativePrime(const TEE_BigInt *op1, const TEE_BigInt *op2); 483 484 void TEE_BigIntComputeExtendedGcd(TEE_BigInt *gcd, TEE_BigInt *u, 485 TEE_BigInt *v, const TEE_BigInt *op1, 486 const TEE_BigInt *op2); 487 488 int32_t TEE_BigIntIsProbablePrime(const TEE_BigInt *op, 489 uint32_t confidenceLevel); 490 491 /* TEE Arithmetical API - Fast modular multiplication operations */ 492 493 void TEE_BigIntConvertToFMM(TEE_BigIntFMM *dest, const TEE_BigInt *src, 494 const TEE_BigInt *n, 495 const TEE_BigIntFMMContext *context); 496 497 void TEE_BigIntConvertFromFMM(TEE_BigInt *dest, const TEE_BigIntFMM *src, 498 const TEE_BigInt *n, 499 const TEE_BigIntFMMContext *context); 500 501 void TEE_BigIntFMMConvertToBigInt(TEE_BigInt *dest, const TEE_BigIntFMM *src, 502 const TEE_BigInt *n, 503 const TEE_BigIntFMMContext *context); 504 505 void TEE_BigIntComputeFMM(TEE_BigIntFMM *dest, const TEE_BigIntFMM *op1, 506 const TEE_BigIntFMM *op2, const TEE_BigInt *n, 507 const TEE_BigIntFMMContext *context); 508 509 #define TA_EXPORT 510 511 /* 512 * TA Interface 513 * 514 * Each Trusted Application must provide the Implementation with a number 515 * of functions, collectively called the “TA interface”. These functions 516 * are the entry points called by the Trusted Core Framework to create the 517 * instance, notify the instance that a new client is connecting, notify 518 * the instance when the client invokes a command, etc. 519 * 520 * Trusted Application Entry Points: 521 */ 522 523 /* 524 * The function TA_CreateEntryPoint is the Trusted Application's 525 * constructor, which the Framework calls when it creates a new instance of 526 * the Trusted Application. To register instance data, the implementation 527 * of this constructor can use either global variables or the function 528 * TEE_InstanceSetData. 529 * 530 * Return Value: 531 * - TEE_SUCCESS: if the instance is successfully created, the function 532 * must return TEE_SUCCESS. 533 * - Any other value: if any other code is returned the instance is not 534 * created, and no other entry points of this instance will be called. 535 * The Framework MUST reclaim all resources and dereference all objects 536 * related to the creation of the instance. 537 * 538 * If this entry point was called as a result of a client opening a 539 * session, the error code is returned to the client and the session is 540 * not opened. 541 */ 542 TEE_Result TA_EXPORT TA_CreateEntryPoint(void); 543 544 /* 545 * The function TA_DestroyEntryPoint is the Trusted Application‟s 546 * destructor, which the Framework calls when the instance is being 547 * destroyed. 548 * 549 * When the function TA_DestroyEntryPoint is called, the Framework 550 * guarantees that no client session is currently open. Once the call to 551 * TA_DestroyEntryPoint has been completed, no other entry point of this 552 * instance will ever be called. 553 * 554 * Note that when this function is called, all resources opened by the 555 * instance are still available. It is only after the function returns that 556 * the Implementation MUST start automatically reclaiming resources left 557 * opened. 558 * 559 * Return Value: 560 * This function can return no success or error code. After this function 561 * returns the Implementation MUST consider the instance destroyed and 562 * reclaims all resources left open by the instance. 563 */ 564 void TA_EXPORT TA_DestroyEntryPoint(void); 565 566 /* 567 * The Framework calls the function TA_OpenSessionEntryPoint when a client 568 * requests to open a session with the Trusted Application. The open 569 * session request may result in a new Trusted Application instance being 570 * created as defined in section 4.5. 571 * 572 * The client can specify parameters in an open operation which are passed 573 * to the Trusted Application instance in the arguments paramTypes and 574 * params. These arguments can also be used by the Trusted Application 575 * instance to transfer response data back to the client. See section 4.3.6 576 * for a specification of how to handle the operation parameters. 577 * 578 * If this function returns TEE_SUCCESS, the client is connected to a 579 * Trusted Application instance and can invoke Trusted Application 580 * commands. When the client disconnects, the Framework will eventually 581 * call the TA_CloseSessionEntryPoint entry point. 582 * 583 * If the function returns any error, the Framework rejects the connection 584 * and returns the error code and the current content of the parameters the 585 * client. The return origin is then set to TEE_ORIGIN_TRUSTED_APP. 586 * 587 * The Trusted Application instance can register a session data pointer by 588 * setting *psessionContext. The value of this pointer is not interpreted 589 * by the Framework, and is simply passed back to other TA_ functions 590 * within this session. Note that *sessionContext may be set with a pointer 591 * to a memory allocated by the Trusted Application instance or with 592 * anything else, like an integer, a handle etc. The Framework will not 593 * automatically free *sessionContext when the session is closed; the 594 * Trusted Application instance is responsible for freeing memory if 595 * required. 596 * 597 * During the call to TA_OpenSessionEntryPoint the client may request to 598 * cancel the operation. See section 4.10 for more details on 599 * cancellations. If the call to TA_OpenSessionEntryPoint returns 600 * TEE_SUCCESS, the client must consider the session as successfully opened 601 * and explicitly close it if necessary. 602 * 603 * Parameters: 604 * - paramTypes: the types of the four parameters. 605 * - params: a pointer to an array of four parameters. 606 * - sessionContext: A pointer to a variable that can be filled by the 607 * Trusted Application instance with an opaque void* data pointer 608 * 609 * Return Value: 610 * - TEE_SUCCESS if the session is successfully opened. 611 * - Any other value if the session could not be open. 612 * o The error code may be one of the pre-defined codes, or may be a new 613 * error code defined by the Trusted Application implementation itself. 614 */ 615 TEE_Result TA_EXPORT TA_OpenSessionEntryPoint(uint32_t paramTypes, 616 TEE_Param params[TEE_NUM_PARAMS], 617 void **sessionContext); 618 TEE_Result TA_EXPORT 619 __GP11_TA_OpenSessionEntryPoint(uint32_t paramTypes, 620 __GP11_TEE_Param params[TEE_NUM_PARAMS], 621 void **sessionContext); 622 623 /* 624 * The Framework calls this function to close a client session. During the 625 * call to this function the implementation can use any session functions. 626 * 627 * The Trusted Application implementation is responsible for freeing any 628 * resources consumed by the session being closed. Note that the Trusted 629 * Application cannot refuse to close a session, but can hold the closing 630 * until it returns from TA_CloseSessionEntryPoint. This is why this 631 * function cannot return an error code. 632 * 633 * Parameters: 634 * - sessionContext: The value of the void* opaque data pointer set by the 635 * Trusted Application in the function TA_OpenSessionEntryPoint for this 636 * session. 637 */ 638 void TA_EXPORT TA_CloseSessionEntryPoint(void *sessionContext); 639 640 /* 641 * The Framework calls this function when the client invokes a command 642 * within the given session. 643 * 644 * The Trusted Application can access the parameters sent by the client 645 * through the paramTypes and params arguments. It can also use these 646 * arguments to transfer response data back to the client. 647 * 648 * During the call to TA_InvokeCommandEntryPoint the client may request to 649 * cancel the operation. 650 * 651 * A command is always invoked within the context of a client session. 652 * Thus, any session function can be called by the command implementation. 653 * 654 * Parameter: 655 * - sessionContext: The value of the void* opaque data pointer set by the 656 * Trusted Application in the function TA_OpenSessionEntryPoint. 657 * - commandID: A Trusted Application-specific code that identifies the 658 * command to be invoked. 659 * - paramTypes: the types of the four parameters. 660 * - params: a pointer to an array of four parameters. 661 * 662 * Return Value: 663 * - TEE_SUCCESS: if the command is successfully executed, the function 664 * must return this value. 665 * - Any other value: if the invocation of the command fails for any 666 * reason. 667 * o The error code may be one of the pre-defined codes, or may be a new 668 * error code defined by the Trusted Application implementation itself. 669 */ 670 671 TEE_Result TA_EXPORT 672 TA_InvokeCommandEntryPoint(void *sessionContext, uint32_t commandID, 673 uint32_t paramTypes, 674 TEE_Param params[TEE_NUM_PARAMS]); 675 TEE_Result TA_EXPORT 676 __GP11_TA_InvokeCommandEntryPoint(void *sessionContext, uint32_t commandID, 677 uint32_t paramTypes, 678 __GP11_TEE_Param params[TEE_NUM_PARAMS]); 679 680 /* 681 * Matching Client Functions <--> TA Functions 682 * 683 * TEE_OpenSession or TEE_OpenTASession: 684 * If a new Trusted Application instance is needed to handle the session, 685 * TA_CreateEntryPoint is called. 686 * Then, TA_OpenSessionEntryPoint is called. 687 * 688 * TEE_InvokeCommand or TEE_InvokeTACommand: 689 * TA_InvokeCommandEntryPoint is called. 690 * 691 * TEE_CloseSession or TEE_CloseTASession: 692 * TA_CloseSessionEntryPoint is called. 693 * For a multi-instance TA or for a single-instance, non keep-alive TA, if 694 * the session closed was the last session on the instance, then 695 * TA_DestroyEntryPoint is called. Otherwise, the instance is kept until 696 * the TEE shuts down. 697 */ 698 699 #include <tee_api_compat.h> 700 701 #endif /*TEE_INTERNAL_API_H*/ 702