6 SIM Toolkit Framework

03.193GPPRelease 1999Subscriber Identity Module Application Programming Interface (SIM API) for Java CardTS

6.1 Overview

The SIM API shall consist of APIs for TS 11.14 [3] (pro-active functions) and TS 11.11 [2] (transport functions).

Figure 2: SIM Toolkit Framework functional description

In this model, the GSM data field structure is viewed as a series of data objects to the API. In the physical model of course, they may still be stored in elementary fields, but classes will access these data as part of the objects within those classes.

6.2 Applet Triggering

The application triggering portion of the SIM Toolkit Framework is responsible for the activation of toolkit applets, based on the APDU received by the GSM application.

Figure 3: toolkit applet triggering diagram

The ME shall not be adversely affected by the presence of applets on the SIM card. For instance a syntactically correct Envelope shall not result in an error status word in case of a failure of an applet. The only application as seen by the ME is the SIM application. As a result, a toolkit applet may throw an exception, but this error will not be sent to the ME.

The difference between a Java Card applet and a Toolkit applet is that the latter does not handle APDUs directly. It will handle higher level messages. Furthermore the execution of a method could span over multiple APDUs, in particular, the proactive protocol commands (Fetch, Terminal Response).

As seen above, when the GSM applet is the selected application and when a toolkit applet is triggered the select() method of the toolkit applet shall not be launched since the toolkit applet itself is not really selected.

Here after are the events that can trigger a toolkit applet :

EVENT_PROFILE_DOWNLOAD

Upon reception of the Terminal Profile command by the SIM, the SIM Toolkit Framework stores the ME profile and then triggers the registered toolkit applet which may want to change their registry. A toolkit applet may not be able to issue a proactive command.

EVENT_MENU_SELECTION, EVENT_MENU_SELECTION_HELP_REQUEST

A toolkit applet might be activated upon selection in the ME’s menu by the user, or request help on this specific menu.

In order to allow the user to choose in a menu, the SIM Toolkit Framework shall have previously issued a SET UP MENU proactive command. When a toolkit applet changes a menu entry of its registry object, the SIM Toolkit Framework shall dynamically update the menu stored in the ME during the current card session. The SIM Toolkit Framework shall use the data of the EFsume file when issuing the SET UP MENU proactive command.

The positions of the toolkit applet menu entries in the item list, the requested item identifiers and the associated limits (e.g. maximum length of item text string) are defined at the loading of the toolkit applet.

If at least one toolkit applet registers to EVENT_MENU_SELECTION_HELP_REQUEST, the SET UP MENU proactive command sent by the SIM Toolkit Framework shall indicate to the ME that help information is available.A toolkit applet registered for one or more menu entries, may be triggered by the event EVENT_MENU_SELECTION_HELP_REQUEST, even if it is not registered to this event. A toolkit applet registered for one or more menu entries should provide help information.

EVENT_FORMATTED_SMS_PP_ENV, EVENT_UNFORMATTED_SMS_PP_ENV,
EVENT_FORMATTED_SMS_PP_UPD, EVENT_UNFORMATTED_SMS_PP_UPD

A toolkit applet can be activated upon the reception of a short message.

There are two ways for a card to receive an SMS : via the Envelope SMS-PP Data Download or the Update Record EFsms instruction.

The reception of the SMS by the toolkit applet cannot be guaranteed for the Update Record EFsms instruction.

The received SMS may be :
– formatted according to TS 03.48[4] or an other protocol to identify explicitly the toolkit applet for which the message is sent ;
– unformatted or using a toolkit applet specific protocol the SIM Toolkit Framework will pass this data to all registered toolkit applets.

EVENT_FORMATTED_SMS_PP_ENV

This event is triggered by an envelope APDU containing an SMS_DATADOWNLOAD BER TLV with an SMS_TPDU simple TLV according to TS 03.48[4].

The SIM Toolkit Framework shall:

  • verify the TS 03.48[4] security of the SMS TPDU ;
  • trigger the toolkit applet registered with the corresponding TAR defined at applet loading;
  • take the optional Application Data posted by the triggered toolkit applet if present;
  • secure and send the response packet.

