For more information about how to use SecureElement API, see SecureElement Guide.
Since: 2.1
[NoInterfaceObject] interface SEServiceManagerObject { readonly attribute SEService seService; };
Tizen implements SEServiceManagerObject;
Since: 2.1
The tizen.seService object allows access to the functionality of the SecureElement API.
[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.
getReaders
void getReaders(ReaderArraySuccessCallback successCallback, optional ErrorCallback? errorCallback);
Since: 2.1
The ErrorCallback is launched with these error types:
Privilege level: public
Privilege: http://tizen.org/privilege/secureelement
Parameters:
Exceptions:
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
unsigned long registerSEListener(SEChangeListener listener);
Since: 2.1
Privilege level: public
Privilege: http://tizen.org/privilege/secureelement
Parameters:
Return value:
unsigned long An identifier used to clear the watch subscriptionExceptions:
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:
try { var seListener = tizen.seService.registerSEListener({ onSEReady:function(reader) { console.log (reader.getName() + "is ready."); }, onSENotReady:function(reader) { console.log (reader.getName() + "is not ready."); }}); } catch (err) { console.log (err.name + ": " + err.message); }
unregisterSEListener
void unregisterSEListener(unsigned long id);
Since: 2.1
Privilege level: public
Privilege: http://tizen.org/privilege/secureelement
Parameters:
Exceptions:
with error type InvalidValuesError, if any of the input parameters contains an invalid value.
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 seListener; //seListener obtained from registerSEListener try { tizen.seService.unregisterSEListener(seListener); } catch (err) { console.log (err.name + ": " + err.message); }
shutdown
void shutdown();
Since: 2.1
Privilege level: public
Privilege: http://tizen.org/privilege/secureelement
Exceptions:
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); }
[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.
Since: 2.1
getName
DOMString getName();
Since: 2.1
Privilege level: public
Privilege: http://tizen.org/privilege/secureelement
Return value:
DOMString The name of the readerExceptions:
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
void openSession(SessionSuccessCallback successCallback, optional ErrorCallback? errorCallback);
Since: 2.1
The ErrorCallback is launched with these error types:
Privilege level: public
Privilege: http://tizen.org/privilege/secureelement
Parameters:
Exceptions:
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
void closeSessions();
Since: 2.1
Privilege level: public
Privilege: http://tizen.org/privilege/secureelement
Exceptions:
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); }
[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
Since: 2.1
openBasicChannel
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:
Privilege level: public
Privilege: http://tizen.org/privilege/secureelement
Parameters:
Exceptions:
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
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:
Privilege level: public
Privilege: http://tizen.org/privilege/secureelement
Parameters:
Exceptions:
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:
var session; //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
byte[] getATR();
Since: 2.1
Privilege level: public
Privilege: http://tizen.org/privilege/secureelement
Return value:
byte[] The ATR of a Secure ElementExceptions:
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 session; //Session obtained from openSession callback try { var atr = session.getATR(); } catch (err) { console.log (err.name + ": " + err.message); }
close
void close();
Since: 2.1
Privilege level: public
Privilege: http://tizen.org/privilege/secureelement
Exceptions:
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 session; //Session obtained from openSession callback try { session.close(); } catch (err) { console.log (err.name + ": " + err.message); }
closeChannels
void closeChannels();
Since: 2.1
Privilege level: public
Privilege: http://tizen.org/privilege/secureelement
Exceptions:
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:
var session; //Session obtained from openSession callback try { session.closeChannels(); } catch (err) { console.log (err.name + ": " + err.message); }
[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
Since: 2.1
close
void close();
Since: 2.1
Privilege level: public
Privilege: http://tizen.org/privilege/secureelement
Exceptions:
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 channel; //Obtained from openLogicalChannel or openBasicChannel try { channel.close(); } catch (err) { console.log (err.name + ": " + err.message); }
transmit
void transmit(byte[] command, TransmitSuccessCallback successCallback, optional ErrorCallback? errorCallback);
Since: 2.1
Some commands that are not allowed to be sent are:
The ErrorCallback is launched with these error types:
Privilege level: public
Privilege: http://tizen.org/privilege/secureelement
Parameters:
Exceptions:
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
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>]
Privilege level: public
Privilege: http://tizen.org/privilege/secureelement
Return value:
bytes[] The data as returned by the application select command including the status wordsExceptions:
with error type SecurityError, if the application does not have the privilege to call this method.
[Callback, NoInterfaceObject] interface SEChangeListener { void onSEReady(Reader reader); void onSENotReady(Reader reader); };
Since: 2.1
It is used in SEService.registerSEListener().
onSEReady
void onSEReady(Reader reader);
Since: 2.1
Parameters:
onSENotReady
void onSENotReady(Reader reader);
Since: 2.1
Parameters:
[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().
onsuccess
void onsuccess(Reader[] readers);
Since: 2.1
Parameters:
[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().
onsuccess
void onsuccess(Session session);
Since: 2.1
Parameters:
[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().
onsuccess
void onsuccess(Channel channel);
Since: 2.1
Parameters:
[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().
To guarantee this application will run on a device with a Secure Element, add the below feature declaration to the config file:
module SecureElement { [NoInterfaceObject] interface SEServiceManagerObject { readonly attribute SEService seService; }; Tizen implements SEServiceManagerObject; [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); }; };