LibTeec API

The LibTeec API provides functionality to communicate with application executed in trusted environment.

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).

Since: 4.0

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
LibTeecManagerObject
LibTeecManager	TeecContext getContext (optional DOMString? name)
TeecContext	TeecTaskId openSession (TeecUuid taUUID, TeecLoginMethod loginMethod, unsigned long? connectionData, TeecParameter[] params, TeecOpenSuccessCallback successCallback, optional ? errorCallback) void revokeCommand (TeecTaskId id) TeecSharedMemory allocateSharedMemory (unsigned long size, TeecSharedMemoryFlags flags) TeecSharedMemory registerSharedMemory (unsigned long long addr, unsigned long size, TeecSharedMemoryFlags flags) void releaseSharedMemory (TeecSharedMemory shm)
TeecSession	void close () TeecTaskId invokeCommand (long cmd, TeecParameter[] params, TeecCommandSuccessCallback successCallback, optional ? errorCallback)
TeecSharedMemory	void setData (byte[] data, unsigned long long offset) void getData (byte[] data, unsigned long long offset)
TeecParameter
TeecRegisteredMemory
TeecTempMemory
TeecValue
TeecOpenSuccessCallback	void onsuccess (TeecSession session)
TeecCommandSuccessCallback	void onsuccess (long cmd, TeecParameter[] params)

1. Type Definitions

1.1. TeecLoginMethod

This type denotes Session Login Method used in OpenSession.

  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

This type denotes Value parameter.

  enum TeecValueType {
    "INPUT",
    "OUTPUT",
    "INOUT"
  };

Since: 4.0

INPUT - The Parameter is a TeecValue tagged as input.
OUTPUT - The Parameter is a TeecValue tagged as output.
INOUT - The Parameter is a TeecValue tagged as both input and output.

1.3. TeecTempMemoryType

This type denotes TempMemory parameter.

  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

This type denotes RegisteredMemory parameter.

  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.5. TeecSharedMemoryFlags

This type denotes SharedMemory access direction.

  enum TeecSharedMemoryFlags {
    "INPUT",
    "OUTPUT",
    "INOUT"
  };

Since: 4.0

INPUT - A flag indicates TeecSharedMemory can be read.
OUTPUT - A flag indicates TeecSharedMemory can be written.
INOUT - A flag indicates TeecSharedMemory can be read and written.

1.6. TeecUuid

This type contains a Universally Unique Resource Identifier (UUID) type as defined in RFC 4122. These UUID values are used to identify Trusted Applications. Example UUID string representation: f81d4fae-7dec-11d0-a765-00a0c91e6bf6

  typedef DOMString TeecUuid;

Since: 4.0

1.7. TeecTaskId

Background process id.

  typedef unsigned long TeecTaskId;

Since: 4.0

2. Interfaces

2.1. LibTeecManagerObject

The LibTeecObject interface gives access to the LibTeec API from the tizen.teec object.

  [NoInterfaceObject] interface LibTeecManagerObject {
    readonly attribute LibTeecManager teec;
  };

   implements LibTeecManagerObject;

Since: 4.0

2.2. LibTeecManager

The LibTeecManager interface provides methods to access Context and Session for GlobalPlatform libteec.

  [NoInterfaceObject] interface LibTeecManager {

    TeecContext getContext(optional DOMString? name) raises ();
  };

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.

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:

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

This type denotes a TEE Context, the main logical container linking a Client Application with a particular TEE.

  [NoInterfaceObject] interface TeecContext {
    TeecTaskId openSession(TeecUuid taUUID,
                           TeecLoginMethod loginMethod,
                           unsigned long? connectionData,
                           TeecParameter[] params,
                           TeecOpenSuccessCallback successCallback,
                           optional ? errorCallback) raises ();

    void revokeCommand(TeecTaskId id) raises ();

    TeecSharedMemory allocateSharedMemory(unsigned long size, TeecSharedMemoryFlags flags) raises ();

    TeecSharedMemory registerSharedMemory(unsigned long long addr, unsigned long size, TeecSharedMemoryFlags flags) raises ();

    void releaseSharedMemory(TeecSharedMemory shm) raises ();
  };

Methods

openSession

Open session with TA.

