
LibTeec API
Libteec can be understood as a universal API for communication with trusted execution environment (TEE).
This API follows GlobalPlatform (GP) specification.
The original documentation (TEE_Client_API_Specification-xxx.pdf)
is available to download from GlobalPlatform.org under Device section.
        
The Libteec provides a set of functions for executing application in TrustZone and communicating with it. This way we have, so called, two worlds: rich world (like Linux) with Client Application (CA) and secure world with Trusted Application (TA).
Table of Contents
- 1. Type Definitions- 1.1. TeecLoginMethod
- 1.2. TeecValueType
- 1.3. TeecTempMemoryType
- 1.4. TeecRegisteredMemoryType
- 1.5. TeecSharedMemoryFlags
- 1.6. TeecUuid
- 1.7. TeecTaskId
 
- 2. Interfaces- 2.1. LibTeecManagerObject
- 2.2. LibTeecManager
- 2.3. TeecContext
- 2.4. TeecSession
- 2.5. TeecSharedMemory
- 2.6. TeecParameter
- 2.7. TeecRegisteredMemory
- 2.8. TeecTempMemory
- 2.9. TeecValue
- 2.10. TeecOpenSuccessCallback
- 2.11. TeecCommandSuccessCallback
 
- 3. Related Feature
- 4. Full WebIDL
Summary of Interfaces and Methods
| Interface | Method | 
|---|
1. Type Definitions
1.1. TeecLoginMethod
Deprecated. Deprecated since 6.5.
  enum TeecLoginMethod { "PUBLIC", "USER", "GROUP", "APPLICATION" };
Since: 4.0
The following methods are supported:
- PUBLIC - No login data is provided.
- USER - Login data about the user running the Client Application process is provided.
- GROUP - Login data about the group running the Client Application process is provided.
- APPLICATION - Login data about the running Client Application itself is provided.
1.2. TeecValueType
Deprecated. Deprecated since 6.5.
  enum TeecValueType { "INPUT", "OUTPUT", "INOUT" };
Since: 4.0
1.3. TeecTempMemoryType
Deprecated. Deprecated since 6.5.
  enum TeecTempMemoryType { "INPUT", "OUTPUT", "INOUT" };
Since: 4.0
- INPUT - The Parameter is a TeecTempMemory tagged as input.
- OUTPUT - The Parameter is a TeecTempMemory tagged as output.
- INOUT - The Parameter is a TeecTempMemory tagged as both input and output.
1.4. TeecRegisteredMemoryType
Deprecated. Deprecated since 6.5.
  enum TeecRegisteredMemoryType { "WHOLE", "PARTIAL_INPUT", "PARTIAL_OUTPUT", "PARTIAL_INOUT" };
Since: 4.0
- WHOLE - The Parameter is a TeecRegisteredMemory that refers to the entire Shared Memory block.
- PARTIAL_INPUT - The Parameter is a TeecRegisteredMemory that refers to a part of SharedMemory and is tagged as input.
- PARTIAL_OUTPUT - The Parameter is a TeecRegisteredMemory that refers to a part of SharedMemory and is tagged as output.
- PARTIAL_INOUT - The Parameter is a TeecRegisteredMemory that refers to a part of SharedMemory and is tagged as both input and output.
1.6. TeecUuid
Deprecated. Deprecated since 6.5.
  typedef DOMString TeecUuid;
Since: 4.0
2. Interfaces
2.1. LibTeecManagerObject
Deprecated. Deprecated since 6.5.
  [NoInterfaceObject] interface LibTeecManagerObject {
    readonly attribute LibTeecManager teec;
  };
Tizen implements LibTeecManagerObject;
Since: 4.0
2.2. LibTeecManager
Deprecated. Deprecated since 6.5.
  [NoInterfaceObject] interface LibTeecManager {
    TeecContext getContext(optional DOMString? name) raises(WebAPIException);
  };
Since: 4.0
Once a context object is obtained, it is possible to open a session to Trusted Application (TA) .
Methods
- 
getContext
- 
Get TEE context by name.Deprecated. Deprecated since 6.5. TeecContext getContext(optional DOMString? name); Since: 4.0 Privilege level: partner Privilege: http://tizen.org/privilege/tee.client Parameters: - name [optional] [nullable]: describes the TEE to connect to, when not given (or null) connects to default TEE.
 Return value: - 
TeecContext:
 Context The created TeecContext              
 Exceptions: - WebAPIException- with error type SecurityError, if application does not have privilege to access this method. 
- with error type NotSupportedError, if required feature is not supported. 
 
 Code example: try { var ctx = tizen.teec.getContext(); /* Get default TEE context */ } catch (err) { console.log(err.name + ": " + err.message); }