The toolkit applet will only be triggered if the TAR is known and the security verified, application data will also be deciphered.

EVENT_UNFORMATTED_SMS_PP_ENV

The registered toolkit applets will be triggered by this event and get the data transmitted in the APDU envelope SMS_DATADOWNLOAD.

But only the first toolkit applet triggered will be able to send back a response as defined by the rules in chapter 6.6.

EVENT_FORMATTED_SMS_PP_UPD

This event is triggered by Update Record EFsms with an SMS TP-UD field formatted according to TS 03.48[4].

The SIM Toolkit Framework shall :

  • update the EFsms file with the data received, it is then up to the receiving toolkit applet to change the SMS stored in the file (i.e. the toolkit applet need to have access to the EFsms file)
  • verify the TS 03.48[4] security of the SMS TPDU ;
  • convert the Update Record EFsms in a TLV List, an EnvelopeHandler ;
  • trigger the toolkit applet registered with the corresponding TAR defined at applet loading;

The Update Record EFsms APDU shall be converted in a TLV list as defined below :

UPDATE RECORD APDU

nb bytes

Handler TLV LIST

size

CLA, INS

2

specific event

1

P1,P2

2

device Identity rec-number

1

P3 = 176

1

1

status

1

device Identity rec-status

1

TS-SCA (RP-OA)

<= 12

Address

Y

SMS TPDU

var

SMS TPDU

Y

padding bytes

var

Y

The EnvelopeHandler provided to the applet shall:

  • return BTAG_SMS_PP_DOWNLOAD to the getEnvelopeTag() method call;
  • return the Simple TLV list length to the getLength() method call;
  • contain the Simple TLV list :

EnvelopeHandler TLV List

Device identities

Address

SMS TPDU

The applet should use the findTLV() methods to get each Simple TLV.

The Device Identity Simple TLV is used to store the information about the absolute record number in the EFsms file and the value of the EFsms record status byte, and formatted as defined below:

Device identities Simple TLV

Device identities tag

length = 02

Absolute Record Number

Record Status

With the absolute record number the toolkit applet can update EFsms in absolute mode to change the received SMS in a readable text.

EVENT_UNFORMATTED_SMS_PP_UPD

The SIM Toolkit Framework will first update the EFsms file, convert the received APDU as described above, and then trigger all the registered toolkit applets. All of them may modify the content of EFsms (i.e. the toolkit applets need to have access to the EFsms file).

EVENT_FORMATTED_SMS_CB, EVENT_UNFORMATTED_SMS_CB

When the ME receives a new cell broadcast message, the cell broadcast page may be passed to the SIM using the envelope command according to the content of the EFCBMID file. E.g. the application may then read the message and extract a meaningful piece of information which could be displayed to the user, for instance.

The received cell broadcast page can be either:
– formatted according to TS 03.48 [4] or an other protocol to identify explicitly the toolkit applet for which the message is sent ;
– unformatted or using a toolkit applet specific protocol the SIM Toolkit Framework will pass this data to all registered toolkit applets.

EVENT_FORMATTED_SMS_CB

This event is triggered by an envelope APDU containing an CELL_BROADCAST_DATADOWNLOAD BER TLV with a Cell Broadcast Page simple TLV according to TS 03.48 [4].

The SIM Toolkit Framework shall:

  • verify the TS 03.48[4] security of the Cell Broadcast Page;
  • trigger the toolkit applet registered with the corresponding TAR defined at applet loading.

The toolkit applet will only be triggered if the TAR is known and the security verified, application data will also be deciphered.

The TAR value is the same as the one used in the events EVENT_FORMATTED_SMS_PP_ENV and EVENT_FORMATTED_SMS_PP_UPD.

EVENT_UNFORMATTED_SMS_CB

The registered toolkit applets will be triggered by this event and get the data transmitted in the APDU envelope CELL_BROADCAST_DATADOWNLOAD.

EVENT_CALL_CONTROL_BY_SIM

When the SIM is in call control mode and when the user dials a number, this number is passed to the SIM. Only one toolkit applet can handle the answer to this command: call barred, modified or accepted.

