SecureElement API

The Secure Element API provides functionality to communicate with applications in several Secure Elements. A Secure Element is a secure smart card chip. It can be a UICC/SIM, an embedded Secure Element, or a Secure SD card that is inserted in a device.

For more information on the Secure Element features, see Secure Element Access Guide.

Since: 2.1

Table of Contents

Summary of Interfaces and Methods

Interface Method
SEServiceManagerObject
SEService
void getReaders (ReaderArraySuccessCallback successCallback, optional ErrorCallback? errorCallback)
unsigned long registerSEListener (SEChangeListener listener)
void unregisterSEListener (unsigned long id)
void shutdown ()
Reader
DOMString getName ()
void openSession (SessionSuccessCallback successCallback, optional ErrorCallback? errorCallback)
Session
void openBasicChannel (byte[] aid, ChannelSuccessCallback successCallback, optional ErrorCallback? errorCallback)
void openLogicalChannel (byte[] aid, ChannelSuccessCallback successCallback, optional ErrorCallback? errorCallback)
byte[] getATR ()
void close ()
Channel
void close ()
void transmit (byte[] command, TransmitSuccessCallback successCallback, optional ErrorCallback? errorCallback)
SEChangeListener
void onSEReady (Reader reader)
void onSENotReady (Reader reader)
ReaderArraySuccessCallback
void onsuccess (Reader[] readers)
SessionSuccessCallback
void onsuccess (Session session)
ChannelSuccessCallback
void onsuccess (Channel channel)
TransmitSuccessCallback
void onsuccess (byte[] response)

1. Interfaces

1.1. SEServiceManagerObject

The SEServiceManagerObject interface defines what is instantiated by the Tizen object from the Tizen Platform. 
  [NoInterfaceObject] interface SEServiceManagerObject {
    readonly attribute SEService seService;
  };
  Tizen implements SEServiceManagerObject;

Since: 2.1

The tizen.seService object allows access to the functionality of the Secure Element API.

Attributes

  • readonly SEService seService
    Object representing a secure element service manager.

    Since: 2.1

1.2. SEService

The SEService interface provides access to the available Secure Element readers. 
  [NoInterfaceObject] interface SEService {
    void getReaders(ReaderArraySuccessCallback successCallback, optional ErrorCallback? errorCallback) raises(WebAPIException);
    unsigned long registerSEListener(SEChangeListener listener) raises(WebAPIException);
    void unregisterSEListener(unsigned long id) raises(WebAPIException);
    void shutdown() raises(WebAPIException);
  };

Since: 2.1

It provides access to the API functionalities through the tizen.seService interface.

Methods

getReaders
Gets all the available Secure Element readers. 
void getReaders(ReaderArraySuccessCallback successCallback, optional ErrorCallback? errorCallback);

Since: 2.1

The ErrorCallback is launched with these error types:

  • UnknownError - If any error occurs during retrieval.

Privilege level: public

Privilege: http://tizen.org/privilege/secureelement

Parameters:

  • successCallback: Callback method that is invoked when the list of available Secure Element readers has been successfully retrieved.
  • errorCallback [optional] [nullable]: Callback method that is invoked when an error occurs.

Exceptions:

  • WebAPIException

    • with error type TypeMismatchError, if the input parameter is not compatible with the expected type for that parameter.

    • with error type SecurityError, if the application does not have the privilege to call this method.

Code example:

try
{
  function success(readers)
  {
    for (var i = 0; i < readers.length; i++)
    {
      if (readers[i].isPresent)
      {
        console.log("Reader name: " + readers[i].getName());
      }
    }
  }
  function error(err)
  {
    console.log(err.name + ": " + err.message);
  }
  tizen.seService.getReaders(success, error);
}
catch (err)
{
  console.log(err.name + ": " + err.message);
}
registerSEListener
Registers a callback function that is invoked when an available Secure Element reader is detected. 
unsigned long registerSEListener(SEChangeListener listener);

Since: 2.1

Privilege level: public

Privilege: http://tizen.org/privilege/secureelement

Parameters:

  • listener: Listener to be called when a Secure Element reader is detected, lost or has an error.

Return value:

    unsigned long: An identifier used to clear the watch subscription.

