Copyright 2011 GlobalPlatform Inc. All Rights Reserved.
Recipients of this document are invited to submit, with their comments, notification of any relevant patent rights or other
intellectual property rights of which they may be aware which might be infringed by the implementation of the specification set
forth in this document, and to provide supporting documentation. The technology provided or described herein is subject to
updates, revisions, and extensions by GlobalP
latform. Use of this information is governed by the GlobalPlatform license
agreement and any use inconsistent with that agreement is strictly prohibited. GlobalPlatform is a Trademark of GlobalPlatform, Inc.
GlobalPlatform Device Technology
TEE Internal API Specification
Version 1.0
Public Release
December 2011
Document Reference: GPD_SPE_010
TM
2/202 TEE Internal API Specification – Public Release v1.0
Copyright 2011 GlobalPlatform Inc. All Rights Reserved.
The technology provided or described herein is subject to updates, revisions, and extensions by GlobalPlatform. Use of this
information is governed by the GlobalPlatform license agreement and any use inconsistent with that agreement is strictly
prohibited.
This page intentionally left blank.
TEE Internal API Specification – Public Release v1.0 3/202
Copyright 2011 GlobalPlatform Inc. All Rights Reserved.
The technology provided or described herein is subject to updates, revisions, and extensions by GlobalPlatform. Use of this
information is governed by the GlobalPlatform license agreement and any use inconsistent with that agreement is strictly
prohibited.
Contents
1 Introduction .......................................................................................................................... 10
1.1 Audience ............................................................................................................................................. 10
1.2 IPR Disclaimer..................................................................................................................................... 10
1.3 Normative References ........................................................................................................................ 11
1.4 Terminology and Definitions ................................................................................................................ 11
1.5 Abbreviations and Notations ............................................................................................................... 14
1.6 Revision History .................................................................................................................................. 15
2 Overview of the TEE Internal API ........................................................................................ 16
2.1 Trusted Applications ............................................................................................................................ 16
2.1.1 TA Interface .................................................................................................................................. 17
2.1.2 Instances, Sessions, Tasks, and Commands .............................................................................. 18
2.1.3 Sequential Execution of Entry Points ........................................................................................... 18
2.1.4 Cancellations ................................................................................................................................ 18
2.1.5 Unexpected Client Termination .................................................................................................... 19
2.1.6 Instance Types ............................................................................................................................. 19
2.1.7 Configuration, Development, and Management .......................................................................... 19
2.2 Error Handling ..................................................................................................................................... 20
2.2.1 Normal Errors ............................................................................................................................... 20
2.2.2 Programmer Errors ...................................................................................................................... 20
2.2.3 Panics ........................................................................................................................................... 20
2.3 Opaque Handles ................................................................................................................................. 21
2.4 Properties ............................................................................................................................................ 22
2.5 Trusted Storage API for Data and Keys .............................................................................................. 23
2.6 Cryptographic Operations API ............................................................................................................ 23
2.7 Time API .............................................................................................................................................. 24
2.8 Arithmetical API ................................................................................................................................... 24
3 Common Definitions ............................................................................................................ 25
3.1 Header File .......................................................................................................................................... 25
3.2 Data Types .......................................................................................................................................... 25
3.2.1 Basic Types .................................................................................................................................. 25
3.2.2 TEE_Result, TEEC_Result .......................................................................................................... 25
3.2.3 TEE_UUID, TEEC_UUID ............................................................................................................. 26
3.3 Constants ............................................................................................................................................ 27
3.3.1 Error Codes .................................................................................................................................. 27
3.4 Parameter Annotations ....................................................................................................................... 28
3.4.1 [in], [out], and [inout] ..................................................................................................................... 28
3.4.2 [outopt] ......................................................................................................................................... 28
3.4.3 [inbuf] ............................................................................................................................................ 28
3.4.4 [outbuf] ......................................................................................................................................... 29
3.4.5 [outbufopt] .................................................................................................................................... 29
3.4.6 [instring] and [instringopt] ............................................................................................................. 30
3.4.7 [outstring] and [outstringopt] ......................................................................................................... 30
3.4.8 [ctx] ............................................................................................................................................... 30
4 Trusted Core Framework API .............................................................................................. 31
4.1 Data Types .......................................................................................................................................... 32
4.1.1 TEE_Identity ................................................................................................................................. 32
4.1.2 TEE_Param .................................................................................................................................. 32
4.1.3 TEE_TASessionHandle ............................................................................................................... 32
4/202 TEE Internal API Specification – Public Release v1.0
Copyright 2011 GlobalPlatform Inc. All Rights Reserved.
The technology provided or described herein is subject to updates, revisions, and extensions by GlobalPlatform. Use of this
information is governed by the GlobalPlatform license agreement and any use inconsistent with that agreement is strictly
prohibited.
4.1.4 TEE_PropSetHandle .................................................................................................................... 32
4.2 Constants ............................................................................................................................................ 33
4.2.1 Parameter Types .......................................................................................................................... 33
4.2.2 Login Types .................................................................................................................................. 33
4.2.3 Origin Codes ................................................................................................................................ 33
4.2.4 Property Set Pseudo-Handles...................................................................................................... 34
4.2.5 Memory Access Rights ................................................................................................................ 34
4.3 TA Interface ......................................................................................................................................... 35
4.3.1 TA_CreateEntryPoint ................................................................................................................... 39
4.3.2 TA_DestroyEntryPoint .................................................................................................................. 39
4.3.3 TA_OpenSessionEntryPoint ........................................................................................................ 40
4.3.4 TA_CloseSessionEntryPoint ........................................................................................................ 41
4.3.5 TA_InvokeCommandEntryPoint ................................................................................................... 42
4.3.6 Operation Parameters in the TA Interface ................................................................................... 43
4.4 Property Access Functions ................................................................................................................. 47
4.4.1 TEE_GetPropertyAsString ........................................................................................................... 48
4.4.2 TEE_GetPropertyAsBool ............................................................................................................. 49
4.4.3 TEE_GetPropertyAsU32 .............................................................................................................. 50
4.4.4 TEE_GetPropertyAsBinaryBlock.................................................................................................. 51
4.4.5 TEE_GetPropertyAsUUID ............................................................................................................ 52
4.4.6 TEE_GetPropertyAsIdentity ......................................................................................................... 53
4.4.7 TEE_AllocatePropertyEnumerator ............................................................................................... 54
4.4.8 TEE_FreePropertyEnumerator .................................................................................................... 54
4.4.9 TEE_StartPropertyEnumerator .................................................................................................... 55
4.4.10 TEE_ResetPropertyEnumerator .................................................................................................. 55
4.4.11 TEE_GetPropertyName ............................................................................................................... 56
4.4.12 TEE_GetNextProperty ................................................................................................................. 56
4.5 Trusted Application Configuration Properties ..................................................................................... 57
4.6 Client Properties .................................................................................................................................. 59
4.7 Implementation Properties .................................................................................................................. 61
4.8 Panics .................................................................................................................................................. 63
4.8.1 TEE_Panic ................................................................................................................................... 63
4.9 Internal Client API ............................................................................................................................... 64
4.9.1 TEE_OpenTASession .................................................................................................................. 64
4.9.2 TEE_CloseTASession .................................................................................................................. 65
4.9.3 TEE_InvokeTACommand ............................................................................................................ 66
4.9.4 Operation Parameters in the Internal Client API .......................................................................... 68
4.10 Cancellation Functions ........................................................................................................................ 69
4.10.1 TEE_GetCancellationFlag ............................................................................................................ 69
4.10.2 TEE_UnmaskCancellation ........................................................................................................... 70
4.10.3 TEE_MaskCancellation ................................................................................................................ 70
4.11 Memory Management Functions......................................................................................................... 71
4.11.1 TEE_CheckMemoryAccessRights ............................................................................................... 71
4.11.2 TEE_SetInstanceData .................................................................................................................. 74
4.11.3 TEE_GetInstanceData ................................................................................................................. 74
4.11.4 TEE_Malloc .................................................................................................................................. 75
4.11.5 TEE_Realloc ................................................................................................................................ 76
4.11.6 TEE_Free ..................................................................................................................................... 77
4.11.7 TEE_MemMove............................................................................................................................ 77
4.11.8 TEE_MemCompare ..................................................................................................................... 78
4.11.9 TEE_MemFill ................................................................................................................................ 78
5 Trusted Storage API for Data and Keys .............................................................................. 79
TEE Internal API Specification – Public Release v1.0 5/202
Copyright 2011 GlobalPlatform Inc. All Rights Reserved.
The technology provided or described herein is subject to updates, revisions, and extensions by GlobalPlatform. Use of this
information is governed by the GlobalPlatform license agreement and any use inconsistent with that agreement is strictly
prohibited.
5.1 Summary of Features and Design ...................................................................................................... 79
5.2 Data Types .......................................................................................................................................... 81
5.2.1 TEE_Attribute ............................................................................................................................... 81
5.2.2 TEE_ObjectInfo ............................................................................................................................ 81
5.2.3 TEE_Whence ............................................................................................................................... 82
5.2.4 TEE_ObjectHandle ...................................................................................................................... 82
5.2.5 TEE_ObjectEnumHandle ............................................................................................................. 82
5.3 Constants ............................................................................................................................................ 83
5.4 Generic Object Functions .................................................................................................................... 85
5.4.1 TEE_GetObjectInfo ...................................................................................................................... 85
5.4.2 TEE_RestrictObjectUsage ........................................................................................................... 87
5.4.3 TEE_GetObjectBufferAttribute ..................................................................................................... 88
5.4.4 TEE_GetObjectValueAttribute ..................................................................................................... 89
5.4.5 TEE_CloseObject ......................................................................................................................... 90
5.5 Transient Object Functions ................................................................................................................. 91
5.5.1 TEE_AllocateTransientObject ...................................................................................................... 91
5.5.2 TEE_FreeTransientObject ........................................................................................................... 93
5.5.3 TEE_ResetTransientObject ......................................................................................................... 94
5.5.4 TEE_PopulateTransientObject..................................................................................................... 95
5.5.5 TEE_InitRefAttribute, TEE_InitValueAttribute .............................................................................. 97
5.5.6 TEE_CopyObjectAttributes .......................................................................................................... 98
5.5.7 TEE_GenerateKey ....................................................................................................................... 99
5.6 Persistent Object Functions .............................................................................................................. 101
5.6.1 TEE_OpenPersistentObject ....................................................................................................... 101
5.6.2 TEE_CreatePersistentObject ..................................................................................................... 103
5.6.3 Persistent Object Sharing Rules ................................................................................................ 105
5.6.4 TEE_CloseAndDeletePersistentObject ...................................................................................... 107
5.6.5 TEE_RenamePersistentObject .................................................................................................. 108
5.7 Persistent Object Enumeration Functions ......................................................................................... 109
5.7.1 TEE_AllocatePersistentObjectEnumerator ................................................................................ 109
5.7.2 TEE_FreePersistentObjectEnumerator ..................................................................................... 110
5.7.3 TEE_ResetPersistentObjectEnumerator ................................................................................... 111
5.7.4 TEE_StartPersistentObjectEnumerator ..................................................................................... 112
5.7.5 TEE_GetNextPersistentObject ................................................................................................... 113
5.8 Data Stream Access Functions ......................................................................................................... 114
5.8.1 TEE_ReadObjectData ................................................................................................................ 114
5.8.2 TEE_WriteObjectData ................................................................................................................ 115
5.8.3 TEE_TruncateObjectData .......................................................................................................... 116
5.8.4 TEE_SeekObjectData ................................................................................................................ 117
6 Cryptographic Operations API .......................................................................................... 118
6.1 Data Types ........................................................................................................................................ 119
6.1.1 TEE_OperationMode ................................................................................................................. 119
6.1.2 TEE_OperationInfo .................................................................................................................... 119
6.1.3 TEE_OperationHandle ............................................................................................................... 119
6.2 Generic Operation Functions ............................................................................................................ 120
6.2.1 TEE_AllocateOperation .............................................................................................................. 120
6.2.2 TEE_FreeOperation ................................................................................................................... 123
6.2.3 TEE_GetOperationInfo ............................................................................................................... 124
6.2.4 TEE_ResetOperation ................................................................................................................. 125
6.2.5 TEE_SetOperationKey ............................................................................................................... 126
6.2.6 TEE_SetOperationKey2 ............................................................................................................. 128
6.2.7 TEE_CopyOperation .................................................................................................................. 129