EVENT_EVENT_DOWNLOAD_MT_CALL, EVENT_EVENT_DOWNLOAD_CALL_CONNECTED, EVENT_EVENT_DOWNLOAD_CALL_DISCONNECTED, EVENT_EVENT_DOWNLOAD_LOCATION_STATUS, EVENT_EVENT_DOWNLOAD_USER_ACTIVITY, EVENT_EVENT_DOWNLOAD_IDLE_SCREEN_AVAILABLE,
EVENT_EVENT_DOWNLOAD_CARD_READER_STATUS,

EVENT_EVENT_DOWNLOAD_LANGUAGE_SELECTION,
EVENT_EVENT_DOWNLOAD_BROWSER_TERMINATION

The toolkit applet will be triggered by the registered event download trigger, upon reception of the corresponding Envelope command.

In order to allow the toolkit applet to be triggered by these events, the SIM Toolkit Framework shall have previously issued a SET UP EVENT LIST proactive command. When a toolkit applet changes one or more of these requested events of its registry object, the SIM Toolkit Framework shall dynamically update the event list stored in the ME during the current card session.

EVENT_MO_SHORT_MESSAGE_CONTROL_BY_SIM

Before sending an SMS MO entered by the user, the SMS is submitted to the SIM. Only one toolkit applet can register to this event

EVENT_TIMER_EXPIRATION

At the registration to this event the toolkit applet gets the reference to its timer. The toolkit applet can then manage the timer, it will be triggered at the reception of the APDU Envelope TIMER EXPIRATION.

The SIM Toolkit Framework shall reply busy to this Envelope APDU if it cannot guaranty to trigger the corresponding toolkit applet.

EVENT_UNRECOGNIZED_ENVELOPE

The applet registered to this event shall be triggered by the framework if the BER-TLV tag contained in the ENVELOPE APDU is not defined in the associated release of TS 11.14 [3] and if no corresponding constant is defined in the list of the ToolkitConstants interface. The unrecognized Envelope event will allow a toolkit applet to handle the evolution of the TS 11.14 specification.

EVENT_STATUS_COMMAND

At reception of a STATUS APDU command, the SIM Toolkit Framework shall trigger the registered toolkit applet.

A range of events is reserved for proprietary usage (from –128 to –1). The use of these events will make the toolkit applet incompatible.

The toolkit applet shall be triggered for the registered events upon reception, and shall be able to access to the data associated to the event using the methods provided by the sim.toolkit.ViewHandler.EnvelopeHandler class.

The order of triggering the toolkit applet shall follow the priority level of each toolkit applet defined at its loading. If several toolkit applets have the same priority level, the last loaded toolkit applet takes precedence.

6.3 Registration

During it’s installation the toolkit applet shall register to the JCRE and the SIM Toolkit Framework so that it can be triggered by both selection mechanisms.

The toolkit applet will have to call the getEntry() method to get a reference to it’s registry and then to explicitly register to each event it requires.

The toolkit applet can change the events to which it is registered during its life cycle.

The toolkit applet will dynamically register itself to some event e.g. EVENT_MENU_SELECTION by calling the corresponding method e.g. initMenuEntry().

The API is described in the sim.toolkit.ToolkitRegistry class in Annex A.

6.4 Proactive command handling

The SIM application toolkit protocol (i.e. 91xx, Fetch, Terminal Response) is handled by the GSM applet and the Toolkit Handler, the toolkit applet shall not handle those events.

The SIM Toolkit Framework shall provide a reference of the sim.toolkit.ViewHandler.EditHandler.ProactiveHandler to the toolkit applet so that when the toolkit applet is triggered it can :

– initialise the current proactive command with the init() method ;

– append several Simple TLV as defined in TS 11.14 [3] to the current proactive command with the appendTLV() methods ;

– ask the SIM Toolkit Framework to send this proactive command to the ME and wait for the reply, with the send() method.

The GSM applet and the SIM Toolkit Framework shall handle the transmission of the proactive command to the ME, and the reception of the response. The SIM Toolkit Framework will then return in the toolkit applet just after the send() method. It shall then provide to the toolkit applet the sim.toolkit.ViewHandler.ProactiveResponseHandler, so that the toolkit applet can analyse the response.