Exceptions:

  • WebAPIException

    • with error type TypeMismatchError, if the input parameter is not compatible with the expected type for that parameter.

    • with error type SecurityError, if the application does not have the privilege to call this method.

    • with error type UnknownError, if any other error occurs.

Code example:

var listener =
{
  onSEReady: function(reader)
  {
    console.log(reader.getName() + " is ready");
  },
  onSENotReady: function(reader)
  {
    console.log(reader.getName() + " is not ready");
  }
};

try
{
  var seListener = tizen.seService.registerSEListener(listener);
}
catch (err)
{
  console.log(err.name + ": " + err.message);
}
unregisterSEListener
Unregisters the listener from notifying any detection of an available Secure Element reader. 
void unregisterSEListener(unsigned long id);

Since: 2.1

Calling this function has no effect if there is no listener with given id.

Privilege level: public

Privilege: http://tizen.org/privilege/secureelement

Parameters:

  • id: A subscription identifier that is returned by the registerSEListener() method.

Exceptions:

  • WebAPIException

    • with error type SecurityError, if the application does not have the privilege to call this method.

    • with error type UnknownError, if any other error occurs.

Code example:

/* Variable seListener obtained from registerSEListener. */
try
{
  tizen.seService.unregisterSEListener(seListener);
}
catch (err)
{
  console.log(err.name + ": " + err.message);
}
shutdown
Shuts down Secure Elements after releasing all resources. 
void shutdown();

Since: 2.1

Privilege level: public

Privilege: http://tizen.org/privilege/secureelement

Exceptions:

  • WebAPIException

    • with error type SecurityError, if the application does not have the privilege to call this method.

    • with error type UnknownError, if any other error occurs.

Code example:

try
{
  tizen.seService.shutdown();
}
catch (err)
{
  console.log(err.name + ": " + err.message);
}

1.3. Reader

The Reader interface that is connected to this device. 
  [NoInterfaceObject] interface Reader {
    readonly attribute boolean isPresent;
    DOMString getName() raises(WebAPIException);
    void openSession(SessionSuccessCallback successCallback, optional ErrorCallback? errorCallback) raises(WebAPIException);
    void closeSessions() raises(WebAPIException);
  };

Since: 2.1

This interface offers methods to control sessions on the reader.

Attributes

  • readonly boolean isPresent
    Boolean value that indicates whether a Secure Element is present on a reader.

    Since: 2.1

Methods

getName
Gets the reader's name. 
DOMString getName();

Since: 2.1

Privilege level: public

Privilege: http://tizen.org/privilege/secureelement

Return value:

    DOMString: The name of the reader.

Exceptions:

  • WebAPIException

    • with error type SecurityError, if the application does not have the privilege to call this method.

    • with error type UnknownError, if any other error occurs.

Code example:

try
{
  function success(readers)
  {
    for (var i = 0; i < readers.length; i++)
    {
      if (readers[i].isPresent)
      {
        console.log("Reader name: " + readers[i].getName());
      }
    }
  }
  function error(err)
  {
    console.log(err.name + ": " + err.message);
  }
  tizen.seService.getReaders(success, error);
}
catch (err)
{
  console.log(err.name + ": " + err.message);
}
openSession
Opens a session on a reader. 
void openSession(SessionSuccessCallback successCallback, optional ErrorCallback? errorCallback);

Since: 2.1

The ErrorCallback is launched with these error types:

  • IOError - An error occurred in communication with the Secure Element in this reader.
  • InvalidStateError - If a Secure Element is not present on this reader.
  • UnknownError - If any other error occurs.

Privilege level: public

Privilege: http://tizen.org/privilege/secureelement

Parameters:

  • successCallback: Callback method that is invoked when a session has been successfully opened.
  • errorCallback [optional] [nullable]: Callback method that is invoked when an error occurs.

Exceptions:

  • WebAPIException

    • with error type TypeMismatchError, if the input parameter is not compatible with the expected type for that parameter.

    • with error type SecurityError, if the application does not have the privilege to call this method.

Code example:

try
{
  function success(session)
  {
    console.log("Open Session Success: " + !session.isClosed);
  }
  function error(err)
  {
    console.log(err.name + ": " + err.message);
  }
  reader.openSession(success, error);
}
catch (err)
{
  console.log(err.name + ": " + err.message);
}
closeSessions
Closes all sessions opened on a reader. 
void closeSessions();

Since: 2.1

Privilege level: public

Privilege: http://tizen.org/privilege/secureelement

Exceptions:

  • WebAPIException

    • with error type SecurityError, if the application does not have the privilege to call this method.

    • with error type UnknownError in any other error case.

Code example:

try
{
  reader.closeSessions();
}
catch (err)
{
  console.log(err.name + ": " + err.message);
}

1.4. Session

The Session interface is connected to one of the readers and offers methods to control channels in a session. 
  [NoInterfaceObject] interface Session {
    readonly attribute boolean isClosed;
    void openBasicChannel(byte[] aid, ChannelSuccessCallback successCallback, optional ErrorCallback? errorCallback)
                          raises(WebAPIException);
    void openLogicalChannel(byte[] aid, ChannelSuccessCallback successCallback, optional ErrorCallback? errorCallback)
                            raises(WebAPIException);
    byte[] getATR() raises(WebAPIException);
    void close() raises(WebAPIException);
    void closeChannels() raises(WebAPIException);
  };

Since: 2.1

Attributes

  • readonly boolean isClosed
    Boolean value that indicates whether a session is closed.

    Since: 2.1

Methods

openBasicChannel
Opens a basic channel in a session. The basic channel (defined in the ISO7816-4 specification) is opened by default and its channel ID is 0. Once this channel has been opened by an application, it is considered to be "locked" to other applications, and they cannot open any channel, until the basic channel is closed. Some Secure Elements might always deny opening a basic channel. 
void openBasicChannel(byte[] aid, ChannelSuccessCallback successCallback, optional ErrorCallback? errorCallback);

Since: 2.1

The optional select response data of an applet can be retrieved with byte[] getSelectResponse().

The ErrorCallback is launched with these error types:

  • IOError - If an error occurs while communicating with the Secure Element in the reader.
  • SecurityError - If access to this AID or the default application on this session is not allowed .
  • InvalidStateError - If this session is closed.
  • NotFoundError - If the application of the AID does not exist in the Secure Element.
  • NoChannelError - If basic channel is unavailable.
  • UnknownError - If any other error occurs.

Privilege level: public

Privilege: http://tizen.org/privilege/secureelement

Parameters:

  • aid: ID of the applet to select on this channel
    If the array is empty, the default applet is selected in this session.
  • successCallback: Callback method that is invoked when a basic channel has been successfully opened.
  • errorCallback [optional] [nullable]: Callback method that is invoked when an error occurs.

Exceptions:

  • WebAPIException

    • with error type TypeMismatchError, if the input parameter is not compatible with the expected type for that parameter.

    • with error type InvalidValuesError, if the AID's length is not within the limit: 5 to 16(inclusive).

    • with error type SecurityError, if the application does not have the privilege to call this method.

Code example:

try
{
  function successChannel(channel)
  {
    if (channel.isBasicChannel)
    {
      console.log("Basic channel is opened");
    }
    else
    {
      console.log("Logical channel is opened");
    }
  }
  function errorChannel(err)
  {
    console.log("openBasicChannel error: " + err.name + ": " + err.message);
  }
  function successSession(session)
  {
    console.log("Open session success: " + !session.isClosed);
    /* This AID is for test. Use AID for your applet in secure element. */
    session.openBasicChannel([0x1, 0x2, 0x3, 0x4, 0x5, 0x6, 0x7, 0x8, 0x9, 0xa, 0xb, 0xc, 0xd, 0xe],
        successChannel, errorChannel);
  }
  function errorSession(err)
  {
    console.log("openSession error: " + err.name + ": " + err.message);
  }
  reader.openSession(successSession, errorSession);
}
catch (err)
{
  console.log(err.name + ": " + err.message);
}
openLogicalChannel
Opens a logical channel in a session by the specified applet ID. The logical channel is defined in the ISO7816-4 specification. 
void openLogicalChannel(byte[] aid, ChannelSuccessCallback successCallback, optional ErrorCallback? errorCallback);

