4 Description

31.1313GPPC-language binding to (U)SIM APIRelease 17TS

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

The (U)SIM Application consists of the following:

– APDU handlers for communicating with the ME;

– File system and file access control;

– Toolkit Framework that provides services to Toolkit applications.

The present document describes the C programming language binding for the interface between the (U)SIM application and toolkit applications described in TS 42.019 [4]. This API allows application programmers using the C programming language to access functions and data described in TS 31.111 [2] and TS 11.14 [8], such that the (U)SIM-based applications and the services they implement can be developed and loaded onto ICCs. If required and supported by the underlying smart card technology, toolkit applications can be loaded or deleted remotely, after the card has been issued.

4.1 Overview

The ‘C’-binding for (U)SIM API shall provide function calls for pro-active functions and transport functions. The figure below shows the interactions between a typical toolkit application (shown in blue) and the various functional blocks of the (U)SIM (shown in orange). The C-bindings for these APIs are presented in subclause 4.2.

Figure 1

4.2 Design Rationale and Upward Compatibility

Some functions on the C SIM API take parameters that correspond to optional TLVs in TS 31.111 [2] and TS 11.14 [8]. If the actual parameter value passed to the function is NULL, the corresponding TLV is not passed to the ME; an example of an optional parameter is CatIconIdentifier that corresponds to the ICON IDENTIFIER TLV.

Some proactive commands have a very large number of optional TLVs, such as SETUP CALL. Therefore, this API offers two variants that address this aspect, CatSetupCall and CatSetupCallEx. The first function, CatSetupCall, takes as parameters everything that is necessary to issue a successful SETUP CALL proactive command (i.e. everything required to construct the mandatory TLVs as required by TS 31.111 [2] and TS 11.14 [8]) and also includes optional user interface TLVs (title and icon) for ease of use.

The second function, CatSetupCallEx, takes a parameter block that can be extended in future versions of the present specification. The parameter block contains members that correspond to all mandatory and optional TLVs for the SETUP CALL proactive command.

The reason for introducing the "…Ex" variants is threefold:

– Rather than extend the parameter list of a function to take a large number of optional parameters for each call, it is preferable to set up the parameters using named structure members before issuing the call to the function.

– If a future version of TS 31.111 [2] or TS 11.14 [8] extends the optional parameters for a proactive command, the corresponding parameter block can be extended to encompass these parameters without changing the function prototype.

– Any source code written for an older version of this C SIM API can be recompiled with a later version without change and will remain upwardly compatible at the source as long as the suggested coding standards are adhered to.

4.3 Application Triggering

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

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

The difference between an application and a toolkit application is that a toolkit application does not typically handle APDUs directly. It will handle higher-level messages. Furthermore the execution of a function could span over multiple APDUs, in particular, the proactive protocol commands.

All the applications that have registered interest in the event are triggered in order of their priority.

– The current context is switched to the toolkit application.

– A pending transaction is aborted.

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

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

On termination of a toolkit application execution of CatExit():

– The context switches back to the context of the current selected application, the NAA application.

– A pending toolkit application transaction is aborted.

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

EVENT_PROFILE_DOWNLOAD

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

EVENT_MENU_SELECTION, EVENT_MENU_SELECTION_HELP_REQUEST

A toolkit application 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 Toolkit Framework shall have previously issued a SET UP MENU proactive command. When a toolkit application changes a menu entry of its registry object, the 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 (TS 51.011 [11] and TS 31.102 [15]) when issuing the SET UP MENU proactive command.

The positions of the toolkit application 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 application.

If at least one toolkit application registers to EVENT_MENU_SELECTION_HELP_REQUEST, the SET UP MENU proactive command sent by the Toolkit Framework shall indicate to the ME that help information is available. A toolkit application 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 application 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 application 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 UpdateRecord EFsms instruction.

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

The received SMS may be:

– formatted according to TS 23.048 [3] or an other protocol to identify explicitly the toolkit application for which the message is sent;

– unformatted or using a toolkit application specific protocol the Toolkit Framework will pass this data to all registered toolkit applications.

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 23.048 [3].

The Toolkit Framework shall:

– verify the TS 23.048 [3] security of the SMS TPDU;

