|
TECHNICAL SPECIFICATION
Smart Cards;
UICC Application Programming Interface (UICC API)
for Java Card™
(Release 15)
---------------------- Page: 1 ----------------------
Release 15 2 ETSI TS 102 241 V15.0.0 (2019-01)
Reference
RTS/SCP-T0310vf00
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
The present document can be downloaded from:
The present document may be made available in electronic versions and/or in print. The content of any electronic and/or
print versions of the present document shall not be modified without the prior written authorization of ETSI. In case of any
existing or perceived difference in contents between such versions and/or in print, the prevailing version of an ETSI
deliverable is the one made publicly available in PDF format at www.etsi.org/deliver.
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
If you find errors in the present document, please send your comment to one of the following services:
Copyright Notification
No part may be reproduced or utilized in any form or by any means, electronic or mechanical, including photocopying
and microfilm except as authorized by written permission of ETSI.
The content of the PDF version shall not be modified without the written authorization of ETSI.
The copyright and the foregoing restriction extend to reproduction in all media.
© ETSI 2019.
All rights reserved.
TM TM TM
DECT , PLUGTESTS , UMTS and the ETSI logo are trademarks of ETSI registered for the benefit of its Members.
TM TM
3GPP and LTE are trademarks of ETSI registered for the benefit of its Members and
of the 3GPP Organizational Partners.
oneM2M™ logo is a trademark of ETSI registered for the benefit of its Members and
of the oneM2M Partners.
GSM and the GSM logo are trademarks registered and owned by the GSM Association.
ETSI
---------------------- Page: 2 ----------------------
Release 15 3 ETSI TS 102 241 V15.0.0 (2019-01)
Contents
Intellectual Property Rights . 5
Foreword . 5
Modal verbs terminology . 5
1 Scope . 6
2 References . 6
2.1 Normative references . 6
2.2 Informative references . 7
3 Definition of terms, symbols and abbreviations . 7
3.1 Terms . 7
3.2 Symbols . 8
3.3 Abbreviations . 8
4 Description . 8
4.0 Purpose . 8
4.1 UICC Java Card™ architecture . 9
5 File access API . 10
5.0 Introduction . 10
5.1 FileView objects . 10
5.2 FileView operations . 11
5.3 BERTLVFileView operations . 11
6 Toolkit API and CAT Runtime Environment . 11
6.0 Introduction . 11
6.1 Applet triggering . 12
6.1.0 Triggering mechanism . 12
6.1.1 Exception handling . 12
6.2 Definition of events . 13
6.3 Registration . 19
6.4 Proactive command handling . 20
6.5 Envelope response handling . 20
6.6 System handler management . 21
6.7 CAT Runtime Environment behaviour. 23
6.7.0 Basic rules . 23
6.7.1 System proactive commands. 24
6.7.1.0 Overall behaviour . 24
6.7.1.1 SET UP MENU . 24
6.7.1.2 SET UP EVENT LIST . 25
6.7.1.3 POLL INTERVAL and POLLING OFF . 25
6.7.1.4 NEGOTIATION OF POLL INTERVAL . 25
6.7.1.5 ACTIVATE . 25
6.7.2 UICC memory reliability monitoring . 26
7 Toolkit applet . 26
7.1 Applet loading . 26
7.2 Data and function sharing . 26
7.3 Package, applet and object deletion . 26
8 UICC and ADF File System Administration API . 27
8.0 Overview . 27
8.1 AdminFileView objects . 27
8.2 AdminFileView operations . 27
9 UICC Java Card™ Services . 27
9.0 Introduction . 27
9.1 High update arrays. 28
10 UICC Java Card Runtime Environment . 28
ETSI
---------------------- Page: 3 ----------------------
Release 15 4 ETSI TS 102 241 V15.0.0 (2019-01)
10.1 Overview . 28
10.2 UICC suspension . 28
10.2.1 UICC Suspension purpose . 28
10.2.2 Suspension mechanism . 29
10.2.2.1 Suspension mechanism overview . 29
10.2.2.2 Suspension Request Operation . 29
10.2.2.3 Suspension Operation. 29
10.2.3 Resume mechanism . 30
10.2.3.1 Resume mechanism overview . 30
10.2.3.2 Resume Indication . 30
10.2.4 Handler management . 30
Annex A (normative): Java Card™ UICC API . 31
Annex B (normative): Java Card™ UICC API identifiers . 32
Annex C (normative): UICC API package version management . 33
Annex D (informative): Menu order example . 35
D.0 Preamble . 35
D.1 State after initialization . 35
D.2 Some application installation later . 35
D.3 Installation of application A with position of menu entry set to 3 . 35
D.4 Installation of application B with position of menu entry set to 3 . 35
D.5 Installation of application C with position of menu entry set to 2 and 3 . 36
D.5.1 Insert at position 2 . 36
D.5.2 Insert at position 3 . 36
D.6 Installation of application D with position of menu entry set to "00" . 36
D.7 Installation of application E with position of menu entry set to 20 . 37
D.8 Disabling/Locking of application legacy1 and application A with menu entries at position 1
respectively 6 . 37
D.9 Re-enabling/Unlocking of application legacy1 and application A with menu entries at position 1
respectively 6 . 37
D.10 Deletion of application A with menu entry at position 6 . 38
Annex E (informative): Change history . 39
History . 42
ETSI
---------------------- Page: 4 ----------------------
Release 15 5 ETSI TS 102 241 V15.0.0 (2019-01)
Intellectual Property Rights
Essential patents
IPRs essential or potentially essential to normative deliverables 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 (https://ipr.etsi.org/).
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.
Trademarks
The present document may include trademarks and/or tradenames which are asserted and/or registered by their owners.
ETSI claims no ownership of these except for any which are indicated as being the property of ETSI, and conveys no
right to use or reproduce any trademark and/or tradename. Mention of those trademarks in the present document does
not constitute an endorsement by ETSI of products, services or organizations associated with those trademarks.
Foreword
This Technical Specification (TS) has been produced by ETSI Technical Committee Smart Card Platform (SCP).
The present document details the stage 2 aspects (overall service description) for the support of an "Application
Programming Interface and Loader Requirements" [11].
The contents of the present document are subject to continuing work within TC SCP and may change following formal
TC SCP approval. If TC SCP decides to modify the contents of the present document, it will be re-released by TC SCP
with an identifying change of release date and an increase in version number as follows:
Version x.y.z
where:
x: the first digit:
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.
Modal verbs terminology
In the present document "shall", "shall not", "should", "should not", "may", "need not", "will", "will not", "can" and
"cannot" are to be interpreted as described in clause 3.2 of the ETSI Drafting Rules (Verbal forms for the expression of
provisions).
"must" and "must not" are NOT allowed in ETSI deliverables except when used in direct citation.
ETSI
---------------------- Page: 5 ----------------------
Release 15 6 ETSI TS 102 241 V15.0.0 (2019-01)
1 Scope
The present document defines the stage 2 description of the "Application Programming Interface and Loader
Requirements" [11] internal to the UICC.
This stage 2 describes the functional capabilities and the information flow for the UICC API implemented on the Java
Card™ Platform, 3.0.1 Classic Edition [2], [3] and [4].
The present document includes information applicable to network operators, service providers and UICC, server and
database manufacturers.
2 References
2.1 Normative references
References are either specific (identified by date of publication and/or edition number or version number) or
non-specific. For specific references, only the cited version applies. For non-specific references, the latest version of the
referenced document (including any amendments) applies.
Referenced documents which are not found to be publicly available in the expected location might be found at
http://docbox.etsi.org/Reference.
• 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.
NOTE: While any hyperlinks included in this clause were valid at the time of publication, ETSI cannot guarantee
their long term validity.
The following referenced documents are necessary for the application of the present document.
[1] Void.
[2] ORACLE: "Application Programming Interface, Java Card™ Platform, 3.0.1 Classic Edition".
[3] ORACLE: "Runtime Environment Specification, Java Card™ Platform, 3.0.1 Classic Edition".
[4] ORACLE: "Virtual Machine Specification Java Card™ Platform, 3.0.1 Classic Edition".
NOTE: ORACLE Java Card™ Specifications can be downloaded at
http://docs.oracle.com/javame/javacard/javacard.html.
[5] ETSI TS 101 220: "Smart Cards; ETSI numbering system for telecommunication application
providers".
[6] ETSI TS 102 221: "Smart Cards; UICC-Terminal interface; Physical and logical characteristics".
[7] ETSI TS 102 223: "Smart Cards; Card Application Toolkit (CAT)".
[8] ETSI TS 102 222: "Integrated Circuit Cards (ICC); Administrative commands for
telecommunications applications".
[9] ETSI TS 102 225: "Smart Cards; Secured packet structure for UICC based applications".
[10] ETSI TS 102 226: "Smart Cards; Remote APDU structure for UICC based applications".
[11] ETSI TS 102 240: "Smart Cards; UICC Application Programming Interface and Loader
Requirements; Service description".
[12] ETSI TS 123 040 (V6.6.0): "Digital cellular telecommunications system (Phase 2+); Universal
Mobile Telecommunications System (UMTS); Technical realization of Short Message Service
(SMS) (3GPP TS 23.040 version 6.6.0 Release 6)".
ETSI
---------------------- Page: 6 ----------------------
Release 15 7 ETSI TS 102 241 V15.0.0 (2019-01)
[13] ETSI TS 102 241: "Smart Cards; UICC Application Programming Interface (UICC API) for Java
Card™".
[14] ETSI TS 102 671: "Smart Cards; Machine to Machine UICC; Physical and logical characteristics".
[15] GlobalPlatform: "Card Specification, version 2.3.1".
NOTE: See http://www.globalplatform.org/.
[16] GlobalPlatform: "Java Card API and Export File for Card Specification, v2.2.1",
(org.globalplatform) v1.6.
NOTE: See http://www.globalplatform.org/.
[17] ETSI TS 102 613: "Smart Cards; UICC - Contactless Front-end (CLF) Interface; Physical and data
link layer characteristics".
[18] ETSI TS 102 705: "Smart Cards; UICC Application Programming Interface for Java Card™ for
Contactless Applications".
2.2 Informative references
References are either specific (identified by date of publication and/or edition number or version number) or
non-specific. For specific references, only the cited version applies. For non-specific references, the latest version of the
referenced document (including any amendments) applies.
• 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.
NOTE: While any hyperlinks included in this clause were valid at the time of publication, ETSI cannot guarantee
their long term validity.
The following referenced documents are not necessary for the application of the present document but they assist the
user with regard to a particular subject area.
Not applicable.
3 Definition of terms, symbols and abbreviations
3.1 Terms
For the purposes of the present document, the following terms apply:
applet: application built up using a number of classes which will run under the control of the Java Card™ virtual
machine
bytecode: machine independent code generated by a Java compiler and executed by the Java interpreter
class: type that defines the implementation of a particular kind of object
NOTE: A Class definition defines instance and class variables and methods.
framework: defines a set of Application Programming Interface (API) classes for developing applications and for
providing system services to those applications
java: object oriented programming language developed by Sun Microsystems designed to be platform independent
method: piece of executable code that can be invoked, possibly passing it certain values as arguments
NOTE: Every Method definition belongs to some class.
ETSI
---------------------- Page: 7 ----------------------
Release 15 8 ETSI TS 102 241 V15.0.0 (2019-01)
object: principal building block of object oriented programs
NOTE: Each object is a programming unit consisting of data (variables) and functionality (methods).
package: group of classes
NOTE: Packages are declared when writing a Java Card™ program.
toolkit application: application on the UICC card which can be triggered by toolkit events issued by the Terminal and
which can send proactive commands to the terminal
NOTE: These applications can be downloaded via any type of network.
UICC suspended context: internal status of the UICC stored during a successful UICC suspension procedure
according to ETSI TS 102 221 [6]
virtual machine: part of the Run-time environment responsible for interpreting the bytecode
3.2 Symbols
Void.
3.3 Abbreviations
For the purposes of the present document, the abbreviations given in ETSI TS 102 221 [6] and the following apply:
ADF Application Dedicated File
AID Application IDentifier
APDU Application Protocol Data Unit
API Application Programming Interface
DF Dedicated File (abbreviation formerly used for Data Field)
EF Elementary File
FFS For Further Study
JCRE Java Card™ Runtime Environment
MF Master File
NAA Network Access Application (e.g. SIM, USIM)
RFM Remote File Management
TLV Tag Length Value
4 Description
4.0 Purpose
The present document describes an API and a Runtime Environment for the UICC platform. This API and the Runtime
Environment allows application programmers to get access to the functions and data described in ETSI TS 102 221 [6]
and ETSI TS 102 223 [7] such that UICC based services can be developed and loaded onto a UICC, quickly and, if
necessarily, remotely, after the card has been issued.
This API is an extension to the "Application Programming Interface, Java Card™ Platform, 3.0.1 Classic Edition" [2],
the Runtime Environment is an extension of the "Runtime Environment Specification, Java Card™ Platform, 3.0.1
Classic Edition" [3].
ETSI
---------------------- Page: 8 ----------------------
Release 15 9 ETSI TS 102 241 V15.0.0 (2019-01)
4.1 UICC Java Card™ architecture
The overall architecture of the UICC API is based on Java Card™ Platform, 3.0.1 Classic Edition [2], [3] and [4].
UICC File 102 221 based Other Toolkit Applet
System Applications Applications (e.g. Toolkit
Server (e.g . SIM not based on service,
Applet or 102 221 Remote
USIM Applet) Management
Applications,
ADF File Browser
System Server Applications)
TM
Java Card uicc.access uicc.toolkit uicc.system
Packages package package package
TM
Java Card CAT Runtime Environment
UICC
Runtime Environment
Runtime
Toolkit Toolkit Triggering
Handlers Registry Entity
Environment
Items that are defined in this specification
Figure 1: UICC Java Card™ architecture
Java Card™ Runtime Environment: this is specified in "Runtime Environment Specification, Java Card™ Platform,
3.0.1 Classic Edition" [3] and is able to select any specific applet and transmit to it the process of its APDU.
CAT Runtime Environment: this is the CAT Runtime Environment composed of, the Toolkit Registry, the Toolkit
Handlers and the Triggering Entity. It is an addition to the JCRE.
UICC Runtime Environment: addition to the Java Card™ Runtime Environment.
Toolkit Registry: this is handling all the registration information of the Toolkit applets, and their link to the JCRE
registry.
Toolkit Handlers: this is handling the availability of the system handler and the toolkit protocol (i.e. Toolkit applet
suspension).
UICC File System Server: it contains the File System of the UICC specified in ETSI TS 102 221 [6] (i.e. the EF and
DF under the MF).
ADF File System Server: it contains the files of an ADF as specified in ETSI TS 102 221 [6] (i.e. the EF and DF under
the ADF).
Applets: these derive from javacard.framework.applet and provide the entry points: process, select, deselect, install as
defined in the "Runtime Environment Specification, Java Card™ Platform, 3.0.1 Classic Edition" [3].
Toolkit Applets: are the Java Card™ based implementation of Toolkit Applications, these derive from
javacard.framework.applet, to provide the same entry points, and provide one object implementing the
uicc.toolkit.ToolkitInterface interface, so that these applets can be triggered by an invocation of the processToolkit()
method. The Toolkit applet(s) AID are defined in ETSI TS 101 220 [5].
ETSI
---------------------- Page: 9 ----------------------
Release 15 10 ETSI TS 102 241 V15.0.0 (2019-01)
Remote Application Management Application: this is handling the loading, installation, management and removal of
applets and packages as specified in ETSI TS 102 226 [10].
Shareable interface: this is defined in the "Runtime Environment Specification, Java Card™ Platform, 3.0.1 Classic
Edition" specifications [2], [3] and [4].
CAT session: card session opened by a terminal supporting proactive UICC, starting with the download of the
Terminal Profile and ending with a subsequent reset or deactivation of the card.
5 File access API
5.0 Introduction
The file access API consists of the uicc.access package, which allows applets to access the file systems of the UICC.
5.1 FileView objects
MF
EF's
e.g.
DF Telecom
ADF 2
ADF 1
DF GSM
Figure 2: Logical structure of FileView
Any applet (not only Toolkit applets) is allowed to retrieve and use a FileView.
A FileView object can be retrieved by invoking one of the getTheFileView() methods defined in the UICCSystem class.
The UICC FileView allows to access the MF and all DFs and EFs that are located under the MF, including DF Telecom
and any access technology specific DF located under the MF, but not the files located under any ADF. This FileView
can be retrieved by invoking the getTheFileView() method from the UICCSystem. The only way to access the DF GSM
is to request the UICC FileView.
An ADF FileView allows to access only the DFs and EFs located under the ADF. It is not possible to access the MF or
any DF or EF located under the MF from an ADF FileView. An ADF FileView can be retrieved by invoking the
ge
...