SecureElement API
For more information on the Secure Element features, see Secure Element Access Guide.
Since: 2.1
Table of Contents
- 1. Interfaces
- 1.1. SEServiceManagerObject
- 1.2. SEService
- 1.3. Reader
- 1.4. Session
- 1.5. Channel
- 1.6. SEChangeListener
- 1.7. ReaderArraySuccessCallback
- 1.8. SessionSuccessCallback
- 1.9. ChannelSuccessCallback
- 1.10. TransmitSuccessCallback
- 2. Related Feature
- 3. Full WebIDL
Summary of Interfaces and Methods
Interface | Method |
---|---|
SEServiceManagerObject | |
SEService |
unsigned long registerSEListener (SEChangeListener listener)
void unregisterSEListener (unsigned long id)
void shutdown ()
|
Reader |
DOMString getName ()
void closeSessions ()
|
Session |
void openBasicChannel (byte[] aid, ChannelSuccessCallback successCallback, optional ErrorCallback? errorCallback)
void openLogicalChannel (byte[] aid, ChannelSuccessCallback successCallback, optional ErrorCallback? errorCallback)
byte[] getATR ()
void close ()
void closeChannels ()
|
Channel |
void close ()
void transmit (byte[] command, TransmitSuccessCallback successCallback, optional ErrorCallback? errorCallback)
byte[] getSelectResponse ()
|
SEChangeListener |
void onSENotReady (Reader reader)
|
ReaderArraySuccessCallback | |
SessionSuccessCallback | |
ChannelSuccessCallback | |
TransmitSuccessCallback | void onsuccess (byte[] response) |
1. Interfaces
1.1. SEServiceManagerObject
[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 seServiceObject representing a secure element service manager.
Since: 2.1
1.2. 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); };
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"); }, onSEError: function(reader, error) { console.log(reader.getName() + ": error occurred: " + error.message); } }; 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); }
- WebAPIException
1.3. Reader
[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 isPresentBoolean 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); }
- WebAPIException
-
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); }
- WebAPIException
1.4. 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 isClosedBoolean 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); }
- WebAPIException
-
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); }
- WebAPIException
-
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); }
- WebAPIException
1.5. Channel
[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 isBasicChannelBoolean 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); }
- WebAPIException
-
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
[Callback, NoInterfaceObject] interface SEChangeListener { void onSEReady(Reader reader); void onSENotReady(Reader reader); void onSEError(Reader reader, WebAPIError error); };
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.
-
onSEError
-
Called when a Secure Element reader has an error.
void onSEError(Reader reader, WebAPIError error);
Since: 3.0
Parameters:
- reader: A Secure Element reader that error is related to.
- error: A Web API error.
1.7. ReaderArraySuccessCallback
[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
[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
[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
[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().
2. Related Feature
To guarantee this application will run on a device with a Secure Element, add the below feature declaration to the config file:
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); void onSEError(Reader reader, WebAPIError error); }; [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); }; };