– trigger the toolkit application registered with the corresponding TAR defined at application loading;

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

– secure and send the response packet.

The toolkit application 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 applications will be triggered by this event and get the data transmitted in the APDU envelope SMS_DATADOWNLOAD.

EVENT_FORMATTED_SMS_PP_UPD

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

The Toolkit Framework shall:

– update the EFsms file with the data received, it is then up to the receiving toolkit application to change the SMS stored in the file (i.e. the toolkit application need to have access to the EFsms file);

– verify the TS 23.048 [3] security of the SMS TPDU;

– convert the Update Record EFsms in a TLV List, an EnvelopeHandler;

– trigger the toolkit application registered with the corresponding TAR defined at application loading.

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 applications. All of them may modify the content of EFsms (i.e. the toolkit applications need to have access to the EFsms file).

EVENT_UNFORMATTED_SMS_CB

When the ME receives a new cell broadcast message, the cell broadcast page may be passed to the card using the envelope command. e.g. the application may then read the message and extract a meaningful piece of information that could be displayed to the user, for instance.

EVENT_CALL_CONTROL_BY_SIM

When the NAA is in call control mode and when the user dials a number, this number is passed to the Toolkit Framework. Only one toolkit application 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

The toolkit application will be triggered by the registered event download trigger, upon reception of the corresponding Envelope command. In order to allow the toolkit application to be triggered by these events, the Toolkit Framework shall have previously issued a SET UP EVENT LIST proactive command. When a toolkit application changes one or more of these requested events of its registry, the 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 Toolkit framework. Only one toolkit application can register to this event.

EVENT_TIMER_EXPIRATION

This event is registered when the application executes a successful Toolkit CatGetTimer(). The toolkit application can then manage this (these) timer(s), and it will be triggered at the reception of the APDU Envelope TIMER EXPIRATION. The Toolkit Framework shall reply busy to this Envelope APDU if it cannot guaranty to trigger the corresponding toolkit application.

EVENT_UNRECOGNIZED_ENVELOPE

The application 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 31.111 [2] and TS 11.14 [8] and if no corresponding constant is defined in the list of the ToolkitConstants interface. By providing the means to transfer an arbitrary block of data, the Unrecognized Envelope Event will allow a toolkit application to handle the evolution of the specifications TS 31.111 [2] and TS 11.14 [8].

EVENT_STATUS_COMMAND

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

A range of events is reserved for experimental and proprietary usage (from -128 to -1). As the definition of these events is not standardized, the use of these events may make the toolkit application behave differently on different platforms.

The toolkit application shall be triggered for the registered events upon reception, and shall be able to access to the data associated to the event using OpenEnvelope() or the low-level functions.

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

4.4 Proactive command handling

The (U)SIM application toolkit protocol (i.e. 91xx, Fetch, Terminal Response) is handled by the network access application and the Toolkit Framework. The toolkit application shall not handle those events.

The network access application and the Toolkit Framework shall handle the transmission of the proactive command to the ME, and the reception of the response. The Toolkit Framework will then return in the toolkit application just after the proactive command. It shall then provide to the toolkit application the values as indicated in the function parameters. It also provides the raw return information so that the toolkit application can analyse the response.

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

The toolkit application 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 Toolkit Framework.

4.5 Application Loading

Applications compliant to the present document are represented for loading as loadfiles in the Executable and Linkable Format (ELF) described in Tool Interface Standard (TIS) Executable and Linking Format Specification [9] and SYSTEM V Application Binary Interface [10]. The application executable in the ELF loadfile may be either native code or byte code that has been created through a process of compiling the representation of the application program in the C programming language.

The e_machine entry in the ELF header is set to according to the table in annex A and indicates the architecture for which the application executable in the loadfile has been prepared.

Coding for other processors, processor instruction set extensions and byte code interpreters will be defined as needed processor-specific or interpreter-specific supplements to SYSTEM V Application Binary Interface [10] may also be provided as needed.

Loadfile linkers, loaders and installers, whether on-card or off-card, return an error condition if the application representation in the loadfile cannot be accommodated or if resources requested by the application are not available.

The over-the-air application loading mechanism, protocol and application life cycle are defined in TS 23.028 [3].