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

Table of Contents

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)
TeecSharedMemory registerSharedMemory (unsigned long long addr, unsigned long size, TeecSharedMemoryFlags flags)
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

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

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

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

};
    Except as noted, this content - excluding the Code Examples - is licensed under Creative Commons Attribution 3.0 and all of the Code Examples contained herein are licensed under BSD-3-Clause.
    For details, see the Content License.