libminkteec/include/tee_client_api.h
Structures
TEEC_UUID
Members
uint32_t
uint16_t
uint16_t
uint8_t
TEEC_Context
Members
Object
Object
Object
struct TEEC_Context
TEEC_Session
Members
TEEC_Context *
Object
struct TEEC_Session
TEEC_SharedMemory
Members
void *
size_t
uint32_t
TEEC_Context *
uint8_t
uint8_t
Object
struct TEEC_SharedMemory
TEEC_RegisteredMemoryReference
Members
TEEC_SharedMemory *
size_t
size_t
TEEC_TempMemoryReference
Members
void *
size_t
TEEC_Value
Members
uint32_t
uint32_t
TEEC_Parameter
Members
TEEC_TempMemoryReference
TEEC_RegisteredMemoryReference
TEEC_Value
TEEC_Operation
Members
uint32_t
uint32_t
TEEC_Parameter
TEEC_Session *
uint32_t
struct TEEC_Operation
Functions
TEEC_InitializeContext
Open a handle to the TEE device.
This function initializes a new TEE Context, forming a connection between this Client Application and the TEE identified by the string identifier name. The Client Application MAY pass a NULL name, which means that a default TEE will be connected to. The caller MUST pass a pointer to a valid TEEC_Context in context. The API assume all fields of the TEEC_Context structure are in an undefined state.
const char *
a zero-terminated string describing the TEE to connect to. If this parameter is set to NULL default “QSEE” is selected.
context: a TEEC_Context structure that is initialized this API
TEEC_FinalizeContext
This function finalizes an initialized TEE Context, closing the connection between the Client Application and the TEE.
The Client Application MUST only call this function when ALL Sessions inside this TEE_Context have been closed and all Shared Memory blocks have been released. The functiona does not fail: after this function returns the Client Application must be able to consider that the Context has been closed. The API does not do anything if context is NULL, simply returns.
TEEC_Context *
an initialized TEEC_Context structure which is to be finalized.
TEEC_RegisterSharedMemory
This function registers a block of existing Client Application memory as a block of Shared Memory within the scope of the specified TEE Context, in accordance with the parameters which have been set by the Client Application inside the sharedMem structure.
The parameter context MUST point to an initialized TEE Context. The parameter sharedMem MUST point to the Shared Memory structure defining the memory region to register. The Client Application MUST have populated the following fields of the Shared Memory structure before calling this function:
The buffer field MUST point to the memory region to be shared, and MUST not be NULL.
The size field MUST contain the size of the buffer, in bytes. (0 is a valid size).
The flags field indicates the intended directions of data flow between the ClientApplication and the TEE.
The API assumes that all other fields in the Shared Memory structure have undefined content. The size of the buffer is limited defined by the constant TEEC_CONFIG_SHAREDMEM_MAX_SIZE. However, note that this function may fail to register a block smaller than this limit due to low resource condition encountered at run-time.
TEEC_Context *
a pointer to an initialized TEE Context
a pointer to a Shared Memory structure to register: o the buffer, size, and flags fields of the sharedMem structure MUST be set in accordance with the specification described above
TEEC_AllocateSharedMemory
This function allocates a new block of memory as a block of Shared Memory within the scope of the specified TEE Context, in accordance with the parameters which have been set by the Client Application inside the sharedMem structure.
The context parameter MUST point to an initialized TEE Context. The sharedMem parameter MUST point to the Shared Memory structure defining the region to allocate. Client Applications MUST have populated the following fields of the Shared Memory structure: The size field MUST contain the desired s ize of the buffer, in bytes. The size is allowedto be zero. In this case memory is allocated and the pointer written in to the buffer field on return MUST not be NULL but MUST never be de-referenced by the Client Application. In this case however, the Shared Memory block can be used in Registered Memory References. The flags field indicates the allowed directions of data flow between the ClientApplication and the TEE. The API assumes that all other fields in the Shared Memory structure have undefined content. The size of the buffer is limited defined by the constant TEEC_CONFIG_SHAREDMEM_MAX_SIZE. However, note that this function may fail to register a block smaller than this limit due to low resource condition encountered at run-time. If this function returns any code other than TEEC_SUCCESS, The API will return with buffe field of sharedMem to NULL.
TEEC_Context *
a pointer to an initialized TEE Context
a pointer to a Shared Memory structure to allocate: o Before calling this API, Client Application MUST set the size, and flags fields o On return, for a successful allocation the API will set the pointer buffer to the address of the allocated block, otherwise it will set buffer to NULL.
TEEC_ReleaseSharedMemory
This function deregisters or deallocates a previously initialized block of.
Shared Memory For a memory buffer allocated using TEEC_AllocateSharedMemory, this API will free the underlying memory. It will set the buffer and size fields of the sharedMem structure to NULL and 0 respectively before returning. Client Application MUST NOT access this region after this function has been called.
For memory registered using TEEC_RegisterSharedMemory this API deregister the underlying memory from the TEE, but the memory region will stay available to the Client Application for other purposes as the memory is owned by it.
This API does nothing if the sharedMem parameter is NULL.
a pointer to an initialized TEE Context
haredMem: a pointer to a valid Shared Memory structure
TEEC_OpenSession
This function opens a new Session between the Client Application and the specified Trusted Application.
The API assumes that all fields of this session structure are in an undefined state. When this function returns TEEC_SUCCESS this structure is populated with all the information necessary for subsequent operations within the Session. The target Trusted Application is identified by a UUID passed in the parameter destination. The Session MAY be opened using a specific connection method that can carry additional connection data, such as data about the user or user-group running the Client Application, or about the Client Application itself. This allows the Trusted Application to implement access control methods which separate functionality or data accesses for different actors in the rich environment outside of the TEE.
The additional data associated with each connection method is passed in via the pointer connectionData (Unsupported for QTEE context). For the core login types the following connection data is required:: TEEC_LOGIN_PUBLIC o connectionData SHOULD be NULL. TEEC_LOGIN_USER o connectionData SHOULD be NULL. TEEC_LOGIN_GROUP : Unsupported for QTEE/default context o connectionData MUST point to a uint32_t which contains the group which this Client Application wants to connect as. The Implementation is responsible for securely ensuring that the Client Application instance is actually a member of this group. TEEC_LOGIN_APPLICATION o connectionData SHOULD be NULL. TEEC_LOGIN_USER_APPLICATION o connectionData SHOULD be NULL. TEEC_LOGIN_GROUP_APPLICATION : Unsupported for QTEE/default context o connectionData MUST point to a uint32_t which contains the group which this Client Application wants to connect as. The Implementation is responsible for securely ensuring that the Client Application instance is actually a member of this group.
User MAY optionally send an Operation Payload, and MAY also cancel it. When the payload is present, the parameter operation MUST point to a TEEC_Operation structure populated by the Client Application. If operation is NULL then no data buffers are exchanged with the Trusted Application, and the operation cannot be cancelled by the Client Application.
The result of this function is returned both in the function TEEC_Result return code and the return orig stored in the variable pointed to by returnOrigin.
TEEC_Context *
pointer to an initialized TEE Context
TEEC_Session *
pointer to a Session structure to open.
const TEEC_UUID *
pointer to a structure containing the UUID of the destination Trusted Application.
uint32_t
the method of connection to use.
const void *
any necessary data required to support the connection method chosen
TEEC_Operation *
pointer to an Operation containing a set of Parameters to exchange with the Trusted Application, or NULL if no Parameters are to be exchanged or if the operation cannot be cancelled. Refer to TEEC_InvokeCommand for more details.
uint32_t *
pointer to a variable which will contain the return origin. This field may be NULL if the return origin is not needed.
TEEC_CloseSession
This function closes a Session which has been opened with a Trusted Application.
All Commands within the Session MUST have completed before calling this function. This API does nto do anything if the session parameter is NULL. This API does not return any failure: after this function returns the Client Application should consider that the Session has been closed.
TEEC_Session *
pointer to a Session to close.
TEEC_InvokeCommand
This function invokes a Command within the specified Session.
The parameter session MUST point to a valid open Session. The parameter commandID is an identifier that is used to indicate which of the exposed TrustedApplication functions should be invoked. The supported command identifiers are defined by the Trusted Application?s protocol.
Operation Handling A Command MAY optionally carry an Operation Payload. When the payload is present the parameter operation MUST point to a TEEC_Operation structure populated by the Client Application. If operation is NULL then no parameters are exchanged with the Trusted Application, and only the Command ID is exchanged. The operation structure is also used to manage cancellation of the Command. If cancellation is required then the operation pointer MUST be non-NULL and the Client Application MUST have zeroed the started field of the operation structure before calling this function.
NOTE: Cancellation of pending operations is unsupported for QTEE/default context
The operation structure MAY contain no Parameters if no data payload is to be exchanged.
The result of this function is returned both in the function TEEC_Result return code and the return orig stored in the variable pointed to by returnOrigin: If the return origin is different from TEEC_ORIGIN_TRUSTED_APP, the return TEEC_ERROR_CANCEL code MUST be one of the error codes defined above. If the return code is then means that the operation was cancelled before it reached the Trusted Application. If the return origin is TEEC_ORIGIN_TRUSTED_APP, the meaning of the return code depends on the protocol between the Client Application and the Trusted Application. If TEEC_SUCCESS is returned, it always means the operatin was succesful. However, and if the function returns a code different from TEEC_SUCCESS, it means that the operation failed.
TEEC_Session *
the open Session in which the command will be invoked.
uint32_t
the identifier of the Command within the Trusted Application to invoke. The meaning of each Command Identifier must be defined in the protocol exposed by the Trusted Application
TEEC_Operation *
pointer to an Operation containing a set of Parameters to exchange with the Trusted Application, or NULL if no Parameters are to be exchangedor if the operation cannot be cancelled. Refer to TEEC_InvokeCommand for more details.
uint32_t *
pointer to a variable which will contain the return. origin. This field may be NULL if the return origin is not needed.
TEEC_RequestCancellation
This function requests the cancellation of a pending open Session operation or a Command invocation operation.
As this is a synchronous API, this function must be called from a thread other than the one executing the TEEC_OpenSession or TEEC_InvokeCommand function.
This function just sends a cancellation signal to the TEE and returns immediately; the operation is not guaranteed to have been cancelled when this function returns. In addition, the cancellation request is just a hint; the TEE or the Trusted Application MAY ignore the cancellation request. It is valid to call this function using a TEEC_Operation structure any time after the Client Application has set the started field of an Operation structure to zero. In particular, an operation can be cancelled before it is actually invoked, during invocation, and after invocation. Note that the Client Application MUST reset the started field to zero each time an Operation structure is used or re-used to open a Session or invoke a Command if the new operation is to be cancellable.
pointer to a Session to close.