Since: 2.1

The optional select response data of an applet can be retrieved with byte[] getSelectResponse().

The ErrorCallback is launched with these error types:

  • IOError - If an error occurs while communicating with the Secure Element in the reader.
  • SecurityError - If access to this AID or the default application in this session is not allowed.
  • InvalidStateError - If this session is closed.
  • NotFoundError - If the application of the AID does not exist in the Secure Element.
  • NoChannelError - If logical channel is unavailable.
  • UnknownError - If any other error occurs.

Privilege level: public

Privilege: http://tizen.org/privilege/secureelement

Parameters:

  • aid: ID of the applet to select on this channel
    If the array is empty, the default application is selected in this session.
  • successCallback: Callback method that is invoked when a logical channel has been successfully opened.
  • errorCallback [optional] [nullable]: Callback method that is invoked when an error occurs.

Exceptions:

  • WebAPIException

    • with error type TypeMismatchError, if the input parameter is not compatible with the expected type for that parameter.

    • with error type InvalidValuesError, if the AID's length is not within the limit: 5 to 16(inclusive).

    • with error type SecurityError, if the application does not have the privilege to call this method.

Code example:

/* Variable session obtained from openSession callback. */
try
{
  function successChannel(channel)
  {
    if (channel.isBasicChannel)
    {
      console.log("Basic channel is opened");
    }
    else
    {
      console.log("Logical channel is opened");
    }
  }
  function errorChannel(err)
  {
    console.log("openLogicalChannel error: " + err.name + ": " + err.message);
  }

  /* This AID is for test. Use AID for your applet in secure element. */
  session.openLogicalChannel([0x1, 0x2, 0x3, 0x4, 0x5, 0x6, 0x7, 0x8, 0x9, 0xa, 0xb, 0xc, 0xd, 0xe],
      successChannel, errorChannel);
}
catch (err)
{
  console.log(err.name + ": " + err.message);
}
getATR
Gets the answer to reset(ATR) of a Secure Element. 
byte[] getATR();

Since: 2.1

Privilege level: public

Privilege: http://tizen.org/privilege/secureelement

Return value:

    byte[]: The ATR of a Secure Element.

Exceptions:

  • WebAPIException

    • with error type SecurityError, if the application does not have the privilege to call this method.

    • with error type UnknownError, if any other error occurs.

Code example:

/* Variable session obtained from openSession callback. */
try
{
  var atr = session.getATR();
}
catch (err)
{
  console.log(err.name + ": " + err.message);
}
close
Closes a session. 
void close();

Since: 2.1

Privilege level: public

Privilege: http://tizen.org/privilege/secureelement

Exceptions:

  • WebAPIException

    • with error type SecurityError, if the application does not have the privilege to call this method.

    • with error type UnknownError, if any other error occurs.

Code example:

/* Variable session obtained from openSession callback. */
try
{
  session.close();
}
catch (err)
{
  console.log(err.name + ": " + err.message);
}
closeChannels
Closes all channels on this session. 
void closeChannels();

Since: 2.1

Privilege level: public

Privilege: http://tizen.org/privilege/secureelement

Exceptions:

  • WebAPIException

    • with error type SecurityError, if the application does not have the privilege to call this method.

    • with error type UnknownError in any other error case.

Code example:

/* Variable session obtained from openSession callback. */
try
{
  session.closeChannels();
}
catch (err)
{
  console.log(err.name + ": " + err.message);
}

1.5. Channel

The Channel interface is open to a Secure Element and offers methods to send Application Protocol Data Units(APDU) to the Secure Element. The channel is defined in the ISO7816-4. 
  [NoInterfaceObject] interface Channel {
    readonly attribute boolean isBasicChannel;
    void close() raises(WebAPIException);
    void transmit(byte[] command, TransmitSuccessCallback successCallback, optional ErrorCallback? errorCallback)
                  raises(WebAPIException);
    byte[] getSelectResponse() raises(WebAPIException);
  };

Since: 2.1

Attributes

  • readonly boolean isBasicChannel
    Boolean value that indicates whether it is a basic channel.

    Since: 2.1

Methods

close
Closes a channel. 
void close();

