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

Table of Contents


Summary of Interfaces and Methods

Interface Method

1. Type Definitions

1.1. TeecLoginMethod

This type denotes Session Login Method used in OpenSession.

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

This type denotes Value parameter.

Deprecated. Deprecated since 6.5.

  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.

Deprecated. Deprecated since 6.5.

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

Since: 4.0

1.4. TeecRegisteredMemoryType

This type denotes RegisteredMemory parameter.

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

This type denotes SharedMemory access direction.

Deprecated. Deprecated since 6.5.

  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 strig representation: f81d4fae-7dec-11d0-a765-00a0c91e6bf6

Deprecated. Deprecated since 6.5.

  typedef DOMString TeecUuid;

Since: 4.0

1.7. TeecTaskId

Background process id.

Deprecated. Deprecated since 6.5.

  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.

Deprecated. Deprecated since 6.5.

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

Since: 4.0

2.2. LibTeecManager

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

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

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

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

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

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

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

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

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);
  }
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.5. TeecSharedMemory

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

Deprecated. Deprecated since 6.5.

  [NoInterfaceObject] interface TeecSharedMemory {
    readonly attribute unsigned long long size;
    void setData(byte[] data, unsigned long long offset) raises(WebAPIException);
    void getData(byte[] data, unsigned long long offset) raises(WebAPIException);
  };

Since: 4.0

Attributes

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

    Deprecated. Deprecated since 6.5.

    Since: 4.0

Methods

setData
Convenient method to set some bytes in shared memory.

Deprecated. Deprecated since 6.5.

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.

Deprecated. Deprecated since 6.5.

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.

Deprecated. Deprecated since 6.5.

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

Since: 4.0

Attributes

  • DOMString type
    The 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

Registered memory parameter.

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 shm
    Referred shared memory.

    Deprecated. Deprecated since 6.5.

    Since: 4.0

  • unsigned long long offset
    Offset in shared memory (start of accessed block).

    Deprecated. Deprecated since 6.5.

    Since: 4.0

  • unsigned long long size
    Size of block in shared memory (length of the block).

    Deprecated. Deprecated since 6.5.

    Since: 4.0

2.8. TeecTempMemory

Temporary memory parameter.

Deprecated. Deprecated since 6.5.

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

Since: 4.0

Constructors

Constructor (byte[])
TeecTempMemory(byte[] mem);

Attributes

  • byte[] mem
    Local memory block.

    Deprecated. Deprecated since 6.5.

    Since: 4.0

2.9. TeecValue

Value parameter.

Deprecated. Deprecated since 6.5.

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

Since: 4.0

Constructors

Constructor (long, long)
TeecValue(long a, long b);

Attributes

  • long a
    Integer number to be delivered.

    Deprecated. Deprecated since 6.5.

    Since: 4.0

  • long b
    Integer number to be delivered.

    Deprecated. Deprecated since 6.5.

    Since: 4.0

2.10. TeecOpenSuccessCallback

The success callback to be invoked when session was opened.

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

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

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

Method tizen.systeminfo.getCapability() can be used in application runtime to check whether this API is supported.

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 {
      Tizen implements LibTeecManagerObject;
    };