2.3. TeecContext
Deprecated. Deprecated since 6.5.
  [NoInterfaceObject] interface TeecContext {
    TeecTaskId openSession(TeecUuid taUUID, TeecLoginMethod loginMethod, unsigned long? connectionData, TeecParameter[] params,
                           TeecOpenSuccessCallback successCallback, optional ErrorCallback? errorCallback) raises(WebAPIException);
    void revokeCommand(TeecTaskId id) raises(WebAPIException);
    TeecSharedMemory allocateSharedMemory(unsigned long size, TeecSharedMemoryFlags flags) raises(WebAPIException);
    TeecSharedMemory registerSharedMemory(unsigned long long addr, unsigned long size, TeecSharedMemoryFlags flags)
                                          raises(WebAPIException);
    void releaseSharedMemory(TeecSharedMemory shm) raises(WebAPIException);
  };
Since: 4.0
Methods
- 
openSession
- 
Open session with TA.Deprecated. Deprecated since 6.5. TeecTaskId openSession(TeecUuid taUUID, TeecLoginMethod loginMethod, unsigned long? connectionData, TeecParameter[] params, TeecOpenSuccessCallback successCallback, optional ErrorCallback? errorCallback); Since: 4.0 The ErrorCallback() is launched with these error types: - InvalidValuesError - If any of the input parameters contain an invalid value as decided by TA.
- OperationCanceledError - If it fails due to request cancellation
- AbortError - If any other error occurs.
 Privilege level: partner Privilege: http://tizen.org/privilege/tee.client Parameters: - taUUID: the UUID of destination TA.
- loginMethod: the authentication algorithm see TeecLoginMethod.
- connectionData [nullable]: the value required for login method or null.
- params: the array of parameters (note. max is 4 items).
- successCallback: callback function triggered when sucessfully done.
- errorCallback [optional] [nullable]: callback function triggered when error occured.
 Return value: - 
TeecTaskId:
 TeecTaskId The id of scheduled task which can be used to revoke (see revokeCommand).
              
 Exceptions: - WebAPIException- with error type SecurityError, if application does not have privilege to access this method. 
- with error type NotSupportedError, if required feature is not supported. 
- with error type InvalidValuesError, if any of input arguments is invalid. 
 
 Code example: try { function sessionSuccess(session) { /* Session opened, now can communicate with TA */ console.log("session opened"); /* ... */ session.close(); } function sessionError(err) { console.log("openSession: " + err.name + ":" + err.message); } var ta = "123e4567-e89b-12d3-a456-426655440000"; var ctx = tizen.teec.getContext(); ctx.openSession(ta, TeecLoginMethod.PUBLIC, null, null, sessionSuccess, sessionError); } catch (err) { console.log(err.name + ": " + err.message); }
- 
revokeCommand
- 
Revoke last operation identified by id.Deprecated. Deprecated since 6.5. void revokeCommand(TeecTaskId id); Since: 4.0 Privilege level: partner Privilege: http://tizen.org/privilege/tee.client Parameters: - id: the identifier of scheduled task see openSession, invokeCommand
 Exceptions: - WebAPIException- with error type SecurityError, if application does not have privilege to access this method. 
- with error type NotSupportedError, if required feature is not supported. 
 
 Code example: try { var ctx = tizen.teec.getContext(); function commandSuccess(cmd, params) { console.log("command " + cmd + ": ", params); } function sessionSuccess(session) { /* Session opened, now can communicate with TA */ var data = [1, 2, 3, 4, 45, 6, 7, 7, 7]; var p1 = new TeecValue(10, 100); /* Command parameter 1 */ var p2 = new TeecTempMemory(data); /* Command parameter 2 */ var id = session.invokeCommand(1, [p1, p2], commandSuccess); ctx.revokeCommand(id); /* Cancel above command */ session.close(); } function sessionError(err) { console.log("openSession: " + err.name + ":" + err.message); } var ta = "123e4567-e89b-12d3-a456-426655440000"; var cid = ctx.openSession(ta, TeecLoginMethod.PUBLIC, null, null, sessionSuccess, sessionError); /* The cid can be used to revoke openSession request */ } catch (err) { console.log(err.name + ": " + err.message); }
- 
Deprecated. Deprecated since 6.5. TeecSharedMemory allocateSharedMemory(unsigned long size, TeecSharedMemoryFlags flags); Since: 4.0 Allocate shared memory. Privilege level: partner Privilege: http://tizen.org/privilege/tee.client Parameters: - size: the size of memory block to be allocated
- flags: the access flags see SharedMemoryFlags
 Exceptions: - WebAPIException- with error type SecurityError, if application does not have privilege to access this method. 
