Secure Element Access
PUBLISHED
You can access secure elements in a device. You can access various secure elements, such as UICC and SIM cards, embedded secure elements, and secure SD cards.
This feature is supported in mobile and wearable applications only.
The main features of the Secure Element API include:
- Managing secure elements
You can manage secure elements by retrieving all the available secure element readers and receiving notifications of reader changes using the
SEService
interface (in mobile [1] and wearable [2] applications). You can also shut down secure elements. - Opening sessions and channels
You can open a session to connect to a secure element reader. Within a session, you can open basic or logical channels.
- Transmitting APDUs to the applet
You can transmit application protocol data units (APDU) to a secure element using a channel.
- Closing sessions and channels
When the channel or session is no longer needed, you can close them.
Prerequisites
To use the Secure Element API (in mobile [3] and wearable [4] applications), the application has to request permission by adding the following privilege to the config.xml
file:
<tizen:privilege name="http://tizen.org/privilege/secureelement"/>
Managing Secure Elements
To use secure elements in your application, you must learn to retrieve them and track changes in them:
-
To retrieve all the available secure element readers, use the
getReaders()
method of theSEService
interface (in mobile [1] and wearable [2] applications). The method registers theReaderArraySuccessCallback
interface (in mobile [5] and wearable [6] applications), which is invoked when the list of available secure element readers has been successfully retrieved.function success(readers) { for (var i = 0; i < readers.length; i++) { if (readers[i].isPresent) console.log('Reader Name: ' + readers[i].getName()); } } tizen.seService.getReaders(success, function(err) { /* Error handling */ });
-
To receive reader change notifications, use the
registerSEListener()
method of theSEService
interface:-
Define a listener using the
SEChangeListener
interface (in mobile [7] and wearable [8] applications):var setSEChange = { onSEReady: function(reader) { console.log(reader.getName() + ' is ready.'); }, onSENotReady: function(reader) { console.log(reader.getName() + ' is not ready.'); }, }
-
Register the listener:
var seListener = tizen.seService.registerSEListener(setSEChange);
-
-
To stop listening for the reader changes, use the
unregisterSEListener()
method:tizen.seService.unregisterSEListener(seListener);
Opening Sessions and Channels
To use secure elements in your application, you must learn to open sessions and channels:
-
To open a session, use the
openSession()
method of theReader
interface (in mobile [9] and wearable [10] applications). The method registers theSessionSuccessCallback
interface (in mobile [11] and wearable [12] applications), which is invoked when a session on a specific reader is opened.function successCB(session) { console.log('A session is open successfully'); } function errorCB(err) { /* Error handling */ } reader.openSession(successCB, errorCB);
-
To open a channel within a session:
-
Open a basic channel with the
openBasicChannel()
method of theSession
interface (in mobile [13] and wearable [14] applications). The method registers theChannelSuccessCallback
interface (in mobile [15] and wearable [16] applications), which is invoked when a channel is opened to communicate with a specific applet.function successCB(channel) { if (channel.isBasicChannel) console.log('A basic channel is opened successfully'); else console.log('A logical channel is opened successfully'); } function errorCB(err) { /* Error handling */ } /* This aid is for testing purposes for your applet */ session.openBasicChannel([0x1, 0x2, 0x3, 0x4, 0x5, 0x6, 0x7, 0x8, 0x9, 0xa, 0xb, 0xc, 0xd, 0xe], successCB, errorCB);
-
Open a logical channel with the
openLogicalChannel()
method of theSession
interface. As with a basic channel, the method registers theChannelSuccessCallback
interface.session.openLogicalChannel([0x1, 0x2, 0x3, 0x4, 0x5, 0x6, 0x7, 0x8, 0x9, 0xa, 0xb, 0xc, 0xd, 0xe], successCB, errorCB);
-
Transmitting APDUs to Secure Elements
To use secure elements in your application, you must learn to transmit application protocol data units (APDU) to secure elements:
-
To transmit an APDU command to a secure element, use the
transmit()
method of theChannel
interface (in mobile [17] and wearable [18] applications)./* APDU command is defined in ISO7816-4 */ channel.transmit(command, successCB, errorCB);
-
The
transmit()
method registers theTransmitSuccessCallback
interface (in mobile [19] and wearable [20] applications), which is invoked when a command has been successfully transmitted:function successCB(response) { console.log('An APDU is transmitted successfully. The response is ' + response); } function errorCB(err) { /* Error handling */ }
Closing Sessions and Channels
To use secure elements in your application, you must learn to close sessions and channels:
-
To close a specific channel, use the
close()
method of theChannel
interface (in mobile [17] and wearable [18] applications):channel.close();
-
To close all channels within a specific session, use the
closeChannels()
method of theSession
interface (in mobile [13] and wearable [14] applications):session.closeChannels();
-
To close a specific session, use the
close()
method of theSession
interface (in mobile [13] and wearable [14] applications):session.close();
-
To close all session for a specific reader, use the
closeSessions()
method of theReader
interface (in mobile [9] and wearable [10] applications):reader.closeSessions();