6 (U)SAT Framework

(U)SIM API for Java™ Card(U)SIM Application Programming Interface (API)31.1303GPPRelease 17TS

Tools: ARFCN - Frequency Conversion for 5G NR/LTE/UMTS/GSM

6.0 Overview

The (U)SIM toolkit API consists of the uicc.usim.toolkit package for toolkit features defined in TS 31.111 [7] and TS 51.014 [8], and is based on the uicc.toolkit package defined in ETSI TS 102 241 [2].

6.1 Applet triggering

See ETSI TS 102 241 [2].

6.1.1 Exception Handling

The following clause describes the handling of exceptions by the (U)SAT Framework in addition to the behaviour defined in ETSI TS 102 241 [2] for the CAT Runtime Environment.

If an Applet triggered by EVENT_FORMATTED_SMS_PP_ENV event throws an ISOException with the reason code (0x6FXX), it shall be sent to the terminal.

Other Exceptions shall not be propagated to the terminal.

6.2 Definition of Events

The following events can trigger a Toolkit Applet in addition to the events defined in ETSI TS 102 241 [2], all short values are reserved in ETSI TS 102 241 [2]:

Table 1: (U)SAT event list

Event Name	Reserved short value
EVENT_FORMATTED_SMS_PP_ENV	2
EVENT_FORMATTED_SMS_PP_UPD	3
EVENT_UNFORMATTED_SMS_PP_ENV	4
EVENT_UNFORMATTED_SMS_PP_UPD	5
EVENT_UNFORMATTED_SMS_CB	6
EVENT_MO_SHORT_MESSAGE_CONTROL_BY_NAA	10
EVENT_FORMATTED_SMS_CB	24
EVENT_EVENT_DOWNLOAD_IWLAN_ACCESS_STATUS	30
EVENT_EVENT_DOWNLOAD_NETWORK_REJECTION	31
EVENT_EVENT_DOWNLOAD_CSG_CELL_SELECTION	33
EVENT_EVENT_DOWNLOAD_DATA_CONNECTION_STATUS_CHANGE	37
EVENT_EVENT_DOWNLOAD_CAG_CELL_SELECTION	118
EVENT_EVENT_DOWNLOAD_IMS_REGISTRATION	119
EVENT_EVENT_DOWNLOAD_INCOMING_IMS_DATA	120
EVENT_FORMATTED_USSD	121
EVENT_UNFORMATTED_USSD	122

EVENT_FORMATTED_SMS_PP_ENV, EVENT_UNFORMATTED_SMS_PP_ENV,
EVENT_FORMATTED_SMS_PP_UPD, EVENT_UNFORMATTED_SMS_PP_UPD

There are two ways for a card to receive a Short Message Point to Point: via an ENVELOPE(SMS-PP Download) APDU as defined in TS 31.111 [7] and TS 51.014 [8] or an UPDATE RECORD EF_SMS APDU as defined in TS 31.102 [3] and TS 51.011 [4]. The EF_SMScan beeither located under the DF_Telecom or under any ADF as defined in TS 31.102 [3] and TS 51.011 [4].

The received Short Message may be:

– formatted according to TS 31.115 [9] or an other protocol to identify explicitly the toolkit applet for which the message is sent;

– unformatted (e.g. a toolkit applet specific protocol ) then the (U)SAT Framework will pass this data to all registered toolkit applets.

When the Short Message is received as Concatenated Short Messages as defined in TS 23.040 [10], it is the responsibility of the (U)SAT Framework to link single Short Messages together to re – assemble the original message before any further processing. The original Short Message shall be placed in one SMS TPDU TLV (with TP-UDL field coded on one octet) included in the USATEnvelopeHandler. The concatenation control headers used to re-assemble the short messages in the correct order shall not be present in the SMS TPDU. The TP-elements of the SMS TPDU and the Address (TS – Service-Centre-Address) shall correspond to the ones in the last received Short Message (independently of the Sequence number of Information-Element-Data).

The minimum requirement for the (U)SAT Framework is to process a concatenated short message with the following properties:

– the Information Element Identifier is equal to the 8-bit reference number.

– it contains uncompressed 8 bit data or uncompressed UCS2 data.

EVENT_FORMATTED_SMS_PP_ENV

Upon reception of a TS 31.115 [9] formatted Short Message Point to Point (Single or Concatenated) via an ENVELOPE, the (U)SAT Framework shall:

– verify the security of the Short Message as per TS 31.115 [9];

– trigger the toolkit applet registered with the corresponding TAR;

– take the optional Application Data posted by the triggered toolkit applet if present;

– secure and send the response packet using SMS-DELIVER-REPORT or SMS-SUBMIT.

When the toolkit applet is triggered, data shall be provided deciphered.

EVENT_UNFORMATTED_SMS_PP_ENV

