 |
Samsung Internal API reference
2.0
|
|
Samsung Internal API reference
2.0
|
The goal of this document is to describe Secure OS and Service Library API categorized to Samsung Internal API. The intended audience is Trusted Application (TA) developers with permission to access Samsung Internal API.
The scope of this document is to describe Samsung Internal API to Trusted Application developers. Global Platform (GP) API is out of scope of this document, and they are explained TEE Internal API document at Global Platform portal.
Each TA has set of mandatory and custom properties which can help TA developers to setup TA features. Mandatory properties are implemented according to TEE specifications and custom one are Samsung extensions.
| Name | Type | Description |
|---|---|---|
| TA_PROP_DATASIZE | Integer | Maximum estimated amount of dynamic data in bytes configured for the Trusted Application. The memory blocks allocated through TEE_Malloc are drawn from this space, as well as the task stacks. How this value precisely relates to the exact number and sizes of blocks that can be allocated is implementation-dependent. |
| TA_PROP_GROUP_ID | String | Group identifier to wich TA belongs to. |
| TA_PROP_INSTANCE_KEEPALIVE | Boolean | Whether the Trusted Application instance context SHALL be preserved when there are no sessions connected to the instance. The instance context is defined as all writable data within the memory space of the Trusted Application instance, including the instance heap. This property is meaningful only when the TA_PROP_SINGLE_INSTANCE is set to true. When this property is set to false, then the TA instance MUST be created when one or more sessions are opened on the TA and it MUST be destroyed when there are no more sessions opened on the instance. When this property is set to true, then the TA instance is terminated only when the TEE shuts down, which includes when the device goes through a system-wide global power cycle. Note that the TEE MUST NOT shut down whenever the REE does not shut down and keeps a restorable state, including when it goes through transitions into lower power states (hibernation, suspend, etc.). The exact moment when a keep-alive single instance is created is implementation-defined but it MUST be no later than the first session opening. |
| TA_PROP_MULTISESSION | Boolean | Whether the Trusted Application instance supports multiple sessions. |
| TA_PROP_SINGLE_INSTANCE | Boolean | Whether the Implementation SHALL create a single TA instance for all the client sessions (if true ) or SHALL create a separate instance for each client session (if false ). |
| TA_PROP_STACKSIZE | Integer | Maximum stack size in bytes available to any task in the Trusted Application at any point in time. This corresponds to the stack size used by the TA code itself and does not include stack space possibly used by the Trusted Core Framework. For example, if this property is set to “ 512 ”, then the Framework MUST guarantee that, at any time, the TA code can consume up to 512 bytes of stack and still be able to call any functions in the API. |
| TA_PROP_UUID | UUID | 16 bits identifier of the Trusted Application. |
| TA_PROP_VERSION | String | Version number of this Trusted Application. |
Optional properties
GPD.TA.DBG_DLM.DATA_AVAILABLE - Debug Rules Property states what sort of DLM data can be retrieved according to the TA.
GPD.TEE.DBG_DLM.DATA_AVAILABLE - states what sort of DLM data can be retrieved, according to each TEE.
| Name | Value | Description |
|---|---|---|
| TEE_BLOCKED | -64 | As a TA rule value, indicates that while the TA with this value has active sessions, DLM events of any TA in the TEE shall be ignored and not reported through the DLM service. As a TEE rule value, shall be considered the same as BLOCKED. |
| BLOCKED | 0 | No DLM is available. As a TA rule value, indicates that while this TA may open a DLM session and use TEE_DLMPrintf(), there shall be no output. As a TEE rule value, indicates that while any TA may open a DLM session and use TEE_DLMPrintf(), there shall be no output. |
| ALL | 64 | All DLM data is available. |
GPD.TA.DBG_PMR.DATA_AVAILABLE - Debug Rules Property states what sort of PMR data shall be retrievable, according to the TA.
GPD.TEE.DBG_PMR.DATA_AVAILABLE - states what sort of PMR data shall be retrievable, according to each TEE.
| Name | Value | Description |
|---|---|---|
| TEE_BLOCKED | -64 | As a TA rule value, indicates that while the TA with this value has active sessions, PMR events of any TA in the TEE shall be ignored and not reported through the PMR service. |
| BLOCKED (default) | 0 | As a TA rule value, indicates that PMR events of this TA shall be ignored and not reported through the PMR service. |
| CODE_ONLY | 32 | Only the following data about the panicked TA shall be available: specNumber functionNumber markValue panicReasonCode |
| CODE_STATE | 64 | This adds the panicked TA’s state to the CODE_ONLY set of data available. If sufficient resources are available, the state data shall be placed at the location defined by PMR_STATE_POINTER |
| HEAP_STACK | 96 | This adds the panicked TA’s heap and stack to the CODE_STATE set of data available. If sufficient resources are available, the heap and stack data shall be placed at the locations defined by PMR_HEAP_POINTER and PMR_STACK_POINTER |
| ALL | 112 | All data in the TEE is available to be reported. In systems where TA specific state could not be presented due to the method of sharing TA stacks and heap between trusted applications, in this state such data may be presented. |
gpd.ta.description - Trusted Application description. Default value is "descr. none ".
gpd.ta.instanceKeepAlive - type Boolean. Whether the Trusted Application instance context SHALL be preserved when there are no sessions connected to the instance. The instance context is defined as all writable data within the memory space of the Trusted Application instance, including the instance heap. This property is meaningful only when the gpd.ta.singleInstance is set to true. When this property is set to false, then the TA instance MUST be created when one or more sessions are opened on the TA and it MUST be destroyed when there are no more sessions opened on the instance. When this property is set to true , then the TA instance is terminated only when the TEE shuts down, which includes when the device goes through a system-wide global power cycle. Note that the TEE MUST NOT shut down whenever the REE does not shut down and keeps a restorable state, including when it goes through transitions into lower power states (hibernation, suspend, etc.). The exact moment when a keep-alive single instance is created is implementation-defined but it MUST be no later than the first session opening.
gpd.ta.multiSession - type Boolean. Whether the Trusted Application instance supports multiple sessions. This property is ignored when gpd.ta.singleinstance is set to false.
gpd.ta.privilege.ta_authority - type String. Group name.
gpd.ta.singleInstance - type Boolean. Whether the Implementation SHALL create a single TA instance for all the client sessions (if true) or SHALL create a separate instance for each client session (if false ).
gpd.ta.stackSize - type Integer. Maximum stack size in bytes available to any task in the Trusted Application at any point in time. This corresponds to the stack size used by the TA code itself and does not include stack space possibly used by the Trusted Core Framework. For example, if this property is set to "512", then the Framework MUST guarantee that, at any time, the TA code can consume up to 512 bytes of stack and still be able to call any functions in the API.
gpd.ta.version - type String. Version number of this Trusted Application.
gpd.tee.debug.debug_unlock_properties - type Boolean. If true, then modifiable Debug Rules Properties may be changed. If false or not present, then modifiable Debug Rules Properties shall not be changeable. This property is itself a modifiable Debug Rules Property and so setting this false prevents resetting it to true.
gpd.tee.debug.DLM_available - type Boolean. If true, then the DLM extension has been installed on this device. If false or not present, then the DLM extension has not been installed on this device. Note that just because the DLM extension is installed does not mean that debug log messages shall be transferred through the system, as they may be ignored due to other Debug Rules Properties of TAs and the TEE.
samsung.client.FIPS_mode_enable - type Boolean. If true FIPS mode is enable.
samsung.ta.cacheHeapSize (old name is gpd.ta.cacheHeapSize) - Memory area that will be allocated while TA starting. This memory is not exempted with free(). Default value is 0.
samsung.ta.FIPS_mode_enable - Enable using FIPS. Default value is false.
samsung.ta.numInstances - Number of instances. It effects if TA_PROP_SINGLE_INSTANCE = false. Default value is 0.
samsung.ta.numSessions - Number of sessions. It effects if TA_PROP_MULTISESSION = true.
sys.ta.no_aslr - Allocation to special memory addresses. Default value is false.
sys.ta.rlim_cur - Priority of TA start. Default value is sys.ta.rlim_max / 2.
sys.ta.rlim_max - Maximum priority value. It is constant.
sys.ta.thread_count - Number of threads, default value is 2.
Samsung Internal API is Samsung's own API to support any privileged features to internal TA developers such as driver API, interrupt API, custom SMC handler, and so on. Only TA developers with permission to the API can use it, and 3rd-party TA developers should be prevented from accessing the API for security reasons.
Thread support library API A set of interfaces (functions, header files) for threaded programming commonly known as POSIX threads, or Pthreads. A single process can contain multiple threads, all of which are executing the same program. These threads share the same global memory (data and heap segments), but each thread has its own stack (automatic variables).
Math library API Set of math functions for floating point calculation.
Auxiliary API is a set of API to provide POSIX-like interface to TA developers. The feature coverage is limited to the minimum set of functions rather than fully supporting POSIX standard in Secure World. Currently, only standard IO functions and string operations are supported by Auxiliary API.
1.8.11 