Since: 2.1

Privilege level: public

Privilege: http://tizen.org/privilege/secureelement

Exceptions:

  • WebAPIException

    • with error type SecurityError, if the application does not have the privilege to call this method.

    • with error type UnknownError, if any other error occurs.

Code example:

/* Variable channel obtained from openLogicalChannel or openBasicChannel. */
try
{
  channel.close();
}
catch (err)
{
  console.log(err.name + ": " + err.message);
}
transmit
Transmits an APDU command to a Secure Element. The APDU command is defined in ISO7816-4. 
void transmit(byte[] command, TransmitSuccessCallback successCallback, optional ErrorCallback? errorCallback);

Since: 2.1

Some commands that are not allowed to be sent are:

  • MANAGE_CHANNEL commands.
  • SELECT by DF Name (p1=04).
  • The commands that CLA bytes with channel numbers are de-masked.

The ErrorCallback is launched with these error types:

  • InvalidValuesError - If the command contain an invalid value.
  • IOError - An error occurred while communicating with the Secure Element in the reader.
  • SecurityError - If the command is not allowed.
  • InvalidStateError - If this channel is closed.
  • UnknownError - If any other error occurs.

Privilege level: public

Privilege: http://tizen.org/privilege/secureelement

Parameters:

  • command: APDU command to transmit through this channel.
  • successCallback: Callback method that is invoked when a command has been successfully transmitted.
  • errorCallback [optional] [nullable]: Callback method that is invoked when an error occurs.

Exceptions:

  • WebAPIException

    • with error type TypeMismatchError, if the input parameter is not compatible with the expected type for that parameter.

    • with error type SecurityError, if the application does not have the privilege to call this method.

getSelectResponse
Gets the data as received from the application select command including the status words. 
byte[] getSelectResponse();

Since: 2.3

When opening a channel, when an applet ID of secure element is selected, a response is generated to the select command. This method retrieves the response.

The return value is a byte array containing the data bytes in the following order:

[<first data byte>, ..., <last data byte>, <status word1>, <status word2>]

  • Only the status words are returned if the application select command has no returned data.
  • Null if an application select command has not been performed or the selection response can not be retrieved by the reader implementation.

Privilege level: public

Privilege: http://tizen.org/privilege/secureelement

Return value:

    byte[]: The data as returned by the application select command including the status words.

Exceptions:

  • WebAPIException

    • with error type SecurityError, if the application does not have the privilege to call this method.

1.6. SEChangeListener

The SEChangeListener interface provides the success callback that is invoked when a Secure Element reader is detected or lost. 
  [Callback, NoInterfaceObject] interface SEChangeListener {
    void onSEReady(Reader reader);
    void onSENotReady(Reader reader);
  };

Since: 2.1

It is used in SEService.registerSEListener().

Methods

onSEReady
Called when a Secure Element reader is detected. 
void onSEReady(Reader reader);

Since: 2.1

Parameters:

  • reader: Newly detected Secure Element reader.
onSENotReady
Called when a Secure Element reader is lost. 
void onSENotReady(Reader reader);

Since: 2.1

Parameters:

  • reader: Lost Secure Element reader.

1.7. ReaderArraySuccessCallback

The ReaderArraySuccessCallback callback interface provides a success callback that is invoked when a list of available Secure Element readers is retrieved. 
  [Callback=FunctionOnly, NoInterfaceObject] interface ReaderArraySuccessCallback {
    void onsuccess(Reader[] readers);
  };

Since: 2.1

It specifies a success method with an array of Reader objects as an input parameter. It is used in asynchronous operations such as SEService.getReaders().

Methods

onsuccess
Called when an asynchronous call completes successfully. 
void onsuccess(Reader[] readers);

Since: 2.1

Parameters:

  • readers: List of available Secure Element readers.

1.8. SessionSuccessCallback

The SessionSuccessCallback interface specifies the success callback that is invoked when a session on a specific reader is open. 
  [Callback=FunctionOnly, NoInterfaceObject] interface SessionSuccessCallback {
    void onsuccess(Session session);
  };

Since: 2.1

This callback interface specifies a success method with a Session object as an input parameter. It is used in asynchronous operations such as Reader.openSession().