Upon reception of an unformatted Short Message Point to Point (Single or Concatenated) via an ENVELOPE, the (U)SAT Framework shall trigger all the Toolkit Applets registered to this event.

NOTE 1: As a consequence of the EnvelopeResponseHandler availability rules specified in clause 6.6, only the first triggered toolkit applet is guaranteed to be able to send back a response.

EVENT_FORMATTED_SMS_PP_UPD

Upon reception of a TS 31.115 [9] formatted Short Message Point to Point (Single or Concatenated) via an UPDATE RECORD EF_SMS, the (U)SAT Framework shall:

– update the EF_SMS 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 EF_SMS file)

– verify the security of the Short Message as per TS 31.115 [9];

– convert the UPDATE RECORD EF_SMS APDU into a COMPREHENSION TLV List;

– trigger the toolkit applet registered with the corresponding TAR;

When the toolkit applet is triggered, data shall be provided deciphered.

The USATEnvelopeHandler provided to the applet shall:

– return BTAG_SMS_PP_DOWNLOAD to the getTag() method call;

– return the Comprehension TLV list length to the getLength() method call;

The USATEnvelopeHandler provided to the applet shall contain the following COMPREHENSION TLVs:

– Device Identities TLV

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

Device identities Comprehension TLV

Device Identities tag

length = 02

Absolute Record Number

Record Status

With the absolute record number the toolkit applet can update EF_SMS in absolute mode to change the received SMS (e.g. in a readable text).

For Concatenated Short Message the Absolute Record Number and the Record Status will correspond to the last UPDATE RECORD EF_SMS APDU received.

– Address TLV

The value is the TS-Service-Centre-Address (RP-OA) of the last UPDATE RECORD EF_SMS APDU.

– SMS TPDU TLV

The value is the SMS TPDU provided deciphered and reassembled, if needed

– AID TLV

The AID comprehension TLV is present only if the EF_SMS file updated is under an ADF. The value is the AID of the ADF as defined TS 31.111 [7].

The order of the TLVs given in the USATEnvelopeHandler is not specified,

NOTE 2: To get each COMPREHENSION TLV, it is recommended that the applet uses the ViewHandler.findTLV() methods

EVENT_UNFORMATTED_SMS_PP_UPD

Upon reception of an unformatted Short Message Point to Point (Single or Concatenated) via UPDATE RECORD EF_SMS APDU, the (U)SAT Framework shall :

– update the EF_SMS file with the data received;

– convert the UPDATE RECORD EF_SMS APDU data into a COMPREHENSION TLV List (as described for EVENT_FORMATTED_SMS_PP_UPD);

– trigger all the Toolkit Applets registered to this event.

The content of EF_SMSmay have been modified by a previously triggered Toolkit Applet..

EVENT_FORMATTED_SMS_CB, EVENT_UNFORMATTED_SMS_CB

The received Cell Broadcast Message, via an ENVELOPE (CELL BROADCAST DOWNLOAD) APDU as defined in TS 31.111 [7] and TS 51.014 [8] and, can be either:

– formatted according to TS 31.115 [9] or an other protocol to identify explicitly the toolkit applet for which the message is sent;

– unformatted ( e.g. using a toolkit applet specific protocol ), then the (U)SAT Framework will pass this data to all registered toolkit applets.

When the Cell Broadcast Message is received as multiple pages as defined in TS 23.041 [5], it is the responsibility of the (U)SAT Framework to link single pages together to re‑assemble the original message before any further processing. The original Cell Broadcast message shall be placed in one Cell Broadcast page TLV included in the USATEnvelopeHandler. The message parameters shall correspond to the ones in the last received Cell Broadcast page (independently of the Page Parameter).

EVENT_FORMATTED_SMS_CB

Upon reception of a TS 31.115 [9] formatted Cell Broadcast message, the (U)SAT Framework shall:

– verify the security of the Cell Broadcast message as per TS 31.115 [9];

– trigger the toolkit applet registered with the corresponding TAR;

When the toolkit applet is triggered, data shall be provided deciphered.

EVENT_UNFORMATTED_SMS_CB

Upon reception of an unformatted Cell Broadcast message, the (U)SAT Framework shall trigger all the Toolkit Applets registered to this event.

EVENT_MO_SHORT_MESSAGE_CONTROL_BY_NAA

Upon reception of an ENVELOPE (MO SHORT MESSAGE CONTROL defined in TS 51.014 [8] and TS 31.111 [7]) APDU as defined in TS 31.101 [6] and TS 51.011 [4] the (U)SAT Framework shall trigger the Toolkit Applet registered to this event. The (U)SAT Framework shall not allow more than one Toolkit Applet to be registered to this event at a time(e.g. if a Toolkit Applet is registered to this event but not in selectable state the (U)SAT Framework shall not allow another Toolkit Applet to register to this event).

