ETSI TS 102 240 V9.0.0 (2009-06)

ETSI TS 102 240 V9.0.0 (2009-06)
Technical Specification


Smart Cards;
UICC Application Programming Interface and
Loader Requirements;
Service description;
(Release 9)

---------------------- Page: 1 ----------------------
Release 9 2 ETSI TS 102 240 V9.0.0 (2009-06)



Reference
RTS/SCP-R0263v900
Keywords
API, smart card
ETSI
650 Route des Lucioles
F-06921 Sophia Antipolis Cedex - FRANCE

Tel.: +33 4 92 94 42 00  Fax: +33 4 93 65 47 16

Siret N° 348 623 562 00017 - NAF 742 C
Association à but non lucratif enregistrée à la
Sous-Préfecture de Grasse (06) N° 7803/88

Important notice
Individual copies of the present document can be downloaded from:
http://www.etsi.org
The present document may be made available in more than one electronic version or in print. In any case of existing or
perceived difference in contents between such versions, the reference version is the Portable Document Format (PDF).
In case of dispute, the reference shall be the printing on ETSI printers of the PDF version kept on a specific network drive
within ETSI Secretariat.
Users of the present document should be aware that the document may be subject to revision or change of status.
Information on the current status of this and other ETSI documents is available at
http://portal.etsi.org/tb/status/status.asp
If you find errors in the present document, please send your comment to one of the following services:
http://portal.etsi.org/chaircor/ETSI_support.asp
Copyright Notification
No part may be reproduced except as authorized by written permission.
The copyright and the foregoing restriction extend to reproduction in all media.

© European Telecommunications Standards Institute 2009.
All rights reserved.

TM TM TM TM
DECT , PLUGTESTS , UMTS , TIPHON , the TIPHON logo and the ETSI logo are Trade Marks of ETSI registered
for the benefit of its Members.
TM
3GPP is a Trade Mark of ETSI registered for the benefit of its Members and of the 3GPP Organizational Partners.
LTE™ is a Trade Mark of ETSI currently being registered
for the benefit of its Members and of the 3GPP Organizational Partners.
GSM® and the GSM logo are Trade Marks registered and owned by the GSM Association.
ETSI

---------------------- Page: 2 ----------------------
Release 9 3 ETSI TS 102 240 V9.0.0 (2009-06)
Contents
Intellectual Property Rights . 5
Foreword . 5
1 Scope . 6
2 References . 6
2.1 Normative references . 6
2.2 Informative references . 7
3 Definitions and abbreviations . 7
3.1 Definitions . 7
3.2 Abbreviations . 8
4 Description . . 8
4.1 Design of UICC based applications using the UICC API . 9
4.2 UICC API architecture . 10
4.3 UICC file data access . 11
4.4 UICC BER-TLV file access . 11
5 Card interoperability. 11
5.1 Loader requirements . 11
5.2 Application transport . 12
6 Applet activation . 12
6.1 Applet triggering . 12
6.2 Applet selection . 13
7 Applet life cycle management . 13
7.1 Applet preparation . 13
7.2 Loading . 14
7.2.1 Arbitration. 14
7.2.2 Transport . 14
7.2.3 Verification . 14
7.2.4 Linking . 14
7.3 Installation/registration/reactivation . 14
7.4 Configuration . 14
7.5 Execution . 15
7.6 Deactivation . 15
7.7 Removal . 15
8 Security management . 15
8.1 Management of applets . 15
8.2 Applet certification . 15
9 API compatibility . 15
9.1 Level of compatibility . 15
9.2 Compatibility at the interface . 15
9.3 Compatibility at the programming interface . 16
9.4 Accessibility of the programming interface . 16
10 API extensibility . . 16
10.1 Evolution of UICC/terminal interface (TS 102 221) . 16
10.2 Evolution of CAT application toolkit (TS 102 223) . 16
10.3 Interworking with other systems . 16
10.4 Evolution of UICC/terminal contactless interface (TS 102 622 and TS 102 613) . 16
11 Data and function sharing and access control . 17
11.1 Sharing resources between applets . 17
11.2 Access to data . 17
12 Technology considerations . 18
ETSI

