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, TeecRegisteredMemoryType
Deprecated. 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; };