ETSI TS 102 705 V11.0.0 (2013-09)

ETSI TS 102 705 V11.0.0 (2013-09)
Technical Specification
Smart Cards;
UICC Application Programming Interface for Java Card™
for Contactless Applications
(Release 11)
---------------------- Page: 1 ----------------------
Release 11 2 ETSI TS 102 705 V11.0.0 (2013-09)
Reference
RTS/SCP-THCIAPIVB00
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

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:

DECT , PLUGTESTS , UMTS and the ETSI logo are Trade Marks of ETSI registered for the benefit of its Members.

3GPP and LTE™ are Trade Marks of ETSI registered for the benefit of its Members and

GSM® and the GSM logo are Trade Marks registered and owned by the GSM Association.

Intellectual Property Rights ................................................................................................................................ 4

Foreword ............................................................................................................................................................. 4

1 Scope ........................................................................................................................................................ 5

2 References ................................................................................................................................................ 5

2.1 Normative references ......................................................................................................................................... 5

2.2 Informative references ........................................................................................................................................ 6

3 Definitions and abbreviations ................................................................................................................... 6

3.1 Definitions .......................................................................................................................................................... 6

3.2 Abbreviations ..................................................................................................................................................... 6

4 Description ................................................................................................................. .............................. 7

4.1 Architecture ........................................................................................................................................................ 7

4.2 Card Emulation Mode ........................................................................................................................................ 9

4.3 Reader Mode ...................................................................................................................................................... 9

4.4 Connectivity Service ........................................................................................................................................ 10

5 Interaction with Proactive Functionality ................................................................................................ 10

6 Java Card Resource Handling ................................................................................................................ 11

Annex A (normative): Java Card™ Platform HCI API for the UICC ........................................... 12

Annex B (normative): Java Card ™ Platform HCI API for the UICC identifiers ........................ 13

Annex C (normative): HCI API package version management ....................................................... 14

Annex D (informative): Change history ............................................................................................... 15

History .............................................................................................................................................................. 16

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

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

This Technical Specification (TS) has been produced by ETSI Technical Committee Smart Card Platform (SCP).

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 modifies 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:

y the second digit is incremented for all changes of substance, i.e. technical enhancements, corrections,

z the third digit is incremented when editorial only changes have been incorporated in the document.

The present document describes the UICC Application Programming Interface for Java Card™ for contactless

Applications. Its purpose is to provide access for a contactless Applet to the services provided by the HCI protocol

defined in [4] for the communication via the CLF. In the scope of the present document contactless means support for

the RF Technologies referenced by the HCI specification [4]. Low level functionality to manage gates and pipes as

defined in the HCI specification [4] is not in the scope of the present document. Registration of contactless parameters

and management of contactless Applets in card emulation mode is defined in "GlobalPlatform Card Specification

Amendment C" [8]. Related APIs are provided in "Java Card API and Export File for Card Specification v2.2.1

(org.globalplatform) v1.5" [12] and "Java Card Contactless API and Export File for Card Specification v2.2.1

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

• In the case of a reference to a TC SCP document, a non specific reference implicitly refers to the latest version

Referenced documents which are not found to be publicly available in the expected location might be found at

NOTE: While any hyperlinks included in this clause were valid at the time of publication ETSI cannot guarantee

The following referenced documents are necessary for the application of the present document.

[1] ISO/IEC 7816-3 (2006): "Identification cards - Integrated circuit cards - Part 3: Cards with

[2] ETSI TS 102 221: "Smart Cards; UICC-Terminal interface; Physical and logical characteristics".

[3] ETSI TS 101 220: "Smart Cards; ETSI numbering system for telecommunication application

[4] ETSI TS 102 622: "Smart Cards; UICC - Contactless Front-end (CLF) Interface; Host Controller

[5] ETSI TS 102 241: "Smart Cards; UICC Application Programming Interface (UICC API) for Java