- with error type NotSupportedError, if required feature is not supported. 
- with error type InvalidValuesError, if any of input arguments is invalid. 
 
 Code example: try { var ctx = tizen.teec.getContext(); var shm = ctx.allocateSharedMemory(1024 * 1024, TeecSharedMemoryFlags.INOUT); ctx.releaseSharedMemory(shm); } catch (err) { console.log(err.name + ": " + err.message); }
- 
Deprecated. Deprecated since 6.5. TeecSharedMemory registerSharedMemory(unsigned long long addr, unsigned long size, TeecSharedMemoryFlags flags); Since: 4.0 Register shared memory. Privilege level: partner Privilege: http://tizen.org/privilege/tee.client Parameters: - addr: the address of memory block to share
- size: the size of memory block to be allocated
- flags: the access flags see SharedMemoryFlags
 Exceptions: - WebAPIException- with error type SecurityError, if application does not have privilege to access this method. 
- with error type NotSupportedError, if required feature is not supported. 
- with error type InvalidValuesError, if any of input arguments is invalid. 
 
 Code example: try { var ctx = tizen.teec.getContext(); var shm = ctx.registerSharedMemory(0x1234567, 1024 * 1024, TeecSharedMemoryFlags.INOUT); ctx.releaseSharedMemory(shm); } catch (err) { console.log(err.name + ": " + err.message); }
- 
Deprecated. Deprecated since 6.5. void releaseSharedMemory(TeecSharedMemory shm); Since: 4.0 Release shared memory, previously allocated or registered. Privilege level: partner Privilege: http://tizen.org/privilege/tee.client Parameters: - shm: the shared memory description object
 Exceptions: - WebAPIException- with error type SecurityError, if application does not have privilege to access this method. 
- with error type NotSupportedError, if required feature is not supported. 
- with error type InvalidValuesError, if any of input arguments is invalid. 
 
 Code example: try { var ctx = tizen.teec.getContext(); var shm = ctx.allocateSharedMemory(1024 * 1024, TeecSharedMemoryFlags.INOUT); ctx.releaseSharedMemory(shm); } catch (err) { console.log(err.name + ": " + err.message); }
2.4. TeecSession
Deprecated. Deprecated since 6.5.
  [NoInterfaceObject] interface TeecSession {
    void close() raises(WebAPIException);
    TeecTaskId invokeCommand(long cmd, TeecParameter[] params, TeecCommandSuccessCallback successCallback,
                             optional ErrorCallback? errorCallback) raises(WebAPIException);
  };
Since: 4.0
Methods
- 
close
- 
Close session with TA.Deprecated. Deprecated since 6.5. void close(); Since: 4.0 Privilege level: partner Privilege: http://tizen.org/privilege/tee.client Exceptions: - WebAPIException- with error type SecurityError, if application does not have privilege to access this method. 
- with error type NotSupportedError, if required feature is not supported. 
 
 Code example: try { function sessionSuccess(session) { /* Session opened, now can communicate with TA */ session.close(); } function sessionError(err) { console.log("openSession: " + err.name + ":" + err.message); } var ta = "123e4567-e89b-12d3-a456-426655440000"; var ctx = tizen.teec.getContext(); val cid = ctx.openSession(ta, TeecLoginMethod.PUBLIC, null, null, sessionSuccess, sessionError); /* Call to openSession can be revoked also */ } catch (err) { console.log(err.name + ": " + err.message); }
- WebAPIException
- 
invokeCommand
- 
Send command to TA.Deprecated. Deprecated since 6.5. TeecTaskId invokeCommand(long cmd, TeecParameter[] params, TeecCommandSuccessCallback successCallback, optional ErrorCallback? errorCallback); Since: 4.0 The ErrorCallback() is launched with these error types: - NotSupportedError - If the requested operation is not supported
- InvalidValuesError - If any of the input parameters contain an invalid value as decided by TA.
- OperationCanceledError - If it fails due to request cancellation
- AbortError - If any other error occurs.
 Privilege level: partner Privilege: http://tizen.org/privilege/tee.client Parameters: - cmd: the command.
- params: the array of parameters (max 4 items).
- successCallback: callback function triggered when sucessfully done.
- errorCallback [optional] [nullable]: callback function triggered when error occured.
 Return value: - 
TeecTaskId:
 TeecTaskId The id of scheduled task which can be used to revoke (see revokeCommand).
              
 Exceptions: - WebAPIException- with error type SecurityError, if application does not have privilege to access this method. 