Methods

onsuccess
Called when an asynchronous call completes successfully. 
void onsuccess(Session session);

Since: 2.1

Parameters:

  • session: Open session.

1.9. ChannelSuccessCallback

The ChannelSuccessCallback interface specifies the success callback that is invoked when a channel is open to communicate with a specific applet. 
  [Callback=FunctionOnly, NoInterfaceObject] interface ChannelSuccessCallback {
    void onsuccess(Channel channel);
  };

Since: 2.1

This callback interface specifies a success method with a Channel object as an input parameter. It is used in asynchronous operations such as Session.openBasicChannel() or Session.openLogicalChannel().

Methods

onsuccess
Called when an asynchronous call completes successfully. 
void onsuccess(Channel channel);

Since: 2.1

Parameters:

  • channel: Open channel.

1.10. TransmitSuccessCallback

The TransmitSuccessCallback interface specifies the success callback that is invoked when Channel.transmit() completes successfully. 
  [Callback=FunctionOnly, NoInterfaceObject] interface TransmitSuccessCallback {
    void onsuccess(byte[] response);
  };

Since: 2.1

This callback interface specifies a success method with an array of bytes as an input parameter. It is used in Channel.transmit().

Methods

onsuccess
Called when an asynchronous call completes successfully. 
void onsuccess(byte[] response);

Since: 2.1

Parameters:

  • response: APDU command response that is transmitted on a channel.

2. Related Feature

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

To guarantee this application will run on a device with a Secure Element, add the below feature declaration to the config file:

  • http://tizen.org/feature/network.secure_element

    • For more information, see Application Filtering.

    3. Full WebIDL

    module SecureElement {
  Tizen implements SEServiceManagerObject;
  [NoInterfaceObject] interface SEServiceManagerObject {
    readonly attribute SEService seService;
  };
  [NoInterfaceObject] interface SEService {
    void getReaders(ReaderArraySuccessCallback successCallback, optional ErrorCallback? errorCallback) raises(WebAPIException);
    unsigned long registerSEListener(SEChangeListener listener) raises(WebAPIException);
    void unregisterSEListener(unsigned long id) raises(WebAPIException);
    void shutdown() raises(WebAPIException);
  };
  [NoInterfaceObject] interface Reader {
    readonly attribute boolean isPresent;
    DOMString getName() raises(WebAPIException);
    void openSession(SessionSuccessCallback successCallback, optional ErrorCallback? errorCallback) raises(WebAPIException);
    void closeSessions() raises(WebAPIException);
  };
  [NoInterfaceObject] interface Session {
    readonly attribute boolean isClosed;
    void openBasicChannel(byte[] aid, ChannelSuccessCallback successCallback, optional ErrorCallback? errorCallback)
                          raises(WebAPIException);
    void openLogicalChannel(byte[] aid, ChannelSuccessCallback successCallback, optional ErrorCallback? errorCallback)
                            raises(WebAPIException);
    byte[] getATR() raises(WebAPIException);
    void close() raises(WebAPIException);
    void closeChannels() raises(WebAPIException);
  };
  [NoInterfaceObject] interface Channel {
    readonly attribute boolean isBasicChannel;
    void close() raises(WebAPIException);
    void transmit(byte[] command, TransmitSuccessCallback successCallback, optional ErrorCallback? errorCallback)
                  raises(WebAPIException);
    byte[] getSelectResponse() raises(WebAPIException);
  };
  [Callback, NoInterfaceObject] interface SEChangeListener {
    void onSEReady(Reader reader);
    void onSENotReady(Reader reader);
  };
  [Callback=FunctionOnly, NoInterfaceObject] interface ReaderArraySuccessCallback {
    void onsuccess(Reader[] readers);
  };
  [Callback=FunctionOnly, NoInterfaceObject] interface SessionSuccessCallback {
    void onsuccess(Session session);
  };
  [Callback=FunctionOnly, NoInterfaceObject] interface ChannelSuccessCallback {
    void onsuccess(Channel channel);
  };
  [Callback=FunctionOnly, NoInterfaceObject] interface TransmitSuccessCallback {
    void onsuccess(byte[] response);
  };
};
    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.