[7] ETSI TS 102 226: "Smart Cards; Remote APDU structure for UICC based applications".

[8] GlobalPlatform: "GlobalPlatform Card Specification Version 2.2, Amendment C: Contactless

[9] Sun Microsystems "Application Programming Interface, Java Card™ Platform, 3.0.1 Classic

[10] Sun Microsystems "Runtime Environment Specification, Java Card™ Platform, 3.0.1 Classic

[11] Sun Microsystems "Virtual Machine Specification Java Card™ Platform, 3.0.1 Classic Edition".

NOTE: SUN Java Card Specifications can be downloaded at http://java.sun.com/products/javacard/specs.html.

[12] GlobalPlatform: "Java Card API and Export File for Card Specification v2.2.1

[13] GlobalPlatform: "Java Card Contactless API and Export File for Card Specification v2.2.1

[14] ETSI TS 102 613: "Smart Cards; UICC - Contactless Front-end (CLF) Interface, Part 1: Physical

The following referenced documents are not necessary for the application of the present document but they assist the

For the purposes of the present document, the following terms and definitions apply:

contactless mode: used as a generic term for "Card Emulation Mode" and "Reader Mode"

NOTE: An HCP message can be of type "command", "event" or "response to a command".

RF Technology: radio frequency technology supported by the HCI (TS 102 622 [4]) protocol specification

The present document describes an API and a Contactless Framework that enables Java Card Platform based

Applets, defined in [9], [10] and [11], to send and receive messages using the HCI protocol as specified in

TS 102 622 [4] and to act as contactless Applets. The Contactless Framework shall support card emulation mode and

The functionality of the Contactless Framework and the configuration of contactless parameters and the management of

contactless Applets in card emulation mode are based on the functionality provided by the Contactless Registry Service

(CRS), the related APIs, the CRS Application and other features and concepts which are defined in the "GlobalPlatform

Amendment C" [8] and the related APIs "Java Card API and Export File for Card Specification v2.2.1

(org.globalplatform) v1.5" [12] and "Java Card Contactless API and Export File for Card Specification v2.2.1

The API is event driven and based on the Observer/Listener pattern. Every HCI service is encapsulated by a dedicated

Service interface. These Service interfaces shall allow the registration of Listener Interfaces and the activation of

events. The Listener Interfaces shall be implemented by Java objects to receive HCI messages and events in the

onCallback method. The Registration of Listener Interfaces and activation of events shall be persistent.

An HCIMessage object shall encapsulates one HCP message according to the HCI protocol as specified in

TS 102 622 [4]. HCI message for the different contactless modes shall be identified by different types of interfaces. It is

not guaranteed that any Applet originated HCI messages are sent before the completion of the execution of the current

Applet. The Contactless Framework sends the Applet originated HCI messages in the same order as they are submitted

NOTE 1: The Contactless Framework may not have enough resources to send several HCI messages submitted

during the same onCallback method execution. The Applet should be aware of this limitation (e.g. use

suitable error handling strategy, or send only one HCI message in the onCallback method at a time).

Any onCallback() method of a Listener interface shall not be invoked again while another onCallback() method is still

being executed. The Contactless Framework shall be able to receive one or more HCI messages while waiting for a

response related to a command originated by the Applet (e.g. processing a request for parameters) especially for the

The HCI event EVT_FIELD_OFF shall be buffered and sent by the Contactless Framework as soon as the Contactless

All other HCI messages shall be delivered to the Applet instance in the same order as they were received by the

Contactless State is the logical state of the Contactless Framework it can take the value enabled and disabled. It refers to

This state can be changed with the mechanisms defined in TS 102 223 [6], and by the method

The Contactless State applies only to the Card Emulation Mode and the Reader Mode, and it does not apply to the

When the Contactless State is disabled, the Contactless Framework shall throw an HCIException with reason code

HCI_CURRENTLY_DISABLED when an Applet invokes a method which requires that the Contactless State