EVENT_FORMATTED_USSD, EVENT_UNFORMATTED_USSD

The received USSD String, via an ENVELOPE (USSD Data Download) APDU as defined in TS 31.111 [7], may be:

– formatted according to TS 31.115 [9] or an other protocol to identify explicitly the toolkit applet for which the message is sent;

– unformatted (e.g. a toolkit applet specific protocol) then the (U)SAT Framework will pass this data to all registered toolkit applets.

When the USSD Message is received as concatenated as defined in TS 31.115 [9], it is the responsibility of the (U)SAT Framework to link single USSD Messages together to re‑assemble the original message before any further processing. The original USSD message shall be placed in one USSD String TLV included in the USATEnvelopeHandler. The USSD String parameters (DCS, PFI, CCF) shall correspond to the ones in the last received USSD String (independently of the CCF Sequence number).

EVENT_FORMATTED_USSD

Upon reception of a TS 31.115 [9] formatted USSD Message via an ENVELOPE, the (U)SAT Framework shall:

– verify the security of the USSD Message as per TS 31.115 [9];

– trigger the toolkit applet registered with the corresponding TAR;

– take the optional Application Data posted by the triggered toolkit applet if present;

– secure and send the response packet.

When the toolkit applet is triggered, data shall be provided deciphered.

EVENT_UNFORMATTED_USSD

Upon reception of an unformatted USSD String via an ENVELOPE, the (U)SAT Framework shall trigger all the Toolkit Applets registered to this event.

NOTE 3: As a consequence of the EnvelopeResponseHandler availability rules specified in clause 6.6, only the first triggered toolkit applet is guaranteed to be able to send back a response.

EVENT_EVENT_DOWNLOAD_IWLAN_ACCESS_STATUS

EVENT_EVENT_DOWNLOAD_NETWORK_REJECTION

EVENT_EVENT_DOWNLOAD_CSG_CELL_SELECTION

EVENT_EVENT_DOWNLOAD_IMS_REGISTRATION

EVENT_EVENT_DOWNLOAD_INCOMING_IMS_DATA

EVENT_EVENT_DOWNLOAD_DATA_CONNECTION_STATUS_CHANGE

EVENT_EVENT_DOWNLOAD_CAG_CELL_SELECTION

Upon reception of an ENVELOPE (Event Download) APDU command as defined in TS 31.111 [7] the (U)SAT Framework shall trigger all the Toolkit applets registered to the corresponding event.

The following events defined in TS 31.111 [7] shall be raised upon reception of the corresponding APDU defined in either TS 51.011 [4] or TS 31.101 [6].

EVENT_PROFILE_DOWNLOAD

EVENT_MENU_SELECTION, EVENT_MENU_SELECTION_HELP_REQUEST

EVENT_CALL_CONTROL_BY_NAA

EVENT_TIMER_EXPIRATION

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_STATUS_COMMAND

EVENT_EVENT_DOWNLOAD_LANGUAGE_SELECTION

EVENT_EVENT_DOWNLOAD_BROWSER_TERMINATION

EVENT_EVENT_DOWNLOAD_DATA_AVAILABLE

EVENT_EVENT_DOWNLOAD_CHANNEL_STATUS

EVENT_EVENT_DOWNLOAD_ACCESS_TECHNOLOGY_CHANGE

EVENT_EVENT_DOWNLOAD_DISPLAY_PARAMETER_CHANGED

EVENT_EVENT_DOWNLOAD_LOCAL_CONNECTION

EVENT_EVENT_DOWNLOAD_NETWORK_SEARCH_MODE_CHANGE

EVENT_EVENT_DOWNLOAD_BROWSING_STATUS

EVENT_PROACTIVE_HANDLER_AVAILABLE

EVENT_EXTERNAL_FILE_UPDATE

EVENT_FIRST_COMMAND_AFTER_ATR

EVENT_UNRECOGNIZED_ENVELOPE

6.3 Registration

A Toolkit Applet shall register to events described in 6.2 as defined in ETSI TS 102 241 [2].

Constants for these events are available in uicc.usim.toolkit.ToolkitConstants interface in Annex A.

The uicc.toolkit.ToolkitException TAR_NOT_DEFINED shall be thrown if a Toolkit Applet has no TAR defined and registers to events: EVENT_FORMATTED_SMS_PP_ENV, EVENT_FORMATTED_SMS_PP_UPD, EVENT_FORMATTED_SMS_CB, EVENT_FORMATTED_USSD.

The uicc.toolkit.ToolkitException.EVENT_ALREADY_REGISTERED shall be thrown if there is another Toolkit Applet already registered to EVENT_MO_SHORT_MESSAGE_CONTROL_BY_NAA.

6.4 Proactive command handling

There is no extension of the CAT Runtime Environment by the (U)SAT Framework for proactive command handling.

6.5 Envelope response handling