TeecTaskId openSession(TeecUuid taUUID, TeecLoginMethod loginMethod, unsigned long? connectionData, TeecParameter[] params, TeecOpenSuccessCallback successCallback, optional ? 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 successfully done.
errorCallback [optional] [nullable]: callback function triggered when error occurred.

Return value:

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.

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);
 }

allocateSharedMemory

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);
 }

registerSharedMemory

TeecSharedMemory registerSharedMemory(unsigned long long addr, unsigned long size, TeecSharedMemoryFlags flags);

Since: 4.0

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);
 }

releaseSharedMemory

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

This type denotes a TEE Session, the logical link between Client Application and a particular Trusted Application.

  [NoInterfaceObject] interface TeecSession {
    void close() raises ();

    TeecTaskId invokeCommand(long cmd,
                             TeecParameter[] params,
                             TeecCommandSuccessCallback successCallback,
                             optional ? errorCallback) raises ();
  };

Methods

close

Close session with TA.

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);
 }

invokeCommand

Send command to TA.

TeecTaskId invokeCommand(long cmd, TeecParameter[] params, TeecCommandSuccessCallback successCallback, optional ? 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 successfully done.
errorCallback [optional] [nullable]: callback function triggered when error occurred.

Return value:

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.5. TeecSharedMemory

Shared memory reference object. Instance of this object can be obtained from TeecSession with one of methods: allocateSharedMemory or registerSharedMemory

  [NoInterfaceObject] interface TeecSharedMemory {
    readonly attribute unsigned long long size;

    void setData(byte[] data, unsigned long long offset) raises ();

    void getData(byte[] data, unsigned long long offset) raises ();
  };

Since: 4.0

Attributes

readonly unsigned long long size
Size of this shared memory block.

Since: 4.0

Methods

setData

Convenient method to set some bytes in shared memory.

void setData(byte[] data, unsigned long long offset);

Since: 4.0

Parameters:

data: sequence of bytes (buffer size is data.length)
offset: offset in shared memory to start writing

Exceptions:

WebAPIException
- with error type TypeMismatchError, if a parameter has incorrect type.

getData

Convenient method to get some bytes from shared memory.

void getData(byte[] data, unsigned long long offset);

Since: 4.0

Parameters:

data: buffer for bytes (buffer size is data.length)
offset: offset in shared memory to start reading

Exceptions:

WebAPIException
- with error type TypeMismatchError, if a parameter has incorrect type.

2.6. TeecParameter

Abstract parameter type.

  [NoInterfaceObject] interface TeecParameter {
    attribute DOMString type;
  };

Since: 4.0

Attributes

DOMString type
The type of parameter - abstract class for all parameters. This can be one of TeecValueType, TeecTempMemoryType, TeecRegisteredMemoryType

Since: 4.0

2.7. TeecRegisteredMemory

Registered memory parameter.

  [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

TeecRegisteredMemory(TeecSharedMemory memory, unsigned long long offset, unsigned long long size);

Attributes

TeecSharedMemory shm
Referred shared memory.

Since: 4.0
unsigned long long offset
Offset in shared memory (start of accessed block).

Since: 4.0
unsigned long long size
Size of block in shared memory (length of the block).

Since: 4.0

2.8. TeecTempMemory

Temporary memory parameter.

  [Constructor(byte[] mem)]
  interface TeecTempMemory : TeecParameter {
    attribute byte[] mem;
  };

Since: 4.0

Constructors

TeecTempMemory(byte[] mem);

Attributes

byte[] mem
Local memory block.

Since: 4.0

2.9. TeecValue

Value parameter.

  [Constructor(long a, long b)]
  interface TeecValue : TeecParameter {
    attribute long a;
    attribute long b;
  };

Since: 4.0

Constructors

TeecValue(long a, long b);

Attributes

long a
Integer number to be delivered.

Since: 4.0
long b
Integer number to be delivered.

Since: 4.0

2.10. TeecOpenSuccessCallback

The success callback to be invoked when session was opened.

  [Callback=FunctionOnly, NoInterfaceObject]
  interface TeecOpenSuccessCallback {
    void onsuccess(TeecSession session);
  };

Since: 4.0

Methods

onsuccess

Called when the session is opened successfully.

void onsuccess(TeecSession session);

Since: 4.0

Parameters:

session: TeecSession object

2.11. TeecCommandSuccessCallback

The success callback to be invoked when command performed on TA is finished.

  [Callback=FunctionOnly, NoInterfaceObject]
  interface TeecCommandSuccessCallback {
    void onsuccess(long cmd, TeecParameter[] params);
  };

Since: 4.0

Methods

onsuccess

Called when the command is done successfully.

void onsuccess(long cmd, TeecParameter[] params);

Since: 4.0

Parameters:

cmd
params: array of TeecParam objects

3. Related Feature

You can check if this API is supported with tizen.systeminfo.getCapability() and decide enable/disable codes that need this API.

To guarantee that the CA is running on a device with TrustZone support, declare following feature in the config.

http://tizen.org/feature/security.tee

For more information, see Application Filtering.

4. Full WebIDL

module LibTeec {


  enum TeecLoginMethod {
    "PUBLIC",
    "USER",
    "GROUP",
    "APPLICATION"
  };

  enum TeecValueType {
    "INPUT",
    "OUTPUT",
    "INOUT"
  };

  enum TeecTempMemoryType {
    "INPUT",
    "OUTPUT",
    "INOUT"
  };

  enum TeecRegisteredMemoryType {
    "WHOLE",
    "PARTIAL_INPUT",
    "PARTIAL_OUTPUT",
    "PARTIAL_INOUT"
  };

  enum TeecSharedMemoryFlags {
    "INPUT",
    "OUTPUT",
    "INOUT"
  };

  typedef DOMString TeecUuid;

  typedef unsigned long TeecTaskId;

  [NoInterfaceObject] interface LibTeecManagerObject {
    readonly attribute LibTeecManager teec;
  };
   implements LibTeecManagerObject;

  [NoInterfaceObject] interface LibTeecManager {

    TeecContext getContext(optional DOMString? name) raises ();
  };

  [NoInterfaceObject] interface TeecContext {
    TeecTaskId openSession(TeecUuid taUUID,
                           TeecLoginMethod loginMethod,
                           unsigned long? connectionData,
                           TeecParameter[] params,
                           TeecOpenSuccessCallback successCallback,
                           optional ? errorCallback) raises ();

    void revokeCommand(TeecTaskId id) raises ();

    TeecSharedMemory allocateSharedMemory(unsigned long size, TeecSharedMemoryFlags flags) raises ();

    TeecSharedMemory registerSharedMemory(unsigned long long addr, unsigned long size, TeecSharedMemoryFlags flags) raises ();

    void releaseSharedMemory(TeecSharedMemory shm) raises ();
  };

  [NoInterfaceObject] interface TeecSession {
    void close() raises ();

    TeecTaskId invokeCommand(long cmd,
                             TeecParameter[] params,
                             TeecCommandSuccessCallback successCallback,
                             optional ? errorCallback) raises ();
  };

  [NoInterfaceObject] interface TeecSharedMemory {
    readonly attribute unsigned long long size;

    void setData(byte[] data, unsigned long long offset) raises ();

    void getData(byte[] data, unsigned long long offset) raises ();
  };

  [NoInterfaceObject] interface TeecParameter {
    attribute DOMString type;
  };

  [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;
  };

  [Constructor(byte[] mem)]
  interface TeecTempMemory : TeecParameter {
    attribute byte[] mem;
  };

  [Constructor(long a, long b)]
  interface TeecValue : TeecParameter {
    attribute long a;
    attribute long b;
  };

  [Callback=FunctionOnly, NoInterfaceObject]
  interface TeecOpenSuccessCallback {
    void onsuccess(TeecSession session);
  };

  [Callback=FunctionOnly, NoInterfaceObject]
  interface TeecCommandSuccessCallback {
    void onsuccess(long cmd, TeecParameter[] params);
  };

};

LibTeec API

Table of Contents

Summary of Interfaces and Methods

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

Methods

2.3. TeecContext

Methods

2.4. TeecSession

Methods

2.5. TeecSharedMemory

Attributes

Methods

2.6. TeecParameter

Attributes

2.7. TeecRegisteredMemory

Constructors

Attributes

2.8. TeecTempMemory

Constructors

Attributes

2.9. TeecValue

Constructors

Attributes

2.10. TeecOpenSuccessCallback

Methods

2.11. TeecCommandSuccessCallback

Methods

3. Related Feature

4. Full WebIDL