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