The proactive command is sent to the ME as defined and constructed by the toolkit applet without any check of the SIM Toolkit Framework.

The toolkit applet shall not issue the following proactive commands : SET UP MENU, SET UP EVENT LIST, POLL INTERVAL, POLLING OFF ; as those are system proactive commands that will affect the services of the SIM Toolkit Framework.

The SIM Toolkit Framework cannot guarantee that if the SET UP IDLE MODE TEXT proactive command is used by a toolkit applet, another toolkit applet will not overwrite this text at a later stage.

6.5 Envelope response handling

To allow a toolkit applet to answer to some specific events (e.g. EVENT_CALL_CONTROL_BY_SIM) the SIM Toolkit Framework shall provide the sim.toolkit.ViewHandler.EditHandler.EnvelopeResponseHandler.

The toolkit applet can then post a response to some events with the post() or the postAsBERTLV() methods, the toolkit applet can continue it’s processing (e.g. prepare a proactive command) the SIM Toolkit Framework will return the response APDU defined by the toolkit applet (i.e. 9F xx or 9E xx).

6.6 Handler availability

The system handlers : ProactiveHandler, ProactiveResponseHandler, EnvelopeHandler and EnvelopeResponseHandler are Temporary JCRE Entry Point Object as defined in the Java Card Runtime Environment Specification [8].

The following table describes the minimum availability of the handlers for all the events at the invocation of the processToolkit method of the toolkit applet.

Table 1: Handler availability for each event

EVENT_

Reply busy

ProactiveHandler
ProactiveResponseHandler

EnvelopeHandler

EnvelopeResponseHandler

Nb of triggered / registrered Applet

_FORMATTED_SMS_PP_ENV

Y

Y

Y

Y

1 / n (per TAR)

_FORMATTED_SMS_PP_UPD

N

Y

Y

N

1 / n (per TAR)

_UNFORMATTED_SMS_PP_ENV

Y

Y

Y

Y

n / n

_UNFORMATTED_SMS_PP_UPD

N

Y

Y

N

n / n

_FORMATTED_SMS_CB

Y

Y

Y

N

1 / n (per TAR)

_UNFORMATTED_SMS_CB

Y

Y

Y

N

n / n

_MENU_SELECTION

Y

Y

Y

N

1 / n (per Item Id)

_MENU_SELECTION_HELP_REQUEST

Y

Y

Y

N

1 / n (per Item Id)

_CALL_CONTROL

N

Y/N (see Note 2)

Y

Y

1 / 1

_SMS_MO_CONTROL

N

Y/N (see Note 2)

Y

Y

1 / 1

_TIMER_EXPIRATION

Y

Y

Y

N

1/ 8 (per timer) (see Note 1)

_EVENT_DOWNLOAD

_MT_CALL

Y

Y

Y

N

n / n

_CALL_CONNECTED

Y

Y

Y

N

n / n

_CALL_DISCONNECTED

Y

Y

Y

N

n / n

_LOCATION_STATUS

Y

Y

Y

N

n / n

_USER_ACTIVITY

Y

Y

Y

N

n / n

_IDLE_SCREEN_AVAILABLE

Y

Y

Y

N

n / n

_LANGUAGE_SELECTION

Y

Y

Y

N

n / n

_BROWSER_TERMINATION

Y

Y

Y

N

n / n

_CARD_READER_STATUS

Y

Y

Y

N

n / n

_UNRECOGNISED_ENVELOPE

Y

Y

Y

Y

n / n

_STATUS_COMMAND

N

Y/N (see Note 2)

N

N

n / n

_PROFILE_DOWNLOAD

N

Y/N (see Note 2)

N

N

n / n

NOTE 1: One toolkit applet can register to several timers, but a timer can only be allocated to one toolkit applet.

NOTE 2: Y/N means that handlers may / may not be available depending whether a proactive session is ongoing.

The following rules define the minimum requirement for the availability of the system handlers and the lifetime of their content.

ProactiveHandler:

– The ProactiveHandler is valid from the invocation to the termination of the processToolkit method.

– If a proactive command is pending the ProactiveHandler may not be available.

– At the processToolkit method invocation the TLV-List is cleared.

– At the call of it’s init method the content is cleared and then initialised.

– After a call to ProactiveHandler.send method the handler will remain unchanged (i.e. previously send proactive command) until the ProactiveHandler.init or appendTLV methods are called.

ProactiveResponseHandler:

– The ProactiveResponseHandler may not be available before the first call to ProactiveHandler.send method, if available the content is cleared.

– The ProactiveResponseHandler is available after the first call to the ProactiveHandler.send method to the termination of the processToolkit method.

– If a proactive command is pending the ProactiveResponseHandler may not be available.

– The ProactiveResponseHandler content is changed after the call to ProactiveHandler.send method and remains unchanged until next call to the ProactiveHandler.send method.

EnvelopeHandler:

– The EnvelopeHandler and its content are available for all triggered toolkit applets (see Table1), from the invocation to the termination of their processToolkit method.

– The SIM Toolkit Framework guarantees that all registered toolkit applet are triggered and receive the data.

EnvelopeResponseHandler:

– The EnvelopeResponseHandler is available for all triggered toolkit applets, until a toolkit applet has posted an envelope response or sent a proactive command. After a call to the post method the handler is no longer available.

– The EnvelopeResponseHandler content must be posted before the first invocation of a ProactiveHandler.send method or before the termination of the processToolkit, so that the GSM applet can offer these data to the ME (eg 9Fxx/9Exx). After the first invocation of the ProactiveHandler.send method the EnvelopeResponseHandler is no more available.

The following diagram illustrates these rules.

Applet

Applet 1

Applet 2

method

processToolkit

post

init

termination

init

init

invocation

init

send

send

processToolkit

send

Envelope Handler

EnvelopeResponseHandler

ProactiveHandler

Proactive ResponseHandler

Figure 5: Typical handler availability for toolkit applets (see Table 1 for detail)

6.7 SIM Toolkit Framework behaviour

The following rules define the SIM Toolkit Framework behaviour for :

– Triggering of a toolkit applet (invocation of the processToolkit() method from the ToolkitInterface shareable interface) :

– The current context is switched to the toolkit applet .

– A pending transaction is aborted.

– There is no invocation of the select() or the deselect() methods.

– The CLEAR_ON_DESELECT transient object can not be accessed and not created as defined in Java Card 2.1 Runtime Environment Specification [8], as the current selected application is unchanged (eg GSM applet) and does not correspond to the current context which is the toolkit applet.

– The current file context of the toolkit applet is the MF.

– The current file context of the current selected applet is unchanged.

– The toolkit applet cannot access the APDU object.

– Termination of a toolkit applet (return from the processToolkit() method):

– The JCRE switches back to the context of the current selected applet, the GSM applet.

– There is no invocation of the select() or the deselect() methods.

– A pending toolkit applet transaction is aborted.

– The transient data are unchanged.

– The current file context of the toolkit applet is lost.

– The current file context of the current selected applet is unchanged.

– The GSM applet shall not rely on the APDU object content. The APDU content may be changed by the system [For Further Study as the interface between the toolkit system and the GSM applet is not defined yet]

– Invocation of ProactiveHandler.send() method :

– During the execution there might be other context switches, but at the return of the send() method the toolkit applet context is restored.

– There is no invocation of the select() or the deselect() methods.

– A pending toolkit applet transaction at the method invocation is aborted.

– The current file context of the toolkit applet is unchanged (see chapter 5.2). The send() method will never return if the GSM applet is deselected and another applet is explicitly selected.

– Emission of system proactive commands (SIM Toolkit framework dynamic behaviour)

– The SIM Toolkit Framework shall send its system proactive command as soon as no proactive session is pending and all the applets registered to the current events have been triggered and have returned from the processToolkit method invocation.

6.8 Usage of ViewHandler and EditHandler

The ViewHandler and EditHandler classes have been defined to group the properties of the system handler, and may be used in the future to provide a simple mechanism to the toolkit applet to handle TLV lists.