- with error type NotSupportedError, if required feature is not supported. 
- with error type InvalidValuesError, if any of input arguments is invalid, like params contains more then 4 elements. 
- with error type TypeMismatchError, if the input parameter is not compatible with the expected type for that parameter. 
 
 Code example: try { var gSession; function commandError(err) { gSession.close(); } function commandSuccess(cmd, params) { console.log("command " + cmd + ": ", params); gSession.close(); } function sessionSuccess(session) { /* Session opened, now can communicate with TA */ gSession = session; var data = [1,2,3,4,45,6,7,7,7]; var p1 = new TeecValue(10, 100); /* Command parameter 1 */ var p2 = new TeecTempMemory(data); /* Command parameter 2 */ session.invokeCommand(1, [p1, p2], commandSuccess, commandError); } function sessionError(err) { console.log("openSession: " + err.name + ":" + err.message); } var ta = "123e4567-e89b-12d3-a456-426655440000"; var ctx = tizen.teec.getContext(); val cid = ctx.openSession(ta, TeecLoginMethod.PUBLIC, null, null, sessionSuccess, sessionError); } catch (err) { console.log(err.name + ": " + err.message); }
2.6. TeecParameter
Deprecated. Deprecated since 6.5.
  [NoInterfaceObject] interface TeecParameter {
    attribute DOMString type;
  };
Since: 4.0
Attributes
- 
DOMString typeThe type of parameter - abstract class for all parameteres. This can be one of TeecValueType, TeecTempMemoryType, TeecRegisteredMemoryTypeDeprecated. Deprecated since 6.5. Since: 4.0 
2.7. TeecRegisteredMemory
Deprecated. Deprecated since 6.5.
  [Constructor(TeecSharedMemory memory, unsigned long long offset, unsigned long long size)]
  interface TeecRegisteredMemory : TeecParameter {
    attribute TeecSharedMemory shm;
    attribute unsigned long long offset;
    attribute unsigned long long size;
  };
Since: 4.0
Constructors
- 
Constructor (TeecSharedMemory, unsigned long long, unsigned long long)
TeecRegisteredMemory(TeecSharedMemory memory, unsigned long long offset, unsigned long long size);
Attributes
- 
TeecSharedMemory shmReferred shared memory.Deprecated. Deprecated since 6.5. Since: 4.0 
- 
unsigned long long offsetOffset in shared memory (start of accessed block).Deprecated. Deprecated since 6.5. Since: 4.0 
- 
unsigned long long sizeSize of block in shared memory (length of the block).Deprecated. Deprecated since 6.5. Since: 4.0 
2.8. TeecTempMemory
Deprecated. Deprecated since 6.5.
  [Constructor(byte[] mem)]
  interface TeecTempMemory : TeecParameter {
    attribute byte[] mem;
  };
Since: 4.0
Attributes
- 
byte[]
                      memLocal memory block.Deprecated. Deprecated since 6.5. Since: 4.0 
2.9. TeecValue
Deprecated. Deprecated since 6.5.
  [Constructor(long a, long b)]
  interface TeecValue : TeecParameter {
    attribute long a;
    attribute long b;
  };
Since: 4.0
Attributes
- 
long aInteger number to be delivered.Deprecated. Deprecated since 6.5. Since: 4.0 
- 
long bInteger number to be delivered.Deprecated. Deprecated since 6.5. Since: 4.0 
2.10. TeecOpenSuccessCallback
Deprecated. Deprecated since 6.5.
  [Callback=FunctionOnly, NoInterfaceObject] interface TeecOpenSuccessCallback {
    void onsuccess(TeecSession session);
  };
Since: 4.0
Methods
- 
onsuccess
- 
Called when the session is opened successfully.Deprecated. Deprecated since 6.5. void onsuccess(TeecSession session); Since: 4.0 Parameters: - session: TeecSession object
 
2.11. TeecCommandSuccessCallback
Deprecated. Deprecated since 6.5.
  [Callback=FunctionOnly, NoInterfaceObject] interface TeecCommandSuccessCallback {
    void onsuccess(long cmd, TeecParameter[] params);
  };
Since: 4.0
Methods
- 
onsuccess
- 
Called when the command is done successfully.Deprecated. Deprecated since 6.5. void onsuccess(long cmd, TeecParameter[] params); Since: 4.0 Parameters: - cmd
- params: array of TeecParam objects
 
3. Related Feature
To guarantee that the CA is running on a device with TrustZone support, declare following feature in the config.
4. Full WebIDL
module LibTeec {
  Tizen implements LibTeecManagerObject;
};