---------------------- Page: 3 ----------------------
Release 9 4 ETSI TS 102 240 V9.0.0 (2009-06)
12.1 UICC hardware requirements . 18
12.2 Technology limitations . 18
12.2.1 Memory recovery . 18
12.3 Evolution . 18
12.3.1 Remote Procedure Call (RPC) . 18
13 Enhanced Runtime Environment . 18
13.1 Interworking between multiple hardware and logical UICC/terminal interfaces . 18
13.2 Support for TCP and UDP . 18
13.3 Support for HTTP . 19
13.4 Support for Card Application Toolkit (CAT) . 19
13.5 Secure communication . 19
13.6 Events . 19
13.7 Access to the enhanced UICC API framework . 19
13.8 Inter-application communication . 19
13.9 Backward compatibility . 19
Annex A (informative): Change history . 20
History . 21

ETSI

---------------------- Page: 4 ----------------------
Release 9 5 ETSI TS 102 240 V9.0.0 (2009-06)
Intellectual Property Rights
IPRs essential or potentially essential to the present document may have been declared to ETSI. The information
pertaining to these essential IPRs, if any, is publicly available for ETSI members and non-members, and can be found
in ETSI SR 000 314: "Intellectual Property Rights (IPRs); Essential, or potentially Essential, IPRs notified to ETSI in
respect of ETSI standards", which is available from the ETSI Secretariat. Latest updates are available on the ETSI Web
server (http://webapp.etsi.org/IPR/home.asp).
Pursuant to the ETSI IPR Policy, no investigation, including IPR searches, has been carried out by ETSI. No guarantee
can be given as to the existence of other IPRs not referenced in ETSI SR 000 314 (or the updates on the ETSI Web
server) which are, or may be, or may become, essential to the present document.
Foreword
This Technical Specification (TS) has been produced by ETSI Technical Committee Smart Card Platform (SCP).
It is based on work originally done by the 3GPP group in "TSG-Terminals WG3" and by "ETSI Special Mobile Group
(SMG)".
The present document details the stage 1 aspects (overall service description) for the support of a UICC Application
Programming Interface (API).
The contents of the present document are subject to continuing work within ETSI SCP and may change following
formal ETSI SCP approval. Should ETSI SCP modify the contents of the present document it will then be republished
by ETSI with an identifying change of release date and an increase in version number as follows:
Version x.y.z
where:
x the first digit:
0 early working draft;
1 presented to TC SCP for information;
2 presented to TC SCP for approval;
3 or greater indicates TC SCP approved document under change control.
y the second digit is incremented for all changes of substance, i.e. technical enhancements, corrections,
updates, etc.
z the third digit is incremented when editorial only changes have been incorporated in the document.
ETSI

---------------------- Page: 5 ----------------------
Release 9 6 ETSI TS 102 240 V9.0.0 (2009-06)
1 Scope
The present document defines the service description of the UICC Application Programming Interface (UICC API)
internal to the UICC. Stage one is an overall service description, and does not deal with the implementation details of
the API.
The present document includes information applicable to network operators, service providers and terminal, UICC,
Network Access Application (NAA) providers, switch and database manufacturers.
The present document contains the core requirements, which are sufficient to provide a complete service.
It is highly desirable however, that technical solutions for a UICC API should be sufficiently flexible to allow for
possible enhancements. Additional functionalities not documented in the present document may implement
requirements which are considered outside the scope of the present document. This additional functionality may be on a
network wide basis, nation-wide basis or particular to a group of users. Such additional functionality shall not
compromise conformance to the core requirements of the service.
2 References
References are either specific (identified by date of publication and/or edition number or version number) or
non-specific.
• For a specific reference, subsequent revisions do not apply.
• In the case of a reference to a TC SCP document, a non specific reference implicitly refers to the latest version
of that document in the same Release as the present document.
• Non-specific reference may be made only to a complete document or a part thereof and only in the following
cases:
- if it is accepted that it will be possible to use all future changes of the referenced document for the
purposes of the referring document;
- for informative references.
Referenced documents which are not found to be publicly available in the expected location might be found at
http://docbox.etsi.org/Reference.
NOTE: While any hyperlinks included in this clause were valid at the time of publication ETSI cannot guarantee
their long term validity.
2.1 Normative references
The following referenced documents are indispensable for the application of the present document. For dated
references, only the edition cited applies. For non-specific references, the latest edition of the referenced document
(including any amendments) applies.
[1] ETSI TS 102 221: "Smart cards; UICC-Terminal interface; Physical and logical characteristics
(Release 7)".
[2] ETSI TS 102 223: "Smart cards; Card Application Toolkit (CAT) (Release 7)".
[3] ISO/IEC 7816-4: " Identification cards - Integrated circuit cards Part 4: Organization, security and
commands for interchange".
[4] ETSI TS 102 622: "Smart Cards; UICC - Contactless Front-end (CLF) Interface; Host Controller
Interface (HCI)".
[5] ETSI TS 102 613: "Smart Cards; UICC - Contactless Front-end (CLF) Interface; Part 1: Physical
and data link layer characteristics".
ETSI

---------------------- Page: 6 ----------------------
Release 9 7 ETSI TS 102 240 V9.0.0 (2009-06)
[6] ETSI TS 102 600: "Smart card ; UICC-Terminal interface; Characteristics of the USB interface".
[7] ETSI TS 102 483: "Smart cards; Internet Protocol connectivity between UICC and terminal".
[8] ETSI TS 102 484: "Smart Cards; Secure channel between a UICC and an end-point terminal".
[9] OMA: "Smartcard Web Server Enabler Architecture",
OMA-AD-Smartcard_Web_Server-V1_0-20070209-C.
[10] ETSI TS 102 412: "Smart cards; Smart Card Platform Requirements Stage 1".
2.2 Informative references
The following referenced documents are not essential to the use of the present document but they assist the user with
regard to a particular subject area. For non-specific references, the latest version of the referenced document (including
any amendments) applies.
Not applicable.
3 Definitions and abbreviations
3.1 Definitions
For the purposes of the present document, the following terms and definitions apply:
applet: application built up using a number of modules which will run under the control of a virtual machine
application: in the scope of this document either an applet or a web-application.
bytecode: machine independent code generated by a bytecode compiler and executed by a bytecode interpreter
data structure: collection of related data values such as the age, birth date and height of an individual
framework: defines a set of Application Programming Interface (API) functions and data structures for developing
applications and for providing system services to those applications
function: callable and executable body of computer instructions which perform a specific computation or data
processing task
module: collection of functions and data structures which implement an entire application or a particular application
feature or capability
UICC API framework: part of the UICC responsible for the handling of applications (including triggering and
loading)
NOTE: It also contains the library for the proactive API.
Servlet: application built up using a number of modules responding to incoming Internet protocol request (e.g. TCP,
HTTP, HTTPS …)
NOTE: A Servlet runs under the control of a Servlet engine.
Servlet engine: part of the enhanced UICC API framework, responsible for handling incoming requests via the TCP/IP
protocol (e.g. HTTP/HTTPS) and dispatching them to the web-application
toolkit applet: applet loaded onto the UICC seen by the mobile as being part of the UICC toolkit application and
containing only the code necessary to run the application
NOTE: These applets might be downloaded over the radio interface.
trusted party: entity trusted by the card issuer with respect to security related services and activities
ETSI

---------------------- Page: 7 ----------------------
Release 9 8 ETSI TS 102 240 V9.0.0 (2009-06)
virtual machine: part of the run-time environment responsible for interpreting the bytecode
web-application: at least one Servlet or a combination of one or more Servlets, additional modules, applets, and static
content
3.2 Abbreviations
For the purposes of the present document, the following abbreviations apply:
AID Applet IDentifier
APDU Application Protocol Data Unit
API Application Programming Interface
AVN Applet Version Number
BER Bit Error Rate
CAD Card Acceptance Device
CAT Card Application Toolkit
CLF Contactless Front-end
EPOS Electronic Point Of Sale
HCI Host Controller Interface
HTTP Hypertext Transfer Protocol
IFD InterFace Device
IP Internet Protocol
MExE Mobile Execution Environment
NAA Network Access Application
RPC Remote Procedure Call
TCP Transmission Control Protocol
TLS Transport Layer Security
TLV Tag, Length, Value
UDP User Datagram Protocol
UICC Universal Integrated Circuit Card
WAP Wireless Application Protocol
4 Description
The present document describes the high level requirements for an API for the UICC. This API shall allow application
programmers easy access to the functions and data described in TS 102 221 [1] and TS 102 223 [2], such that UICC
based services can be developed and loaded onto UICCs, quickly and, if necessary, remotely, after the UICC has been
issued.

Application
↔
AIDx. TARx
AID
Card
Application Card
Operator
AID1,TAR1
Applet1
TAR2
Applet2
…
…
Application Trusted
AID
Trusted
AIDn,TARn
Appletn
UICC
Communication
↔
Terminal
AIDx TARx
…
Management

Figure 1: Toolkit applet management and communication
ETSI

---------------------- Page: 8 ----------------------
Release 9 9 ETSI TS 102 240 V9.0.0 (2009-06)
4.1 Design of UICC based applications using the UICC API
Figure 2 shows how UICC applications can be developed in a standard development environment and converted into an
interpreted format, then loaded into the UICC.
Source code; e.g. C,
Java, Visual Basic, etc.
compile (including
libraries)
Development
Environment API;
Bytecode
(e.g. Visual Basic
API, C API, Java
optimise
API)
(optional)
Toolkit
Applet File
Terminal
download
Applet file stored in non volatile
memory
install
Smart Card Execution
Application environment
platform;
activate
( e.g. Java Card™,
Multos, Smart Card
for Windows)
Runnable (activated)
applet
trigger
Executed applet

Figure 2: Flow diagram of the development of a UICC application
ETSI

---------------------- Page: 9 ----------------------
Release 9 10 ETSI TS 102 240 V9.0.0 (2009-06)
4.2 UICC API architecture
The UICC API shall consist of APIs for TS 102 223 [2] (pro-active functions) and TS 102 221 [1] (transport functions).
Figure 3 illustrates the interactions between these APIs.

Toolkit Toolkit
…
Applet 1 Applet 2 Applet 3 Applet n
Proactive
UICC-API
commands
Activation
File
Install
access
Uninstall
P/C
(see note)
responses
UICC API Framework
Applet
Proactive Applet
triggering
command manager install/uninstall
Applet security
Security
manager
APDU Proactive polling, 91XX, Fetch,
e.g. Proactive commands,
File access
Envelopes Terminal Response
UICC Kernel
Files
APDU
Interface to terminal

NOTE: The install / uninstall process does not form part of the API. Its requirements are outlined in clause 7.

Figure 3: UICC API architecture
In this model, the UICC data field structure is viewed as a series of data structures and data access functions to the API.
In the physical model of course, they may still be stored in elementary files, but the functions will access these data as
values within those data structures.
A general requirement of the UICC API is that applets should not interfere with the basic UICC services.
The UICC API framework shall prevent the toolkit applets from sending proactive commands which would interfere
with the correct execution of the UICC operating system and/or other toolkit applets.
ETSI

---------------------- Page: 10 ----------------------
Release 9 11 ETSI TS 102 240 V9.0.0 (2009-06)
4.3 UICC file data access
The following methods shall be offered by the API to UICC applets, to allow access to the UICC data:
activateFile This function reactivates a deactivated EF. In case of successful execution of the command, the EF
on which the command was applied becomes the current EF. After an unsuccessful execution, the
current EF and current DF shall remain the same as prior to the execution.
deactivateFile This function initiates a reversible deactivation of an EF. In case of successful execution of the
command, the EF on which the command was applied becomes the current EF. After an
unsuccessful execution, the current EF and current DF shall remain the same as prior to the
execution.
increase This function adds the value given in an array of bytes to the value of the last increased/updated
record of the current cyclic EF, and stores the result into the oldest record. The record pointer is set
to this record and this record becomes record number 1. The function does not perform the
increase if the result would exceed the maximum value of the record (represented by all bytes set
to "FF").
readBinary This function reads an array of bytes from the current transparent EF.
readRecord This function reads one complete record in the current linear fixed or cyclic EF into an array of
bytes.
SearchRecord This function searches through a linear fixed or cyclic EF to find record(s) containing a specific
pattern.
select Select a file without changing the current file of any other applet or of the subscriber session.
status This function returns information concerning the current directory.
updateBinary This function updates the current transparent EF with an array of bytes.
updateRecord This function updates one specific, complete record in the current linear fixed or cyclic EF with an
array of bytes.
4.4 UICC BER-TLV file access
The following methods shall be offered by the API to UICC applets, to allow access to the data stored in BER-TLV
files as defined in TS 102 221 [1]:
• Retrieve a list of objects stored in the BER-TLV file identified by the TAG values of the objects.
• Select a TLV object in the BER-TLV file.
• Read data from a TLV object in the BER-TLV file.
• Write data to a TLV object in a BER-TLV file.
• Delete a TLV object in a BER-TLV file.
• Add a TLV object in a BER-TLV file.
5 Card interoperability
5.1 Loader requirements
There are a number of requirements for the loader which are seen as being vital to the successful deployment of UICC
API based UICCs.
• The Applet format shall be common to all compliant UICCs, such that a card issuer can deploy UICC API
based service applets to any UICC API compliant UICC.
ETSI

---------------------- Page: 11 ----------------------
Release 9 12 ETSI TS 102 240 V9.0.0 (2009-06)
• The loader environment that allows the loading of applets to the UICC shall be common to all UICC API
compliant UICCs. This loader shall be able to send applets to UICCs in three distinct ways:
- During the personalization of the UICC, prior to the issue of the UICC to the user.
- During the life of the UICC using the UICC Data Download mechanism defined in TS 102 223 [2] or
using other standardized application dependent mechanisms.
- During the life of the UICC using an IFD (Interface Device) or CAD (Card Accepting Device,
e.g. an EPOS terminal).
5.2 Application transport
The transport of applications shall be transparent to the terminal. Applications may be transported via several different
bearers.
6 Applet activation
6.1 Applet triggering
The application triggering portion of the UICC Framework is responsible for the activation of toolkit applets, based on
the APDU received by the UICC. The inputs and outputs could be represented in figure 4.

Menu
Terminal
Applet Triggering
APDU
...

Figure 4: Applet triggering module
Entry points to the applet shall be provided in two ways:
• High level entry points, in order to have a simple programming of the UICC.
• Low level entry points to support the evolution of the TS 102 223 [2] specification.
Some of the high level entry points are listed below:
• Application loading.
• Application removal.
• Terminal profile.
• Menu selection.
• Events upon file system operations by the terminal or by application(s) in the card :
- read file,
- update file,
- set data,
- retrieve data,
- search record,
ETSI

---------------------- Page: 12 ----------------------
Release 9 13 ETSI TS 102 240 V9.0.0 (2009-06)
- create file,
- delete file,
- resize file,
- terminate file,
- activate file,
- deactivate file.
6.2 Applet selection
Applet activation through selection shall follow the rules defined in TS 102 221 [1] for application selection
...