For the events defined in the present document, the following rules apply:

A Toolkit Applet can post a response by using the post() method or the postAsBERTLV() method defined in ETSI TS 102 241 [2]. The (U)SAT Framework shall return the Status Word as defined in TS 31.111 [7] and in TS 51.014 [8] depending on the current NAA.

Case of EVENT_MO_SHORT_MESSAGE_CONTROL_BY_NAA:

– The rules defined for EVENT_CALL_CONTROL_BY_NAA in ETSI TS 102 241 [2] apply.

Case of EVENT_UNFORMATTED_SMS_PP_ENV:

– See ETSI TS 102 241 [2].

Case of EVENT_FORMATTED_SMS_PP_ENV:

– When the post() or the postAsBERTLV() method is invoked, the (U)SAT Framework shall, according to bit 6 of the second octet of the SPI defined in TS 31.115 [9], build a SMS-DELIVER-REPORT or a SMS-SUBMIT.

In case of a SMS-DELIVER-REPORT and if the post response is too large to be contained in a SMS-DELIVER-REPORT, the (U)SAT Framework shall issue Response Packets as defined in TS 31.115 [9].

In case of a SMS-DELIVER-REPORT, the (U)SAT Framework shall return the Status Word for RP-ACK or RP-ERROR as defined in TS 31.111 [7] and in TS 51.014 [8] depending on the current NAA.

In case of SMS-SUBMIT the boolean value method parameter shall be ignored by the (U)SAT Framework. If the SMS-SUBMIT is to be used, the (U)SAT Framework shall build and issue a Send Short Message proactive command as defined in TS 31.111 [7] and in TS 51.014 [8] depending on the current NAA .

Case of EVENT_FORMATTED_USSD:

– When the post() or the postAsBERTLV() method is invoked, the (U)SAT Framework shall build a USSD String to be sent back in the Return Result Component contained in the subsequent Facility message. In that case the (U)SAT Framework shall return the Status Word as defined in TS 31.111 [7].

Case of EVENT_UNFORMATTED_USSD:

– See ETSI TS 102 241 [2].

6.6 System Handler management

For the handler management of the ProactiveHandler, the ProactiveResponseHandler, the EnvelopeHandler and the EnvelopeResponseHandler, the rules defined in ETSI TS 102 241 [2] apply.

USATEnvelopeHandler:

The single system instance of the USATEnvelopeHandler and the single system instance of the EnvelopeHandler are two distinct objects instances.

– When available the USATEnvelopeHandler shall remain available and its content shall remain unchanged from the invocation to the termination of the processToolkit() method.

– The TLV List provided in the USATEnvelopeHandler are the same as in the EnvelopeHandler.

– The handler availability of the USATEnvelopeHandler is the same handler availability as the EnvelopeHandler including all the events defined in ETSI TS 102 241 [2].

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. The rules described in this table apply in addition to the rules described in "UICC API for Java Card™"

Table 2: Handler availability for each event

EVENT_	Reply busy allowed	EnvelopeHandler / USATEnvelopeHandler	EnvelopeResponseHandler	Nb of triggered / registrered Applet
_FORMATTED_SMS_PP_ENV	Y (see Note 1)	Y	Y	1 / n (per TAR)
_FORMATTED_SMS_PP_UPD	N	Y	N	1 / n (per TAR)
_UNFORMATTED_SMS_PP_ENV	Y	Y	Y	n / n
_UNFORMATTED_SMS_PP_UPD	N	Y	N	n / n
_FORMATTED_SMS_CB	Y	Y	N	1/n (per TAR)
_UNFORMATTED_SMS_CB	Y	Y	N	n / n
_MO_SHORT_MESSAGE_CONTROL_BY_NAA	N	Y	Y	1 / 1
_FORMATTED_USSD	Y	Y	Y	1 / n (per TAR)
UNFORMATTED_USSD	Y	Y	Y	n / n
EVENT_DOWNLOAD
_IWLAN_ACCESS_STATUS	Y	Y	N	n/n
_NETWORK_REJECTION	Y	Y	N	n/n
_IMS_REGISTRATION	Y	Y	N	n/n
_INCOMING_IMS_DATA	Y	Y	N	n/n
_DATA_CONNECTION_STATUS_CHANGE	Y	Y	N	n/n
_CAG_CELL_SELECTION	Y	Y	N	n/n
NOTE 1: The framework may reply busy and not trigger the toolkit applet if e.g. a PoR using SMS SUBMIT is required in the incoming message and a proactive session is ongoing.

6.7 (U)SAT Framework behaviour

The (U)SAT Framework is a (U)SAT extension of the CAT Runtime Environment as defined in ETSI TS 102 241 [2]. In addition, the (U)SAT Framework shall consider the EVENT_EVENT_DOWNLOAD_* defined in this specification when issuing the SET UP EVENT LIST system proactive command.