Developer Suite Getting Started

Developer Suite V3.
2
Getting Started
www.gemalto.com
All information herein is either public information or is the property of and owned solely by Gemalto NV. and/or its subsidiaries
who shall have and keep the sole right to file patent applications or any other kind of intellectual property protection in
connection with such information.
Nothing herein shall be construed as implying or granting to you any rights, by license, grant or otherwise, under any
intellectual and/or industrial property rights of or concerning any of Gemaltos information.
This document can be used for informational, non-commercial, internal and personal use only provided that:
The copyright notice below, the confidentiality and proprietary legend and this full warning notice appear in all copies.
This document shall not be posted on any network computer or broadcast in any media and no modification of any part of
this document shall be made.
Use for any other purpose is expressly prohibited and may result in severe civil and criminal liabilities.
The information contained in this document is provided AS IS without any warranty of any kind. Unless otherwise expressly
agreed in writing, Gemalto makes no warranty as to the value or accuracy of information contained herein.
The document could include technical inaccuracies or typographical errors. Changes are periodically added to the information
herein. Furthermore, Gemalto reserves the right to make any change or improvement in the specifications data, information,
and the like described herein, at any time.
Gemalto hereby disclaims all warranties and conditions with regard to the information contained herein, including all
implied warranties of merchantability, fitness for a particul ar purpose, title and non-infringement. In no event shall
Gemalto be liable, whether in contract, tort or otherwise, for any indirect, special or consequential damages or any
damages whatsoever including but not limited to damages resulting from loss of use, data, profits, revenues, or
customers, arising out of or in connection with the use or performance of information contained in this document.
Gemalto does not and shall not warrant that this product will be resistant to all possible attacks and shall not incur,
and disclaims, any liability in this respect. Even if each product is compliant with current security standards in force
on the date of their design, security mechanisms' resistance necessarily evolves according to the state of the art in
security and notably under the emergence of new attacks. Under no circumstances, shall Gemalto be held liable for
any third party actions and in particular in case of any successful attack against systems or equipment
incorporating Gemalto products. Gemalto disclaims any liability with respect to security for direct, indirect,
incidental or consequential damages that result from any use of its products. It is further stressed that independent
testing and verification by the person using the product is particularly encouraged, especially in any application in
which defective, incorrect or insecure functioning could result in damage to persons or property, denial of service or
loss of privacy.
Copyright 2009 Gemalto N.V. All rights reserved. Gemalto and the Gemalto logo are trademarks and service marks of
Gemalto N.V. and/or its subsidiaries and are registered in certain countries. All other trademarks and service marks, whether
registered or not in specific countries, are the property of their respective owners.
GEMALTO, B.P. 100, 13881 GEMENOS CEDEX, FRANCE.
Tel: +33 (0)4.42.36.50.00 Fax: +33 (0)4.42.36.50.90
Printed in France. Document Reference: D1123621A
March 30, 2009
C
o
n
t
e
n
t
s
Chapter 1 Introduction 1
The J ava Card Environment . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1
The GlobalPlatform Specifications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2
The OpenCard Framework . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2
J ava Card Concepts and Terminology . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2
Applets . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2
GSM and 3G Extension to the J ava Card Specification . . . . . . . . . . . . . . . . . . . . 3
CDMA Extensions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3
Client Applications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4
Targets . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4
Packages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4
File Formats . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5
CAP Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5
J AR Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5
SAP Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5
IJ C Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5
Projects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6
AIDs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6
The Developer Suite V3.2 Tools . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6
Developer Suite V3.2 Development Scenarios . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9
Development Phase . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9
Tools Used During the Test Phase . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10
Preface 11
Whats New in This Release . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11
Who Should Read this Book . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11
Conventions Used in this Document . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11
Chapter 3 Installing Developer Suite V3.2 13
System Requirements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13
Hardware Requirements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13
Software Requirements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13
Installation Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14
Before Installing Developer Suite V3.2 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14
Installing Developer Suite V3.2 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14
After Installing Developer Suite V3.2 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15
Apply and Import A License for Developer Suite V3.2 . . . . . . . . . . . . . . . . . . . . 15
Importing WTK Devices Into Eclipse . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16
Chapter 4 Developer Suite V3.2 Components 19
License Key Manager . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19
Eclipse . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20
Static Content Explorer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20
Menu to Access . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21
Static Content Explorer View . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21
Static Content Explorer Toolbar . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22
J CardManager . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26
iv Contents
Application Manager 2G/3G . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26
Simulators . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26
The SIM Card Simulators . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27
The Mobile Simulators . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27
Simulation Chain 2G and Simulation Chain 3G . . . . . . . . . . . . . . . . . . . . . . . . . 28
Tools . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28
Cap File Utility . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28
Crypto Tool . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28
File System Editor . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28
Key File Editor . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29
OTA Interpreter . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29
Script Editor . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29
WTKOCF Bridge . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29
Chapter 5 Getting Started with Developer Suite V3.2 31
Developer Suite V3.2 Working Environment . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31
Developer Suite Perspective . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31
J ava Card Project Management View . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32
Project Wizards And Applications Wizards . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33
Project Wizards: . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33
Applications Wizards - Twin displays: . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33
J ava Card Project Import and Export . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34
Import and Export Menu Access . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34
Importing Developer Suite Projects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35
Exporting Developer Suite Projects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 36
Project Properties Editor . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 38
How To Access . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 38
Applications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 40
Export Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 40
GDP and GBP pages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 41
The Out Line Viewer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 41
A Typical Development Cycle . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 41
How to import examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 44
Chapter 6 M-NFC Enabled JavaCard Applet/Servlet 47
NFC Contactless Technology . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 47
NFC Technology Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 47
Three Modes of Interaction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 47
NFC Contactless J avaCard Applets . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 48
Card Emulation Applets . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 49
Reader Emulation Applets . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 49
Use of SIM / UICC Toolkit In NFC Contactless Applets . . . . . . . . . . . . . . . . 49
NFC Demo Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 50
Creating An NFC Demo . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 50
Creating Emulation and Reader Project . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 50
Creating an Emulation Servlet . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 51
Creating a Reader Servlet . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 51
Debugging the Servlet Using the Mobile Simulator 3G . . . . . . . . . . . . . . . . . . . . . . . 53
Starting the Projects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 53
Starting the Reader Project . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 53
Starting the Emulation Project . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 55
Two Ways To Use . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 55
Use The STK Method: . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 55
Use The SCWS Feature: . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 57
Contents v
The Card Simulator Proxy . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 60
The OCF View . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 62
Contact-less Tag Application: . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 63
How to create a contact-less tag application . . . . . . . . . . . . . . . . . . . . . . . . . . . . 63
How to program a contact-less tag application . . . . . . . . . . . . . . . . . . . . . . . . . . 64
How to run a contact-less tag application . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 65
Contact-less Reader Application . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 69
How to create a contact-less reader application . . . . . . . . . . . . . . . . . . . . . . . . . 69
How to program a contact-less reader application . . . . . . . . . . . . . . . . . . . . . . . 70
How to run a contact-less reader application. . . . . . . . . . . . . . . . . . . . . . . . . . . . 72
Chapter 7 Worked Example with USIM Toolkit Applet 77
Creating the J ava Card Project with the Eclipse IDE . . . . . . . . . . . . . . . . . . . . . . . . 77
Adding a USIM Toolkit Applet to a Project . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 84
The Toolkit Applet Wizard . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 84
Debugging the USIM Toolkit Applet . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 91
Client Applications Used . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 91
Mobile Simulator Versions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 92
Applet Debugging Steps . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 93
Debugging the Applet Using the Mobile Simulator 3G . . . . . . . . . . . . . . . . . . . . 93
Step 1: Setting breakpoints in the applets code . . . . . . . . . . . . . . . . . . . . . . 93
Step 2: Debugging the project . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 94
Step 3: Operating the Client Application (Mobile Simulator) . . . . . . . . . . . . . 95
Step 4: Notification that execution has stopped on a breakpoint . . . . . . . . . 96
Step 5: Bug detection and correction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 97
Loading and Installing the Applet in a Card using Eclipse . . . . . . . . . . . . . . . . . . . . . 97
Testing the USIM Toolkit Applet in a Real Card . . . . . . . . . . . . . . . . . . . . . . . . . . . . 98
Chapter 8 Worked Example with JCRMI Applet and Client 99
Creating the J ava Card Project with Eclipse IDE . . . . . . . . . . . . . . . . . . . . . . . . . . . 99
Creating a Remote Object Interface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 99
The Remote Object Wizard . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 100
Adding a J CRMI Applet to a Project . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 104
The J CRMI Applet Wizard . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 105
Creating a J CRMI Client Project . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 107
The J CRMI/APDU OCF Client Project Wizard . . . . . . . . . . . . . . . . . . . . . . . . . 107
Debugging the J CRMI Applet Using the J CRMI Client Application . . . . . . . . . . . . . 108
Step 1: Call the new function in the J CRMI client . . . . . . . . . . . . . . . . . . . . 108
Step 2: Setting breakpoints in the applets code . . . . . . . . . . . . . . . . . . . . . 109
Step 3: Debugging the project . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 109
Step 4: Notification that execution has stopped on a breakpoint . . . . . . . . 111
Step 5: Bug detection and correction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 111
Loading and Installing the Applet in a Card using Eclipse . . . . . . . . . . . . . . . . . . . . 111
Testing the J CRMI Applet in a Real Card . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 111
Chapter 9 Worked Example with JavaCard Applet and Client 113
Creating the J ava Card Project with Eclipse IDE . . . . . . . . . . . . . . . . . . . . . . . . . . 113
Adding a J avaCard Applet to the J ava Card Project . . . . . . . . . . . . . . . . . . . . . . . . 113
The J avaCard Applet Wizard . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 114
Debugging the J ava Card Applet Using J CardManager . . . . . . . . . . . . . . . . . . . . . 114
Step 1: Setting breakpoints in the applets code . . . . . . . . . . . . . . . . . . . . . 114
Step 2: Debugging the project with J CardManager . . . . . . . . . . . . . . . . . . 115
Creating the OCF Client Application . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 115
vi Contents
Debugging the J ava Card Applet Using the OCF Client Application . . . . . . . . . . . . 115
Loading and Installing the Applet in a Card using Eclipse . . . . . . . . . . . . . . . . . . . . 116
Testing the J ava Card Applet in a Real Card . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 116
Chapter 10 Worked Example with SATSA MIDlets 117
Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 117
Creating the Applet . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 117
Building the Midlet . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 119
Creating the MIDlet . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 120
Adding a SATSA Card Access Method . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 122
Debugging the Applet and MIDlet . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 123
Chapter 11 Worked Example with Servlet and Toolkit 127
Creating the J ava Card Project with the Eclipse IDE . . . . . . . . . . . . . . . . . . . . . . . 127
Adding a Servlet to a Project . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 134
The Servlet Wizard . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 135
Debugging the Servlet . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 145
Client Applications Used . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 145
Mobile Simulator Versions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 146
Servlet Debugging Steps . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 146
Debugging the Servlet Using the Static Content Explorer . . . . . . . . . . . . . . . . . 147
Step 1: Setting breakpoints in the Servlets code . . . . . . . . . . . . . . . . . . . . 147
Step 2: Debugging the project . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 147
Step 3: Operating the Client Application (Static Content Explorer) . . . . . . . 149
Step 4: Notification that execution has stopped on a breakpoint . . . . . . . . 150
Step 5: Bug detection and correction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 150
Debugging the Servlet Using the Mobile Simulator 3G . . . . . . . . . . . . . . . . . . . 150
Loading and Installing the Servlet in a Card using Eclipse . . . . . . . . . . . . . . . . . . . 152
Testing the Servlet in a Real Card . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 153
Chapter 12 Worked Example with HTTP MIDlet 155
Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 155
Creating the Servlet . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 155
Creating the HTTP MIDlet . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 156
Debugging the Applet and MIDlet . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 157
Chapter 13 Creating and Using Libraries 159
How to Create Libraries . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 159
How to Use Libraries . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 159
How to Modify the Gxsc Script File . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 160
Chapter 14 Using the Application Manager 161
Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 161
Overview of Defining and Running an Application . . . . . . . . . . . . . . . . . . . . . . . . . 162
Starting the Application Manager . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 162
The Application Manager Window . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 162
Chapter 15 The Script Editor 163
What is a Script? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 163
Starting the Script Editor . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 163
Contents vii
The Script Editor Interface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 164
Chapter 16 The File System Editor 167
What is the File System Editor? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 167
The File System Editor Interface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 168
Contextual Commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 169
Chapter 17 The Key File Editor 171
Appendix A Managing OTA Profiles 173
The OTA Profile Manager . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 173
SMS Options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 174
Text and Data Format . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 175
Secured Message Options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 176
SPI . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 176
KIc . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 178
KID . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 179
Configuring Data Encryption . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 179
Configuring CC, RC, or DS Security Settings . . . . . . . . . . . . . . . . . . . . . . . 180
Expert Options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 180
Concatenation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 181
Command Packet Header . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 181
Response Packet Header . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 182
Appendix B The JCardManager 185
Logical Channels . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 186
Script Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 186
Traces . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 187
Terminology 189
Abbreviations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 189
References 195
Standards and Specifications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 195
Web Site Addresses . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 196
Recommended Reading . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 196
Index 197
viii Contents
List of Figures
Figure 1 - The J ava Card Environment:a PC/Workstation-Resident Client Application 1
Figure 2 - The Compilation, Loading and Conversion Process . . . . . . . . . . . . . . . . . . 5
Figure 3 - The AID Format . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6
Figure 4 - The Development Phase . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10
Figure 5 - Developer Suite V3.2 - Not Registered . . . . . . . . . . . . . . . . . . . . . . . . . . . 15
Figure 6 - License Key Manager . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15
Figure 7 - Profile Generation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16
Figure 8 - Importing Wireless WTK - Preference Window . . . . . . . . . . . . . . . . . . . . . 17
Figure 9 - Importing Wireless WTK - Import Devices . . . . . . . . . . . . . . . . . . . . . . . . 17
Figure 10 - Importing Wireless WTK - Browse For Folder Window . . . . . . . . . . . . . . 18
Figure 11 - Importing Wireless WTK - Devices Refreshed . . . . . . . . . . . . . . . . . . . . 18
Figure 12 - The Developer Suite V3.2 Plug-ins for Eclipse . . . . . . . . . . . . . . . . . . . . 20
Figure 13 - Static Content Menu . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21
Figure 14 - Static Content Manager View . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21
Figure 15 - Memory status bar . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21
Figure 16 - Create New Folder - Select A Parent Folder . . . . . . . . . . . . . . . . . . . . . . 23
Figure 17 - Create New Folder - Enter Path . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23
Figure 18 - Create New Folder - Content Structure Updated . . . . . . . . . . . . . . . . . . 24
Figure 19 - Launch Browser . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25
Figure 20 - Static Content Explorer Preference . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25
Figure 21 - Sim Card Simulator Window . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27
Figure 22 - The Mobile Simulator Parameters Window . . . . . . . . . . . . . . . . . . . . . . . 28
Figure 23 - The WTKOCF Bridge . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29
Figure 24 - Switch to Developer Suite Perspective . . . . . . . . . . . . . . . . . . . . . . . . . . 32
Figure 25 - J ava Card Project Management View . . . . . . . . . . . . . . . . . . . . . . . . . . . 32
Figure 26 - Applications Wizards . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33
Figure 27 - Application Wizard for Servlet . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33
Figure 28 - File Menu - Import & Export . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34
Figure 29 - Project Contextual Menu - Import & Export . . . . . . . . . . . . . . . . . . . . . . . 34
Figure 30 - Import Main Page . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35
Figure 31 - Import Projects Found . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 36
Figure 32 - Developer Suite Export Wizard - Step 1 . . . . . . . . . . . . . . . . . . . . . . . . . 37
Figure 33 - Project Properties Editor . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 38
Figure 34 - Open With Project Properties Editor . . . . . . . . . . . . . . . . . . . . . . . . . . . . 38
Figure 35 - Overview of Project Properties Editor . . . . . . . . . . . . . . . . . . . . . . . . . . . 39
Figure 36 - Project Properties Editor - Application Tab . . . . . . . . . . . . . . . . . . . . . . . 40
Figure 37 - Project Properties Editor - Exported Files Tab . . . . . . . . . . . . . . . . . . . . 40
Figure 38 - Development Flow with Developer Suite V3.2 Tools . . . . . . . . . . . . . . . 43
Figure 39 - . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 44
Figure 40 - . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 45
Figure 41 - . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 46
Figure 42 - NFC Phone Interaction Modes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 48
Figure 43 - NFC Applet - Card Emulation Mode . . . . . . . . . . . . . . . . . . . . . . . . . . . . 48
Figure 44 - NFC Applet - Reader Emulation Mode . . . . . . . . . . . . . . . . . . . . . . . . . . 48
Figure 45 - Card Emulation Applets . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 49
Figure 46 - Reader Emulation Applets . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 49
Figure 47 - Emulation Servlet Creation - Step 1 - Technology Selection . . . . . . . . . 51
Figure 48 - Reader Servlet Creation - Step 1 - Technology Selection . . . . . . . . . . . 52
Figure 49 - Reader Servlet Creation Step 1 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 52
Figure 50 - Select An Emulation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 53
Figure 51 - Start Reader Project - Select Reader Project . . . . . . . . . . . . . . . . . . . . . 53
Figure 52 - Start Reader Project- Mobile Simulator Launching In Process . . . . . . . . 53
Figure 53 - Start Reader Project - MS 3G Started With Reader Servlet . . . . . . . . . . 54
Figure 54 - Start Reader Project - Enter Pin Code for MS 3G . . . . . . . . . . . . . . . . . . 54
Contents ix
Figure 55 - Start Reader Project - Mobile Simulator Home Screen . . . . . . . . . . . . . . 55
Figure 56 - Start Emulation Project - MS 3G Started With Emulation Servlet . . . . . . 55
Figure 57 - Using STK Method - Switch Reader Servlet To Reader Mode . . . . . . . . 56
Figure 58 - Using STK Method - NFC Window Menu . . . . . . . . . . . . . . . . . . . . . . . . 56
Figure 59 - Using STK Method - NFC Management Window . . . . . . . . . . . . . . . . . . 56
Figure 60 - Using STK Method - Transfer Completed . . . . . . . . . . . . . . . . . . . . . . . . 57
Figure 61 - Using the SCWS Feature - Mobile Simulator Select Button . . . . . . . . . . 57
Figure 62 - Using the SCWS Feature - Load URL Menu . . . . . . . . . . . . . . . . . . . . . 57
Figure 63 - Using the SCWS Feature - Load URL Dialogue . . . . . . . . . . . . . . . . . . . 58
Figure 64 - Using the SCWS Feature - NFC Application Reader Demo . . . . . . . . . . 58
Figure 65 - Using the SCWS Feature - Switch Reader Servlet Mode . . . . . . . . . . . . 58
Figure 66 - Card Simulator Console . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 60
Figure 67 - Card Simulator Console - Configuration Dialogue . . . . . . . . . . . . . . . . . 60
Figure 68 - Card Simulator Console - Confirm Terminating . . . . . . . . . . . . . . . . . . . 61
Figure 69 - OCF View . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 62
Figure 70 - Tag Wizards . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 63
Figure 71 - Souce Code . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 65
Figure 72 - . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 66
Figure 73 - . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 66
Figure 74 - . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 67
Figure 75 - . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 67
Figure 76 - . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 67
Figure 77 - . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 68
Figure 78 - . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 68
Figure 79 - . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 69
Figure 80 - . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 70
Figure 81 - . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 71
Figure 82 - . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 72
Figure 83 - . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 72
Figure 84 - . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 72
Figure 85 - . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 73
Figure 86 - . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 73
Figure 87 - . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 74
Figure 88 - . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 74
Figure 89 - J ava Card Project Creation Wizard - Step 1 . . . . . . . . . . . . . . . . . . . . . . 78
Figure 94 - Adding a DAP Control . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 83
Figure 95 - The Toolkit Applet Wizard Step 1 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 84
Figure 99 - The Toolkit Applet Wizard Step 4 Menus . . . . . . . . . . . . . . . . . . . . . 86
Figure 100 - The Toolkit Applet Wizard Step 4 Priority and Timers . . . . . . . . . . 87
Figure 101 - The Toolkit Applet Wizard Step 4 Channels . . . . . . . . . . . . . . . . . . 88
Figure 102 - The Toolkit Applet Wizard Step 4 Min. Security Level . . . . . . . . . . 88
Figure 103 - The Toolkit Applet Wizard Step 4 Security Parameters . . . . . . . . . 89
Figure 104 - The Toolkit Applet Wizard Step 4 SIM Access Parameters . . . . . . 90
Figure 105 - The Toolkit Applet Wizard Termination . . . . . . . . . . . . . . . . . . . . . . . 91
Figure 106 - Interactive Debugging of USIM Toolkit Applets . . . . . . . . . . . . . . . . . . . 93
Figure 107 - Setting Breakpoints in the J ava Code . . . . . . . . . . . . . . . . . . . . . . . . . . 93
Figure 108 - Debug window . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 94
Figure 109 - Mobile Simulator 3G Waiting for User Interaction . . . . . . . . . . . . . . . . . 95
Figure 110 - The Triggered Breakpoint in the Eclipse IDE . . . . . . . . . . . . . . . . . . . . 96
x Contents
Figure 111 - Accessing the Script File in Eclipse . . . . . . . . . . . . . . . . . . . . . . . . . . . 97
Figure 112 - Script Editor Showing the Load Script . . . . . . . . . . . . . . . . . . . . . . . . . . 98
Figure 113 - Remote Object Wizard Step 1 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 100
Figure 115 - The Add Method Dialog Box . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 101
Figure 116 - The Add Method Dialog Box (2) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 102
Figure 118 - J ava Card Project Implementation Source . . . . . . . . . . . . . . . . . . . . . 104
Figure 119 - The J CRMI Applet Wizard Step 1 . . . . . . . . . . . . . . . . . . . . . . . . . . 105
Figure 122 - J CRMI/OCF Client Project Wizard Step 3 . . . . . . . . . . . . . . . . . . . . 108
Figure 123 - Call New Function . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 109
Figure 124 - Setting the Breakpoint for J CRMI Client Example . . . . . . . . . . . . . . . 109
Figure 125 - New Debug Configuration for Client Test Project . . . . . . . . . . . . . . . . 110
Figure 126 - Edit Runtime Configuration Window . . . . . . . . . . . . . . . . . . . . . . . . . . 110
Figure 127 - Edit Runtime Configuration Window . . . . . . . . . . . . . . . . . . . . . . . . . . 115
Figure 128 - Remote Method Definition . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 118
Figure 129 - Adding the Add Method . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 119
Figure 130 - Create New Midlet Suite Project . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 119
Figure 131 - J 2ME Midlet Project Wizard Step 2 . . . . . . . . . . . . . . . . . . . . . . . . . . . 120
Figure 132 - Create New J 2ME Midlet . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 120
Figure 133 - New J 2ME Midlet Wizard - Step 1 . . . . . . . . . . . . . . . . . . . . . . . . . . . 121
Figure 134 - Source Folder Selection Window . . . . . . . . . . . . . . . . . . . . . . . . . . . . 121
Figure 135 - SATSA Midlet Access Wizard Step 1 . . . . . . . . . . . . . . . . . . . . . . . . 122
Figure 136 - SATSA Midlet Access Wizard Step 2 . . . . . . . . . . . . . . . . . . . . . . . . 122
Figure 137 - Calling the Remote J CRMI Method . . . . . . . . . . . . . . . . . . . . . . . . . . . 123
Figure 138 - Debug Configuration for the J CRMI Applet Project . . . . . . . . . . . . . . . 124
Figure 139 - Specifying the MIDlet Project . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 124
Figure 140 - The WTK Mobile Simulator . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 125
Figure 141 - J ava Card Project Creation Wizard - Step 1 . . . . . . . . . . . . . . . . . . . . 128
Figure 146 - Adding a DAP Control . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 133
Figure 147 - The Servlet Wizard Step 1 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 135
Figure 149 - The Servlet Wizard - Step 3 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 136
Figure 152 - The Servlet Wizard Step 5 Menus . . . . . . . . . . . . . . . . . . . . . . . . . 138
Figure 153 - The SCWS Wizard Step 5 Priority and Timers . . . . . . . . . . . . . . . 139
Figure 154 - The SCWS Wizard Step 5 Channels . . . . . . . . . . . . . . . . . . . . . . . 140
Figure 155 - The SCWS Wizard Step 5 Min. Security Level . . . . . . . . . . . . . . . 140
Figure 156 - The SCWS Wizard Step 5 Security Parameters . . . . . . . . . . . . . . 141
Figure 157 - The SCWS Wizard Step 5 SIM Access Parameters . . . . . . . . . . . 142
Figure 158 - The SCWS Wizard Step 5 Number of services . . . . . . . . . . . . . . . 143
Figure 159 - The SCWS Wizard Step 5 Toolkit Parameters DAP . . . . . . . . . . . 143
Figure 160 - The SCWS Wizard Step 5 UICC Access Application paras . . . . . 144
Figure 161 - The SCWS Wizard Step 5 UICC Admin Access Application paras 144
Figure 162 - The Servlet Wizard Termination . . . . . . . . . . . . . . . . . . . . . . . . . . . . 145
Figure 163 - Interactive Debugging of USIM Toolkit Applets . . . . . . . . . . . . . . . . . . 146
Figure 164 - Setting Breakpoints in the J ava Code . . . . . . . . . . . . . . . . . . . . . . . . . 147
Figure 165 - Debug Window . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 148
Figure 166 - Static Content Explorer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 149
Contents xi
Figure 167 - The Triggered Breakpoint in the Eclipse IDE . . . . . . . . . . . . . . . . . . . 150
Figure 168 - Mobile Simulator 3G Waiting for User Interaction) . . . . . . . . . . . . . . . 151
Figure 169 - Accessing the Script File in Eclipse . . . . . . . . . . . . . . . . . . . . . . . . . . 153
Figure 170 - Script Editor Showing the Load Script . . . . . . . . . . . . . . . . . . . . . . . . . 153
Figure 171 - HTTP Midlet Access Wizard- Step 1 . . . . . . . . . . . . . . . . . . . . . . . . . . 156
Figure 172 - HTTP Midlet Access Wizard - Step 2 . . . . . . . . . . . . . . . . . . . . . . . . . 157
Figure 173 - Debug Configuration for the J CRMI Applet Project . . . . . . . . . . . . . . . 158
Figure 174 - Specifying the MIDlet Project . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 158
Figure 175 - The Application Manager Main Window . . . . . . . . . . . . . . . . . . . . . . . 162
Figure 176 - Script Editor Window . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 164
Figure 177 - Script Editor The Add/Remove Commands Window . . . . . . . . . . . . 164
Figure 178 - The Select the Target Window . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 167
Figure 179 - File System Editor . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 168
Figure 180 - Key File Editor . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 171
Figure 181 - The OTA Profile Manager Window . . . . . . . . . . . . . . . . . . . . . . . . . . . 173
Figure 182 - The Originating Address Editor Window . . . . . . . . . . . . . . . . . . . . . . . 174
Figure 183 - Triple DES Encryption . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 180
Figure 184 - The Initial J CardManager Window . . . . . . . . . . . . . . . . . . . . . . . . . . . 185
List of Tables
Table 1 - Development Stages and Steps . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7
Table 2 - Accessing Developer Suite V3.2 Tools . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8
Table 3 - Simulator Versions Standards Compatibility . . . . . . . . . . . . . . . . . . . . . 27
Table 4 - Export Options and Relative Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 37
Table 5 - Change Dependencies . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 39
Table 6 - Debugging and Testing Tools According to Applet Type . . . . . . . . . . . . . . 42
Table 7 - Mobile Simulator Capabilities . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 92
Table 8 - Mobile Simulator Capabilities . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 146
Table 9 - Contextual Commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 169
1
Introduction
This chapter introduces the J ava Card environment and explains the main J ava Card
concepts and terminology. It then introduces the Developer Suite V3.2 tools and
describes when to use them during the development, conversion, and test phases of a
project.
The Java Card Environment
Figure 1 shows the main components of a J ava Card application.
Figure 1 - The Java Card Environment:a PC/Workstation-Resident Client
Application
J ava Cards contain a microprocessor, but have no means of directly receiving input or
displaying output. They must therefore be connected to a card reader, also known as a
card acceptance device (CAD), or terminal, which is in turn connected to or contained
in:
A workstation such as a personal computer (PC) via a USB or serial cable.
A mobile phone
Any other smart card reading device.
The card in a card reader and the client application communicate using application
protocol data unit (APDU) commands. APDUs contain command instructions, data and
responses. Refer to the ISO 7816-3 standard for detailed information on APDUs.
Smart card reader
Java Card with
applet loaded into
the card
Communications
using APDUs
Smart card reader
to PC link (USB or
serial ports)
PC/Workstation
Client application
resident on PC/
Workstation
2 Introduction
The GlobalPlatform Specifications
The GlobalPlatform (GP) is a generic framework for the management of
multi-application smart cards, devices and systems. It provides mechanisms for
securely managing the applications on smart cards in order to extend the J ava Card
environment.
USIM R6 and R-UIM cards are GP 2.1.1 compliant. The other members of the
GemXplore card family are fully compatible with the GP 2.0.1 standard.
The GP specification includes several components:
A set of commands to manage the life cycle of the card and its applications, load,
install, and delete the applications on the card, and manage the cards security by,
for example, updating keys and setting up a secure channel between the card and
the terminal.
An API, consisting of a single J ava package, or g. gl obal pl at f or m(or
vi sa. openpl at f or min the case of GP 2.0.1) that can be used by application
developers to access the GP features, in particular the applications life cycle and
the secure messaging mechanism.
A documented specification, which describes in detail the commands available and
the principles of interoperability between the J ava Card and GP card environments.
The current version is GP 2.1.1.
To obtain the GP specification, go to www.globalplatform.org.
The OpenCard Framework
The OpenCard Framework (OCF) is an open architecture and a set of APIs providing a
common interface for card readers and smart card-based applications. The OCF
enables you to develop client applications that will work on a variety of different
suppliers equipment and platforms. The Developer Suite V3.2 tools use the OCF for all
communications between client applications, card readers, real cards and simulated
cards. An OCF to PCSC bridge is used to be able to manage PCSC card readers in
OCF.
To obtain further details about the OpenCard Framework, go to www.opencard.org.
Java Card Concepts and Terminology
Applets
An applet is a J ava program designed to work within the J ava Card environment. Apart
from being programmed in J ava, a J ava Card applet is very different from a web
browser-based J ava applet.
Applets can be pre-installed on a card during the manufacturing process. They can
also, however, be downloaded to a card at subsequent stages of the cards life cycle.
On GSM cards, for example, applets can be downloaded:
Note: The GlobalPlatform specification was formerly named Open Platform. OP 2.0.1
and GP 2.0.1 are exactly the same apart from the name.
Note: An applet is often referred to in specifications as a J ava Card application. The
GlobalPlatform documentation, for example, is not specific to J ava Cards and uses
the term application throughout. You can also load packages with no applets onto
cards, and applets can have instances, so application is a generic term.
Introduction 3
From the wireless network using over the air techniques.
At the point-of-sale.
Many different applets can be installed on the same card, and multiple instances of the
same applet can be created (instantiated) and run on the same card. You can also
load packages containing library functions that are used by other applets on the card.
In the telecommunications environment, J ava Card applets are server applications
running in the card. These applets react to the mobile equipment (ME) user interface or
to an OTA application.
A telecom J ava card can manage three types of API:
Toolkit
J ava Card
GlobalPlatform
All GemXplore cards can support all three types of API.
Applets written for telecom applications can use the SAT (SIM Application Toolkit),
CAT (Card Application Toolkit), USAT (USIM Application Toolkit) or CCAT (CDMA
Card Application Toolkit) APIs. These applets must be created using the appropriate
Toolkit Applet wizard. See Chapter 7 - Worked Example with USIM Toolkit Applet for
an example of how to create a USIM Toolkit applet.
Applets written for J ava Card applications can be written using either exclusively J ava
Card API methods (J ava Card applets), or a combination of J ava Card and
GlobalPlatform methods (J ava Card-GP applets). Both types of applets must be
created using the J ava Card Applet wizard. See Chapter 8 - Worked Example with
J CRMI Applet and Client. The choice of J ava Card or J ava Card-GP is made during
step 4 of the J ava Card Applet wizard by checking (or not) Global Platform
specifications, as shown on page 114.
GSM and 3G Extension to the Java Card Specification
In order to support the SIM Toolkit mechanisms used by applications on GSM cards,
the J ava Card API has been extended with a GSM-specific API.
This API is defined in ETSI 102241 (a common Toolkit API for Telecom technologies)
and either the 3GPP TS 43.019 (for 2G cards) or 3GPP 31130 specification (for 3G
cards). Very basically, it enables applets to access the file system on a SIM card, and
to perform proactive exchanges with a mobile as defined in the SIM Toolkit
specification.
CDMA Extensions
Developer Suite V3.2 provides support for CDMA target cards, allowing you to
generate skeleton code for CCAT (CDMA Card Application Toolkit) applications.
You can use Developer Suite V3.2s J ava Card project and applet creation wizards to
generate CCAT-compatible skeleton code for your project, then test and simulate
application deployment using Developer Suite V3.2 tools such as the Mobile Simulator
CDMA and the script editor.
The R-UIM card profile complies with the following specifications:
3GPP2 CS0035-A (Version 1.0)
ETSI TS 102.223 (CAT)
ETSI TS 102.241 (UICC API)
J ava Card 2.2.1
4 Introduction
Client Applications
A client application is a software program running on a workstation. The client
application communicates with an applet that has been uploaded and installed on a
card.
The client application controls all input and output operations on behalf of the applet,
and sends requests for processing to the applet. The applet acts as a server,
responding to the client applications requests.
The following client applications are provided with Developer Suite V3.2:
The Mobile Simulator GSM, Mobile Simulator 3G, and Mobile Simulator CDMA.
The J CardManager.
Simulation Chain 2G and Simulation Chain 3G.
SATSA Midlet
You can also develop your own custom client applications with Eclipse. Developer
Suite V3.2 provides you with wizards to help you do this. To obtain further details about
developing your own client applications, see the documentation available at
www.opencard.org.
Targets
Applets can be loaded onto two types of target:
A real J ava Card, which can be either ETSI 102-224/102-225/102-226 compatible,
or GlobalPlatform compatible.
A card simulator supplied with Developer Suite V3.2, which simulates a card/card
reader combination. The card simulator makes it possible to develop applets
without having access to real J ava Cards or a card reader and also allows you to
debug your applets.
Packages
A package is a J ava programming term to describe the collection of related classes
and interfaces to which an applet belongs. Since an entire package can be uploaded to
a card, it is easy to upload several applets at the same time. If you choose to develop
your own client application, the client applications classes must belong to a different
package than the applets classes. A package can also be created that only contains
library classes to be loaded, that is, no applets.
In global system for mobile communications (GSM) environments, a package is often
referred to as an executable load file.
Introduction 5
File Formats
Before an applet can be loaded onto a card, it must be converted to byte code that can
be interpreted by the J ava Card Virtual Machine (J CVM) on the card. The process is
illustrated in Figure 2 - The Compilation, Loading and Conversion Process:
Figure 2 - The Compilation, Loading and Conversion Process
The process involves converting the J ava source files first to compiled Class files, then
to byte code. The byte code is then loaded onto the target card, where it is interpreted
by the J ava Card Virtual Machine.
CAP Files
The .cap file format is the loadable file format defined by the J ava Card
specification. It defines the binary representation of an applet (or library for packages
with no applets) that can be loaded and executed on a J ava Card. A .cap file consists
of a set of components, each of which describes a different aspect of the contents. The
set of components in a CAP file includes a number of mandatory components defined
in the J ava Card specification, but may also include a number of optional components
that are not necessarily supported by all card manufacturers.
For a complete description of the J ava Card CAP file format, see Suns Java Card 2.2.1
Virtual Machine Specification.
JAR Files
The .jar file structure is also defined in the J ava Card specification. A .jar file is NOT
a loadable file format, it is simply an archive (similar to a .zip archive) containing a
set of .cap files, each .cap file corresponding to one loadable component. In order to
be loaded on a card, a .jar file must systematically be converted into a loadable .cap
file (this very basically consists in concatenating the individual .cap components from
the .jar archive).
SAP Files
Simulator Applet Package (SAP) files are a Gemalto-proprietary version of the CAP
files. Although they cannot be downloaded onto a real card, when loaded into
Developer Suite V3.2s card simulator they accurately simulate an applet in almost all
other ways.
IJC Files
The .ijc format is not strictly speaking a standard file format. It was created by the SIM
Alliance because the converter provided by Sun only generates J AR files, leaving
J AR to CAP conversion open, which caused divergences in CAP file formats from one
manufacturer to another.
Compiled
J ava Code
Source
J ava
Code
.J ava . Class
J ava Card
Virtual Machine
(J CVM)
Byte
Code
. SAP . CAP
. J AR .IJ C
Compiler
Developer Suite V3.2
J ava Card plug-in
Loader Converter
Eclipse and Developer Suite V3.2
6 Introduction
The idea was thus to define a loadable file format containing only the components
described as mandatory by the J ava Card specification (for example, the optional
Descriptor component has been removed in the IJ C format).
In other words, the IJ C format is the smallest common denominator of the different
CAP file components supported by the cards of the SIM Alliance members.
Projects
The term project in the Developer Suite V3.2 environment refers to a package which
may, or may not, include one or more applets, together with all necessary system
classes, with or without libraries. When no applets are included in the project it is a
library. The project file groups together all the files and environment variables
required for building, debugging and loading applets and libraries.
AIDs
For security reasons, client applications must be able to uniquely identify any installed
applet. Every package, applet, and instance of an applet loaded on a card must
therefore be assigned a unique identifier, known as an application identifier (AID). An
AID is a string of between 5 and 16 hexadecimal bytes.
Figure 3 - The AID Format
The first five bytes of an AID (the RID) indicate the application provider, that is, the
company supplying the package or applet. To obtain an RID, your company must
register with the international standards organization (ISO). This procedure is
described in ISO7816-5 Numbering system and registration procedure for application
identifiers.
The remaining bytes (up to 11) of an AID contain the proprietary identifier extension
(PIX). The PIX is chosen by the application provider to uniquely identify a package or
applet. Your company is then responsible for assigning PIXs to individual applications.
As mentioned previously, three types of AID are used in a project:
The package AID. An AID assigned to a package.
The applet AID. An AID assigned to an applet.
The applet instance AID. An AID assigned to an instance of an applet.
An applet AID cannot have the same value as the AID of any other package or any
other applet stored on the same card.
The Developer Suite V3.2 Tools
Developer Suite V3.2 builds a J ava Card Integrated Developement Environment(IDE)
on Eclipse, an external tool from Eclipse.org. As a prerequisite of installing Developer
Suite V3.2, Eclipse is included in Developer Suite V3.2s installation package. It will be
automatically extracted and installed when you execute the installation program of
Developer Suite V3.2.
Eclipse is an open universal framework, with whose plug-ins, theoretically any
extended functions can be achieved and integrated perfectly with the platform. As a
result, Eclipse is popularly used by software tool vendors as a platform for building
developer tools. Developer Suite V3.2 is a set of seamlesssly embedded Eclipse plug-
ins (see also Eclipse on page 20). It adds a user-friendly Developer Suite
Application Identifier (AID)
RID (5 bytes) PIX (up to 11 bytes)
Introduction 7
perspective(see Developer Suite Perspective on page 31), a Developer Suite menu,
abundant wizards as well as tools used at pre-loading, loading and post-loading
stages.
Through Eclipse platform, Developer Suite V3.2 provides the appropriate tools for
each stage of development and testing, as follows:
Wizards: These gather the information necessary to build and configure a skeleton
J ava Card project, such as J ava package names and default applet AID values. All
Wizards can be launched through quick access from Application Wizard view
panel (see J ava Card Project Management View on page 32).
Pre-loading tools: The Developer Suite V3.2 J ava Card plug-in for Eclipse
prepares the applet for loading onto the card by converting Class files to byte code.
Loading tools and post-loading tools:
The J CardManager loads packages into a card or the card simulator, and
exchanges APDU commands with a loaded applet.
The Application Manager loads and installs applets into a card.
The Script Editor creates and edits XML script files to provide batch execution
of commands.
Simulation tools: A card simulator simulates all aspects of particular card types
behavior, and is extremely useful for testing and debugging the functionality of an
applet. The Mobile Simulator GSM, Mobile Simulator 3G and Mobile Simulator
CDMA card simulators operate in exactly the same way as the equivalent real
mobile telephones. The Simulation Chain 2G and Simulation Chain 3G tools
simulate a secure connection between a server and a mobile station.
Miscellaneous utilities: Various utility tools are also included:
The Cap File utility lets you visualize the contents of a loadable CAP file.
The Crypto Tool provides a method of enciphering and deciphering data using
the DES, 3DES, AES and RSA cryptographic algorit3.2hms and provides a
method of hashing using the SHA1 and MD5 hash algorithms.
The File System Editor allows you to view the file structure in a card or card
simulator and the properties and access conditions for any given file.
The Key File Editor allows you to create custom key files.
The OTA interpreter allows you to display an interpreted view of a sequence
of OTA data bytes.
The WTKOCF Bridge assures communication between the J 2ME Mobile
Simulator and the SmartCardFramework. It converts the TLP224 WTK2.3
mobile simulator protocol into the TPDU format used by OCF.
The following table lists the Developer Suite V3.2 tools and the corresponding
development stages and target types required.
Table 1 - Development Stages and Steps
Development Tools Development Stages
Quick-start tools:
Wizards Code development and compilation.
Pre-loading tools:
Developer Suite V3.2 J ava
Card Plug-in for Eclipse
Converting Class files to loadable files (CAP or SAP).
8 Introduction
The Developer Suite V3.2 tools can be launched from within the plug-ins provided for
Eclipse, or from within the J CardManager. Some can also be launched from the
command line using supplied batch files. Table 2 - Accessing Developer Suite V3.2
Tools summarizes the launch options.
Loading tools and Post-loading tools:
Application Manager Loads and installs applets.
J CardManager CAP file loading, APDU command exchange, tracing,
scanning.
Script Editor Creation and edition of configuration files and scripts.
Simulation and test tools:
Simulation Chain 2G Simulates a client application, GSM network components
and a mobile phone.
Simulation Chain 3G Simulates a client application, 3G network components
and a mobile phone.
Mobile Simulator GSM Simulates a client GSM handset.
Mobile Simulator 3G Simulates a client 3G handset
Mobile Simulator CDMA Simulators a client CDMA handset
J CardManager APDU command exchange, tracing, scanning.
Card simulator Testing and debugging applets
Miscellaneous utilities:
Cap File utility Viewing the contents of a CAP file
Key File Editor Creating custom key files
CryptoTool Enciphering and deciphering data
OTA Interpreter Displays an interpreted view of a sequence of 23.048-
formatted data bytes
File System Editor Viewing the file structure and individual properties and
access conditions for a file.
WTKOCF bridge A bridge between Suns Wireless Toolkit (WTK) phone
simulator and Developer Suite V3.2's reader/card
connection. Enables communications with a real reader/
card connection (since the WTKs TLP224 protocol is
integrated directly in the card simulators).
Table 2 - Accessing Developer Suite V3.2 Tools
Tool Accessible from:
Eclipse
Plug-in
JCardManager Command Line
Wizards Yes No No
Mobile Simulators Yes No Yes
Cap File utility Yes Yes No
CryptoTool Yes Yes No
Table 1 - Development Stages and Steps (continued)
Development Tools Development Stages
Introduction 9
Developer Suite V3.2 Development Scenarios
The Developer Suite V3.2 tools allow you a wide range of flexibility when developing
applets. There is usually more than one way of accomplishing a task.
Development Phase
For the rapid development of a prototype applet with Developer Suite V3.2, do the
following:
Run the Wizards. Use the supplied wizards to generate skeleton code and a
project definition.
Debug the Project. Set breakpoints and then use Developer Suite V3.2 tools to
launch the simulator, load the files into the card simulator and launch the client
application.
Developer Suite V3.2 automatically generates a GXSC script file containing all
necessary load and install parameters. If necessary, you can edit this file using the
Script Editor.
Script Editor Yes Yes No
Key File Editor Yes Yes No
File System Editor No Yes No
OTA Interpreter Yes Yes No
WTKOCF bridge Yes Yes No
Table 2 - Accessing Developer Suite V3.2 Tools (continued)
Tool Accessible from:
Eclipse
Plug-in
JCardManager Command Line
Note: When you debug a project, Developer Suite V3.2 automatically builds the
project for you first, that is, compiles the J ava source code to Class files and converts
the Class files to CAP, J AR, or other file formats as necessary.
10 Introduction
The following diagram illustrates the development phase.
Figure 4 - The Development Phase
Tools Used During the Test Phase
Once you have built and debugged your J ava Card application, it can be further tested
in a real card.
The test scenario would be:
Load the applet into the card with J CardManager (possibly using GXSC scripts) or
the Application Manager (refer to Using the Application Manager on page 161).
Alternatively, you can use the deployment script generated with the project.
Test the applet using the client applications provided with Developer Suite V3.2:
The Mobile Simulator GSM, Mobile Simulator 3G, or Mobile Simulator CDMA
Simulation Chain 2G or Simulation Chain 3G
J CardManager (for J ava Card applets)
OCF Client application (for J ava Card applets)
J CRMI Client application (for J CRMI applets)
SATSA Midlet
Java Card Plug-in
Automation
Eclipse IDE
Wizards
Project
Java Class File
Java Card
Project
.GBP, GDP &
.GXSC
.JAR
.SAP
.CAP
.IJC
Debugger
Card Simulator
Script Editor
JCard Manager
Mobile Simulators
(GSM, 3G, CDMA)
Simulation Chain 2G,
Simulation Chain 3G
Installed applet
triggers breakponts
Communication
Communication
File
Conversion
Loader
Edition of .GXSC files
Communication
P
r
e
f
a
c
e
This document is designed to help you learn about Gemalto Developer Suite V3.2 by
using it. It guides you step by step from the creation of a new J ava Card applet, through
to its installation and testing.
Whats New in This Release
The main evolution of the Developer Suite 3.2 & Simulation Suite 2.2 are to:
Enhance the support of Multimedia Cards
New Standardized SCWS API
Support for MMReady & FullMM Cards
Support the Contact-less Cards
Add Live Update mechanism
Other improvements
Who Should Read this Book
You only need a minimum knowledge about smart cards, but you are strongly
recommended to read the standards and documents listed in References on
page 195.
Conventions Used in this Document
bold Command and window names are shown in bold. For example:
... the JCardManager window...
> Menu selection sequences are shown using the >symbol to link
the selections. For example:
... select Start > All Programs > Gemalto > Wireless
Solutions...
italics Book titles are shown in italics.
notation By default, a numeric value is expressed in decimal
notation.
Whenever a value is expressed in binary, it is followed by
the letter b. For example the decimal value 13 expressed
in binary becomes 1101b.
A hexadecimal number is followed by the letter h, or
preceded by 0x. For example, the decimal value 13
expressed in hexadecimal becomes 0Dh or 0x0D.
12 Preface
installdir This variable is used throughout this book to indicate the
directory in which Developer Suite V3.2 is installed. For
example, when the following directory is shown in the book:
installdir\ bi n
you may need to substitute the following directory:
c: \ Pr ogr amFi l es\ Gemal t o\ Devel oper Sui t e\ bi n
carddir This variable is used throughout this book to indicate the
directory which stores the files common to a particular type of
card. For example, when the following directory is shown in the
book:
.. . \ exampl es\carddir
you may need to substitute the following directory:
. . . \ exampl es\ USI M Car d R6
3
Installing Developer Suite
V3.2
This chapter describes how to install Developer Suite V3.2.
System Requirements
Hardware Requirements
The following hardware is required to install and use Developer Suite V3.2:
A Windows-compatible PC with:
500 MHz processor.
512 MB RAM recommended minimum (768 MB is recommended).
1GB of available disk space, plus another 1GB during installation.
Support for Super VGA resolutions (1024 x 768).
A CD-ROM drive (only mandatory when you install from a CD-ROM).
A PC/SC compliant smart card reader with associated connection cables and
drivers, such as the GemPC Twin smart card reader (P/N HWP108765 C); this is
not required for the Evaluation Version.
Optionally, a SIM Toolkit, USIM Toolkit, or CCAT (CDMA Card Application Toolkit)
J ava Card (for example, GemXplore Xpresso v3 or GemXplore Generations). In
order to be able to download applets onto a card in Developer Suite V3.2, it must
be either Global Platform or 3GPP 23.048 compliant.
Software Requirements
1 Developer Suite V3.2 runs under the following operating systems:
Microsoft
Windows 2000 (with Service Pack 4)

Microsoft Windows
XP (with Service Pack 2)

Microsoft
Windows Vista (with Service Pack 1)

2 Eclipse
Version 3.3 or higher

The Developer Suite V3.2 environment is installed as a set of plug-ins integrated in
Eclipse IDE. It installs a Developer Suite menu on Eclipses menu bar, adds the
Java Card Project Management view, and configures various J ava Card project-
specific property settings. The Developer Suite menu allows you to directly launch
the various tools. The Java Card Project Management view gives you quick
14 Installing Developer Suite V3.2
access to J ava Card project and applet creation wizards. Certain tools display their
output in Eclipses messages window.
3 The J ava2 Software Development Kit (SDK) 1.5 or higher. This is also installed
as part of the Developer Suite V3.2 installation procedure.
4 J ava Cryptography Extension, necessary in order to use Simulation Chain 2G and
Simulation Chain 3G to their full capabilities (for example, allows the use of 24-byte
3DES keys). To fully benefit from all the features of Simulation Chain 2G and
Simulation Chain 3G, you should use the unlimited strength version. These can
be downloaded from http://java.sun.com/products/J CE.
5 Adobe
Acrobat
Reader Version 4.0 or later. This is required to read the online

documentation provided on the installation CD-ROM.
6 Microsoft Internet Explorer Version 5.01 and Microsoft XML Parser Version 4.0, or
Microsoft Internet Explorer Version 6.0 or later.
7 If you are using the card simulator, you must make sure the TCP/IP networking
protocol is installed on your PC.
Installation Overview
You can either install the Developer Suite V3.2 environment from a CD-ROM or a . zi p
file downloaded from the product website. The installation program installs any
additional components required. If you have a card reader installed, it is configured for
use. The card simulator is automatically installed on your workstation during
installation.
Before Installing Developer Suite V3.2
To prepare for Developer Suite V3.2 Installation, perform the following steps:
1 Configure the display settings on your computer. The desktop resolution must be at
least 1,024 by 768 pixels, with 65,536 colors (16bit).
2 Log in with an account that has Administrator rights on your computer, otherwise
you will not be able to install Developer Suite V3.2. Contact your System
Administrator if do not have these rights.
3 Close all other applications running on your computer.
Installing Developer Suite V3.2
To install Developer Suite V3.2:
1 Insert the Developer Suite V3.2 CD-ROM into the CD-ROM drive on your
computer; or unzip the installation archive (the . zi p file) to a temp directory and
double-click the executable program (like GXDev_I nst al l . exe).
The installation program starts automatically.
For CD-ROM installation, if for any reason it does not start automatically, run the
drive:\Developer_Suite_x.y.z.exe program on the installation CD-ROM, where
drive is the drive letter of the CD-ROM drive.
Note: Eclipse is installed as part of the Developer Suite V3.2 installation procedure.
Installing Developer Suite V3.2 15
2 Choose the Install Developer Suite V3.2 Installation option. This program guides
you through the installation process.
After Installing Developer Suite V3.2
Apply and Import A License for Developer Suite V3.2
Developer Suite V3.2 uses a new version of License Key Manager, to puts all
Developer Suite V3.2 components under protection against compromise.
Without a license, each time you launch the Developer Suite V3.2, a dialogue will
prompt you, warning that your copy of this product will expire in a certain number of
days, for example like Figure 5 - Developer Suite V3.2 - Not Registered shows.
Figure 5 - Developer Suite V3.2 - Not Registered
On the above window:
Click Continual Trial to skip registration and use an evaluation version of
Developer Suite V3.2. You can use a full-featured version of Developer Suite V3.2
within the remaining days.
Click Apply License to activate the Developer Suite V3.2 product. This starts the
license application wizard. Then following steps in To apply a License to
Developer Suite V3.2: on page 15 to complete registration.
To apply a License to Developer Suite V3.2:
1 After clicking Apply License button, the License Key Manager window appear
like blow:
Figure 6 - License Key Manager
Note: The default software installation directory is:
c: \ Pr ogr amFi l es\ Gemal t o\ Devel oper Sui t e
You can specify a different drive or directory. To avoid confusion, the installation
directory is referred to as installdir throughout this document.
2 If a license is already achieve, click Import License to browse and locate it on your
local disk. Follow the wizard to complete.
3 If you have no license on hand, you need to apply one first. Click Export Profile,
the following window appear:
Figure 7 - Profile Generation
4 Fill in the blank form in window as the above figure presents. All fields with a * are
required. For the Gemalto contact option, choose either the Gemalto Web Store
or Gemalto Email Address as your email receiptor.
5 Click Save if you want to further revise your information before sending; click Save
& Send to take modification in effect and feedback them to Gemalto.
6 A message will the be sent to your registered Email Box. A license (XML file) will be
attached.
7 Go back to the License Key Manager window. Click Import License and follow
the wizard to complete.
Importing WTK Devices Into Eclipse
If you want to develop SATSA MIDlets, the Sun J ava
TM
Wireless Toolkit V2.5 need to
be installed and configured.
For sake of convenience, WTK 2.5 is contained in Developer Suite V3.2 installation
package and will be automatically installed. We strongly suggest you do not change the
default installation path c: \ Devel oper Sui t eWt k.
Before using this tool, you need to follow the steps below to configure J2ME
environment by specifying a valid location for WTK Devices:
1 Start Eclipse as described in Eclipse on page 20.
2 On Eclipse menu bar, click Window > Preferences. This prompts the
Preference window.
Installing Developer Suite V3.2 17
3 On the left pane of Preference window, click J2ME node to unfold it and select
Device Management, shown as follows:
Figure 8 - Importing Wireless WTK - Preference Window
4 On the Device Management page shown on the right, click Import button. On the
Import Devices window, click Browse button next to the Specify search
directory: textbox, as follows:
Figure 9 - Importing Wireless WTK - Import Devices
5 On the Browse For Folder window, browse to WTK 2.5s installation directory(c: \
Devel oper Sui t eWt k by default).
Figure 10 - Importing Wireless WTK - Browse For Folder Window
6 Click OK to close Browse For Folder window and return to Import Devices
window. Click Refresh button. Four lines appear in the Devices list and are
selected, shown as below:
Figure 11 - Importing Wireless WTK - Devices Refreshed
7 Click Finish button to close Import Devices and return to Preference window.
8 Click OK to close Preference window.
Now you have finished configuration of J 2ME for Eclipse. This is a global setting which
means you dont have to configure it each time you use the tool.
4
Components
License Key Manager
The License Key Manager applies a license protection mechanism to the Developer
Suite V3.2 at component level. Under the License Key Management System, the
products components are divided into two categories:
License-free components
Components that are open to use in both an evaluation version and a full
version of the Developer Suite V3.2 product.
License-protected components
Components that are only available in the full version of the Developer Suite
V3.2 product.
It is important to notice that, while an evaluation version demonstrates basic features of
the Developer Suite V3.2, the full version is indispensable for a complete J ava Card
development cycle. Main differences between the two versions are:
Smart Card Access. The Evaluation Version cannot access a real card and does
not generate byte code (.cap, .jar files) for cards. To test the behavior of your applet
in a card, you must use a card simulator.
The Application Manager is only available in the Full Version.
Many features in Simulation Chain 2G and Simulation Chain 3G are blocked.
The Mobile Simulator CDMA is only available in the Full Version.
For legal reasons, the cryptographic capabilities are limited in the Evaluation
Version:
For RSA, to 512bit key lengths (instead of 2,048 bits for the Full Version)
For DES and 3DES to 56 bits (instead of 168 bits for the Full Version)
For AES to 56 bits (instead of 256 bits for the Full Version)
Only the SCWS card and SIM R5 card profiles (available in wizards, mobile
simulators, commands, and so on) are available in the evaluation version.
Note: Longer values are accepted by the Evaluation Version, but in practice the
bits that exceed the allowed length are set to zero.
20 Developer Suite V3.2 Components
Eclipse
The Developer Suite V3.2 is a J ava Card plugin for Eclipse. To use the Developer
Suite V3.2, Eclipse needs to be installed on your PC. For more information about which
features are accessible from Eclipse, see Table 2 - Accessing Developer Suite V3.2
Tools on page 8.
Because Developer Suite V3.2 automatically launches Eclipse SDK, no separate
shortcuts are provided for Eclipse in Start menu. The IDE starts with an embedded
Developer Suite V3.2 plug-in when you click:
Start >All Programs >Gemalto >Wireless Solutions > Developer Suite.
The Developer Suite V3.2 adds a Developer Suite menu in Eclipse menu bar, from
which you can launch all the Developer Suite V3.2 tools. The following figure show the
Developer Suite menu and its menu items.
Figure 12 - The Developer Suite V3.2 Plug-ins for Eclipse
Static Content Explorer
The static Content Explorer provides a visual viewer to manage static content in SCWS
card. It is easy to use this tool to add new file (even batch file is allowed), delete folder/
files and explore contents.
Developer Suite V3.2 Components 21
Menu to Access
From the Eclipse menu bar, click Developer Suite > Static Content Manager, as the
following figure shows:
Figure 13 - Static Content Menu
Static Content Explorer View
This displays the Static Content Explorer view in Eclipse workbench.
Figure 14 - Static Content Manager View
The static contents are automatically started when the Static Content Explorer is
opened. The SCWS card memory status are present on the status bar (at the button of
Eclipse workbench), as below:
Figure 15 - Memory status bar
Static Content
Tree Structure
Toolbar
Right-click
Contextual
Menu
Static Content Explorer Toolbar
The toolbar is at the top of the Static Content Explorer.
The following contents introduce each button in the toolbar.
Add file(s) as static contents to SCWS card
The Put button is for recursively adding files into the SCWS card.
1 In the static content tree structure, select a folder (root included) to add the
imported files.
2 Click the Put button to display the file explorer, where you can choose a single file
or a batch of files from your PC local disk.
3 Click Open to add the selected file(s) to the SCWS card.
4 After adding file(s) finished, the contents structure and memory status are
refreshed automatically.
Add a folder (files included) as static contents to SCWS card
The Put All button can recursively add a whole directory into an SCWS card while
keep the same file structure with the local disk.
1 In the static content tree structure, select a folder (root included) to add the
imported files.
1 Click the Put All button to display the file explorer.
2 On the Browse for Folder window displayed, browse the file system to specify a
directory on your PC local disk.
3 After selecting a directory to add, click Ok to add files.
4 The contents structure and memory status are refreshed automatically.
Create an empty folder in static contents tree structure
The Create Folder button allows to create an empty folder under a specific node of
the static contents tree structure. To add a new folder:
Tip: Press Ctrl and click the to select multiple files in the explorer window.
1 In the oncard static contents tree structure, click to select a parent folder for the
folder to be created, e.g. SCWS as highlighted in the figure below:
Figure 16 - Create New Folder - Select A Parent Folder
2 Click the Create Folder button. This display a New Folder page as below:
Figure 17 - Create New Folder - Enter Path
3 On the window above, the select folders path is given. The new folder will be
added into that directory.
In the text field, enter a name for new folder.
You can also use a slash (/) to including a sub folder, e.g. On card port/images
(double quotation marks excluded).
4 Click Ok to add folder(s). The contents structure and memory status are refreshed
automatically.
5 If you cant see update in the tree structure, click Refresh button or press F5 key to
refresh the display.
Note: When you name the new folder, notice that space is allowed which a
backslash (\) is forbidden.
6 The new created folder(s) appears in the static content tree structure, as the figure
below shows:
Figure 18 - Create New Folder - Content Structure Updated
Delete a file or folder
The Delete allows you to remove unwanted files or folders from the SCWS card.
1 In the static content tree structure, select a single file or folder to delete. Like the
case for adding files, you can also choose a batch of files to delete.
2 Click Delete button.
3 You will be prompted for confirmation on continuing the operation.
4 Click Yes to confirm or click Cancel to quit.
5 The contents structure and memory status are refreshed automatically.
Reload the static file structure in SCWS card
Click the Refresh button refresh your static content tree structure. This will:
Refresh the root directory if no file or folder is selected.
Refresh the corresponding directory selected.
Launch the system web browser in Eclipse Editor view panel
The View in web browser button allows to open the system web browser in
Eclipse Editor view panel to display a selected file or folder. This button is disabled if no
file or folder is selected in the static content structure.
1 In the static content tree structure, select a single file or folder to display.
Warning: To delete a folder will recursively delete all files and sub-folders under
its directory.
2 Click the View in web browser button to launch the web browser. The selected file
or folder is opened in the web browser. As the following figure shows:
Figure 19 - Launch Browser
3 As in Figure 19, the selected image file back. j pg is displayed in the web
browser on the right.
Download a file or folder from the SCWS card to local disk
The Get button allows to export files or folders selected in SCWS card into local
system. As the case in adding file, you can select one single file or a batch of files at a
time by press Ctrl key and click on files.
This button is disabled if no file or folder is selected in the static content tree structure.
If a file with the same name already exists on the local disk, a window prompts to you,
asking whether to overwrite and existing copy or not.
Set the properties of Static Content Explorer
The Preference button enables you to modify Static Content Explorer settings. To
change preference configuration:
1 Click Preference button. This displays the Preference page.
Figure 20 - Static Content Explorer Preference
2 On the HTTP Proxy screen, define the following parameters or use the default
values:
Compress text file as gzip encoding: if gziped the file when put text file, there
is a list if MIME type that the gzip option may compress when put files. Multiple
types are separated by space. For example, text/html text/plain.
Http server Address: The ip address of the http server, default value is
127.0.0.1.
Http server Port: This is a http service port, default value is 3516.
Maximum receive length: Maximum value for a receive data or a data
available. Shall never exceed 237 (APDU limit), default value is 237.
Chained receive: if true try to optimize the flow by using remaining data length
in the receive buffer, else perform a data available between each receive. The
default value is true.
timeout: use for receive and emit data. On the user point of view, it looks like
Http request time out. Default value is 60000 (1 min).
BIP Channel size: the size of BIP channel pool, default value is 5. It can open
multiple BIP channels at the same time.
Force the Memory Access by using specific perso commands, and temporarily
disable the SCWS security (for the current ATR session) if the current card is in
secure mode.
After modification, you need to re-start the Static Contents Explorer to take effect.
JCardManager
The J CardManager is a powerful tool used to load CAP files, exchange APDUs, and
run traces. More generally, it is used to send any Global Platform command to a card
or simulator. For more details about the J CardManager, refer to Appendix B - The
J CardManager.
Application Manager 2G/3G
The Application Manager is a tool that can be used to download packages onto real
cards and install and delete applets or applet instances. It has three download modes:
I/O mode: GlobalPlatformcompatible cards
OTA mode: 3GPP TS 23048 compatible cards
BIP mode: 3GPP TS 23048 compatible cards
The Application Manager is started from the Developer Suite menu in Eclipse IDE and
is fully explained in Chapter 14 - Using the Application Manager.
Simulators
There are four types of simulators available in Developer Suite V3.2:
Card simulators (SIM, USIM, R-UIM and SCWS cards).
Mobile simulators (Mobile Simulator GSM, Mobile Simulator 3G and Mobile
Simulator CDMA).
Simulation Chain 2G and Simulation Chain 3G.
The SIM Card Simulators
SIM card simulators are software that simulate the behavior of a smart card. Developer
Suite V3.2 includes a number of card simulators. They perform the same basic
functions, but are compliant with different versions of J ava Card, Telecom and
GlobalPlatform standards. The following table illustrates the differences:
To start the SIM Card Simulator:
From the Start menu, choose USim Card R6 Simulator, USim Card R5 Simulator,
Sim Card R5 Simulator, Sim Card R99 Simulator, R-UIM Simulator or SCWS Card
Simulator as appropriate. If you cannot find the simulator directly from the Start menu,
try Start >All Programs >Gemalto >Wireless Solutions > Card Simulators.
Alternatively, when a J ava Card applet project is open in Eclipse, running the project
automatically launches the simulator and loads the applet into the simulator. This is
typically the method used if you want to debug an applet. This action displays the
following in the Messages area of the Eclipse window:
Figure 21 - Sim Card Simulator Window
The Mobile Simulators
The mobile simulators are client applications used to debug Toolkit Applets. The
simulators are all started in the same way. Each has a distinctive graphical user
interface (GUI). The mobile simulator starts automatically when you run a project,
provided you have selected it in the Choose the client application to run drop-down
menu in Run or Debug window (see Figure 108 on page 94). Otherwise, you can
start it manually from the Developer Suite menu by choosing the option Mobile
Simulator.
Table 3 - Simulator Versions Standards Compatibility
Simulator Java Card version Telecom standard GP standard
NFC Card with
Proprietary of SCWS
2.2.1 3GPP release 6 2.1.1
USim Card Simulator R5 2.2.1 3GPP release 5 2.0.1
Sim Card Simulator R5 2.1.1 3GPP release 5 2.0.1
Sim Card Simulator R99 2.1.1 3GPP (1999 release) 2.0.1
R-UIM Card Simulator 2.2.1 3GPP2 C.S0035-A 2.1.1
NFC Card with
Standerdized SCWS
2.2.1 3GPP release 6 2.2.1

The mobile simulators first display the Mobile Simulator Parameters window, as shown
in the following figure:
Figure 22 - The Mobile Simulator Parameters Window
Proceed as follows:
1 Select Simulator from the Available Readers group box.
2 Click Add to add it to the Selected readers group box.
3 Click OK to continue.
Simulation Chain 2G and Simulation Chain 3G
This simulator is used to debug SIM Toolkit, USIM Toolkit, R-UIM Toolkit applets and
Servlet that trigger OTA events. If you have it installed on your machine, you can start it
in Eclipse from the Developer Suite menu by choosing the option Simulation Chain
2G or Simulation Chain 3G.
Tools
Cap File Utility
This tool enables you to view and optionally save a .cap file in text format. Access this
tool in Eclipse by choosing Developer Suite >Cap File utility.
Crypto Tool
Developer Suite V3.2 contains a tool you can use to perform DES and Triple DES
computations. Access this tool in Eclipse by choosing Developer Suite >Crypto Tool.
File System Editor
This tool enables you to view the file structure in a card or a card simulator and the
properties and access conditions for any file. In addition it can be used to perform
certain commands on files.
For information about this tool, refer to Chapter 16 - The File System Editor.
Key File Editor
This utility enables you to create custom key files. With it you can add, remove, import
and key sets and mother keys in a key profile. The Key File Editor is described in detail
in Chapter 17 - The Key File Editor.
OTA Interpreter
This tool is installed automatically with Simulation Chain . For more information refer to
the Getting Started document that is located on your Developer Suite V3.2 CD in
Devel oper Sui t e\ Si mul at i onChai n2G\ Get t i ngSt ar t ed. pdf .
Script Editor
The Script Editor is a tool that enables you to create and edit configuration files and
scripts. A script is a sequence of command APDUs. For information about the Script
Editor, refer to Chapter 15 - The Script Editor.
WTKOCF Bridge
This tool aides communication between a J 2ME emulator and a smart card. The J 2ME
emulator communicates with the card simulator using the TLP 224 protocol. A real
smart card needs the TPDU protocol to interpret APDU commands. The bridge
reformats commands received in TLP 224 protocol into TPDU format as shown in the
following figure:
Figure 23 - The WTKOCF Bridge
J 2ME Emulator
Card Simulator
T
L
P

2
2
4

P
r
o
t
o
c
o
l
WTK-OCF
Bridge
Smart Card
TLP 224 Protocol
O
C
F

P
r
o
t
o
c
o
l
Handles TLP 224 and OCF Handles OCF only
5
Getting Started with
Developer Suite V3.2 Working Environment
As we mentioned previously in Eclipse on page 20, the Developer Suite V3.2adds a
J ava Card plug-in to Eclipse and by embedding the Developer Suite menu in Eclipse
menu bar, make its major tools easy to access.
In this chapter, we further explore Developer Suite V3.2 proprietary GUIs and
features integrated in Eclipse IDE. Here we mainly focus on features closely related to
the Developer Suite working mode, apart from the Developer Suite menu and its
members we introduced before in Chapter 4 - Developer Suite V3.2 Components.
Developer Suite Perspective
The term Perspective using by Eclipse refers to an initial set and layout of views in the
Workbench (desktop development environment) window. Each perspective provides a
set of functionality aimed at accomplishing a specific type of task or works with specific
types of resources. For example, the J ava perspective combines views that you would
commonly use while editing J ava source files, while the Debug perspective contains
the views that you would use while debugging J ava programs. For more information on
Eclipse Perspectives, please refer to Eclipse Help Contents in Help menu. Developer
Suite V3.2 adds a perspective called Developer Suite to Eclipse IDE. By default this
perspective is in use at initial launch of Developer Suite V3.2. You can also switch from
other perspectives(e.g. Java or Java Browsing) to Developer Suite, by clicking
32 Getting Started with Developer Suite V3.2
on the upper-right corner of current workbench and select Developer Suite from the
popup menu, as highlighted in the following figure (the pressed-down button
indicates that Developer Suite perspective is currently in use):
Figure 24 - Switch to Developer Suite Perspective
Java Card Project Management View
In Eclipse, Views support editors and provide alternative presentations or navigations
of the information in the Workbench. For example:
The Bookmarks view displays all bookmarks in the Workbench along with the
names of the files with which the bookmarks are associated.
The Navigator view displays the projects and other resources.
For more information on Eclipses Views, please search Help Content under Help
menu on Eclipse menu bar.
Developer Suite V3.2 provides wizards for creating the most common types of J ava
Card development projects. These wizards can be quickly accessed by double-clicking
their icons on Java Card Project Management view panel (only appears in Developer
Suite perspective). Figure 25 shows where Java Card Project Management view
panel is docked on the workbench window and a close-up view of the panel:
Figure 25 - Java Card Project Management View
Getting Started with Developer Suite V3.2 33
Project Wizards And Applications Wizards
Two categories of wizards can be found on the Java Card Project Management view.
They are Project Wizards and Application Wizards.
Project Wizards:
The Project Wizards combo box contains three projects types:
J ava Card Project: including several sub types of J ava Card Projects, each
specifying a card profile (R-UIM, SIM R99, USIM R5, etc.).
J CRMI / APDU OCF Client Project: used to create offcard client application for
testing compatible oncard applets.
Applications Wizards - Twin displays:
This area displays applications (various types of applets and servlets), library, and
methods (SATSA Midlet access and HTTP Midlet access) available to the selected
project type. The Applications Wizards combo box changes display when user
switches selection between a J ava Card project and an SCWS project.
When a J ava Card project is currently selected, the Applications Wizards area
appears like below:
Figure 26 - Applications Wizards
When a SCWS project is currently selected, the Applications Wizards changes its
outlook.
Figure 27 - Application Wizard for Servlet
The wizards generate skeleton J ava code that is ready to compile, and gather the
information necessary to build and configure a skeleton J ava Card project, such as
J ava package names and default applet AID values.
Chapter 7 - Worked Example with USIM Toolkit Applet is a quick tutorial on how to
use the wizards to create a J ava Card project in Eclipse.
Java Card Project Import and Export
Import and Export Menu Access
Developer Suite V3.2 provides ability to import external projects into Eclipse
workbench or export J ava Card projects from Eclipse.
To start an Import/Export wizard, you can do either of the following.
As the following figure shows, click File Eclipse menu and select Import/Export.
Figure 28 - File Menu - Import & Export
On the Package explorer, select a project and right-click. On the contextual menu
displayed (see Figure 29), select Import/Export.
Figure 29 - Project Contextual Menu - Import & Export
Importing Developer Suite Projects
To import Developer Suite projects, you need to following these steps:
1 On the Import page, click to unfold the Developer Suite menu.
Figure 30 - Import Main Page
2 Under Developer Suite node, select a project type. You can choose to:
Import New Developer Suite projects.
This wizard is used to import external Developer Suite projects into Eclipse
workspace. It is not applicable when projects to be imported already exist under
workspace.
Import J Builder J ava Card projects.
This wizard is used to import J ava Card projects exported from a J Builder
version of Developer Suite (earlier than Developer Suite V3.0).
3 Click Next to proceed. This displays steps 1 of the Import Projects Wizard, on
which browse to locate an archive file (for New and Existing Developer Suite
Projects) or specify a directory (for J Builder java card project).
Note: To use Update Existing Developer Suite Projects, make sure the archive file
you destine to import contains at least one project named the same as an existing
project under Eclipse workspace.
4 Projects in the specified archived file or under the specified directory will be
automatically detected and displayed in the Projects field once they are found. All
the detected projects are selected by default as shown in the figure below:
Figure 31 - Import Projects Found
5 Select the projects you want to include. Click Finish to complete import. Eclipse
starts building the projects immediately after they are imported if Build
Automatically is selected under the Project menu.
Exporting Developer Suite Projects
To import Developer Suite projects, you need to following these steps:
1 On the Export page, click to unfold the Developer Suite folder.
2 Under Developer Suite folder, select the only option Developer Suite Archive.
Current release of the Developer Suite only allows you to export J ava Card projects
into a ZIP file.
3 Click Next to display step 1 of Developer Suite Export Wizard.
Figure 32 - Developer Suite Export Wizard - Step 1
4 On the above window, user can choose export all relative files or specify part of
them. See description below.
5 Specify an export directory by click Browse button. Click Finish to complete
export.
Table 4 - Export Options and Relative Files
File Default export +Sources +External class
paths
+External scripts
DS configurations
(.gdp, .gbp,
.launch)
X
Simulation Chain
configurations
X
J ava source file X
Class file
Local libraries
(.jar, .zip, .class)
X
External libraries
(.jar, .zip, .class)
X
Local scripts
(.gxsc, .atf, )
X
External scripts
(.gxsc, .atf)
X
Note: For easy synchronization with Simulation Suite, Developer Suite export all the
Simulation Suite configuration files under pr oj ect / . conf directory.
Project Properties Editor
How To Access
Immediately after a completion of a J ava Card/SCWS project wizard, the Project
Properties Editor automatically launches with the new projects definition.
Below is a SCWS project definition opened in the Project Properties Editor.
Figure 33 - Project Properties Editor
By default, the Project Properties Editor is used as the default editor for . gbp and
. gdp files. You can open a J ava Card/SCWS projects parameters in Project
Properties Editor at any time by double-clicking the projects . gbp/. gdp file. You can
also right-click a . gbp/. gdp file and select Open With > Project Properties Editor,
as below:
Figure 34 - Open With Project Properties Editor
The Project Properties Editor has multiple tab-pages, as we can see on its Overview
tab-page as follows:
Figure 35 - Overview of Project Properties Editor
Overview
The Overview page is displayed when the Overview tab is selected. On this page,
shortcuts are available to modify general J ava Card/SCWS project definition, including.
Project Location: Click this link to retrieve the first page of a J ava Card project
wizard.
J ava Card Project Settings: Click this link to retrieve the second page of a J ava
Card project wizard.
Personalization script or Set project environment: Click this link to open the current
projects run dialogue.
DAP setting: Click this link to retrieve the last page of a J ava Card project, or the
second last page of an SCWS project wizard.
As most of the shortcuts reuse J ava Card/SCWS project wizard, you can follow the
instruction next to each link to make changes to projects parameters.
Any modification made will overwrite the corresponding parameter you specified before
within project creation wizard.
To make it clearer, the table below shows which parts of the project are accordingly
changed with the above parameters:
Table 5 - Change Dependencies
Project Nature Wizards .gdp File .gbp File
Name Y Y Y
Version
ClassDir Y Y
ConversionDir Y Y
Applications
The Application page is displayed when the Application tab is selected. With this
page, user can easily manage a J ava Card/SCWS projects applets/servlets:
Figure 36 - Project Properties Editor - Application Tab
To add an applet/servlet: Click Add button to bring out the Applications Wizards
panel, on which all available applications types are displayed.
To delete an applets/servlets: Select an existing applet/servlet in Application area.
Click Remove button to delete the applet/servlet.
To modify an applet/servlets settings: Select a package and an existing applet/
servlet under it in Application area. The information panel on the right display the
current selected items. You are not allowed to change a packages parameters. To
modify settings of a selected applet/servlet, click the Applet/Servlet Setting link in
the right information area.
This displays step 1 of an applet/servlet creation wizard. Make changes as
necessary.
Export Files
The Application page is displayed when the Application tab is selected.
Figure 37 - Project Properties Editor - Exported Files Tab
In this page, user can customize exported files path by clicking Add, Remove or
Properties button.
In this page the user can also choose which compiler is used for java class compiling.
With this option, the problem mentioned in http://gallium.rnd.gemplus.com/phpBB2/
viewtopic.php?t=1350 will be avoided.
Add new exported file to the current project
This feature will change both the . gdp and . gbp files.
Change J avacard complier
Two compilers are provided at your choice: Eclipse J DT compiler and J avac
complier.
GDP and GBP pages
These two pages display when the <<pr oj ect name>>. gdp or <<pr oj ect
name>>. gdp tab is selected.
GDP page: The source page of GDP file.
GBP page: The source page of GBP file.
The Out Line Viewer
When a project is under edition, the Out Line Viewer provides an intuitive way to
manage the . gdp and . gbp files.
A Typical Development Cycle
The following development tasks are involved and automated by Developer Suite V3.2:
1 Create the project definition and J ava code skeleton with wizards.
2 Debug the applet using one of the following:
The Mobile Simulator GSM (for SIM Toolkit applets), Mobile Simulator CDMA
(for CCAT Toolkit Applet) or Mobile Simulator 3G (for USIM Toolkit) in an I/O
(APDU exchange) mode.
The Simulation Chain 2G (for SIM Toolkit applets or CCAT Toolkit applets) or
Simulation Chain 3G (for USIM Toolkit applets) that trigger over-the-air (OTA)
events.
J ava Card Manager (for J ava Card applets)
APDU OCF Client application (for J ava Card applets).
J CRMI Client application (for J CRMI applets).
SATSA Midlet running in Suns WTK emulator.
HTTP Midlet (for SCWS card servlet).
Static Content Explorer (for SCWS card servlet).
Command line
3 Load and install the applet in a real card using one of the following:
Eclipse (by means of the script pr oj ect . name_l oad. gxsc)
J CardManager (by issuing the Quick Load command or the commands,
Authenticate, Install for Load, Load and Install for Install individually).
Application Manager. For details refer to Chapter 14 - Using the Application
Manager.
4 Carry out tests on a real card using one of the tools listed for debugging.
The applications that can be used for debugging and testing the applet depends on the
type of applet as shown in the following table:
Some worked examples are described to help you get started, as follows:
USIM Toolkit Applet, debugged and tested using the Mobile Simulator 3G,
described in Chapter 7 - Worked Example with USIM Toolkit Applet.
J CRMI Applet, debugged and tested using the J CRMI Client Application, described
in Chapter 8 - Worked Example with J CRMI Applet and Client.
GP Applet debugged and tested using the OCF Client Application and
J CardManager, described in Chapter 9 - Worked Example with J avaCard Applet
and Client.
A SATSA Midlet, described in Chapter 10 - Worked Example with SATSA
MIDlets.
An SCWS Servlet, described in Chapter 11 - Worked Example with Servlet and
Toolkit.
A HTTP Midlet, described in Chapter 12 - Worked Example with HTTP MIDlet.
Figure 38 shows the basic development process followed in this document for the
USIM Toolkit Example applet, described in Chapter 7 - Worked Example with USIM
Toolkit Applet.
Table 6 - Debugging and Testing Tools According to Applet Type
PC Card
Simulation Chain 2G or Simulation Chain 3G Toolkit Applet
Mobile Simulator GSM, Mobile Simulator 3G, Mobile Simulator
CDMA
SATSA Midlet
J CardManager J ava Card Applet
OCF Client Application
SATSA Midlet
J CRMI Client Application J CRMI Applet
SATSA Midlet
Simulation Chain 3G Servlet, Servlet with Toolkit
Features
Mobile Simulator 3G
HTTP Midlet Test Application
Figure 38 - Development Flow with Developer Suite V3.2 Tools
J ava Source
Code
.class file
Output Type
File
Conversion
File
Conversion
.SAP file
.JAR File
Start Card
Simulator
Load the .SAP file
into the Simulator
Personalize the
Applet
(Opt ional)
Run the
application on the
simulator
Simulator
.CAP or .IJC file
Load the .CAP or
.IJC file in the
J ava Card
Personalize the
Applet
(Optional)
Run the
application on the
J ava Card
J ava Card
Wizards
Debug Test
Eclipse
Automated Tasks provided
by the Java Card Plug-in
Non-automated Tasks
How to import examples
1 Click the File ->Import
Figure 39 -
2 Then you will see the picture below and click the Import Examples and Click the
Next button to continue
Figure 40 -
3 Then you can select the example you want by click the square in front of each
example. Then Click Finish
Figure 41 -
6
M-NFC Enabled JavaCard
Applet/Servlet
NFC Contactless Technology
NFC Technology Introduction
This example describes the main concepts of the NFC technology involving the SIM/
USIM card. It guides you how to develop an applet in the SIM/USIM that enables
communication between the SIM/USIM card in the phone and any external contactless
devices like payment cards, Tags or readers in the field.
It is recommended to familiarize first with contactless technologies and especially the
ISO 14443 standards and the Single Wire Protocol (SWP).
A SWP-NFC phone is composed by the following elements:
The Baseband which contains the handset Operating System
The NFC chip which interfaces with the contactless world
The antenna which receives contactless data
The SIM/USIM card processing data coming from the phone on the legacy ISO
7816 interface and data coming from the NFC chip (and so, from the contactless
devices) on the Single Wire Protocol - SWP interface.
Three Modes of Interaction
An NFC phone can act in three modes:
Card emulation: the phone is acting as an NFC card in the contactless system.
Reader emulation: the phone is acting as a NFC reader in the contactless system.
48 M-NFC Enabled J avaCard Applet/Servlet
Peer-to-Peer (out of scope of this document).
Figure 42 - NFC Phone Interaction Modes
Card Emulation Mode
In this mode, the (U)SIM card receives commands (generally APDUs) on the SWP
interface. It processes them and returns the response on the same SWP interface.
As an example, the phone can behave as a payment card:
Figure 43 - NFC Applet - Card Emulation Mode
Reader Emulation Mode
In this mode, the SIM card is the initiator and sends commands to a card or a tag.
As an example, the phone can behave as a Tag reader.
Figure 44 - NFC Applet - Reader Emulation Mode
NFC Contactless JavaCard Applets
Card emulation applets
M-NFC Enabled J avaCard Applet/Servlet 49
Reader emulation applets
Card Emulation Applets
Figure 45 - Card Emulation Applets
These applets are very similar to classic J avaCard applets. All commands (APDUs) are
sent by the RF reader. At the reception of each Contactless APDU the pr ocess ( )
method is called with the APDU header in parameter. The applet computes the
response and sends it back using the classic J avaCard API. It is the responsibility of
the (U)SIM operating System and the NFC chip to forward the response back to the
contactless reader.
Reader Emulation Applets
Figure 46 - Reader Emulation Applets
In Reader mode, the behavior is more complex because the applet needs to send
commands and there is no existing adapted interface to do that.
First, there is a new package to start and stop the reader mode (it must not be always
activated for consumption issues. When reader mode is activated, the NFC chip
generates a Contactless field, and it consumes power from the phone battery).
This package is com.axalto.contactless.readermode.
It contains two main native functions Reader ModeSt ar t ( ) and Reader ModeSt op( )
to respectively start and stop the reader emulation mode.
An NFC contactless applet should always use transient variables when possbile for
better performance.
In card emulation mode, the first APDU sent by the reader should be a SELECT AID
containing the AID of the card emulation applet, otherwise, by default the Contactless
logical channel will stay closed.
Use of SIM / UICC Toolkit In NFC Contactless Applets
In an NFC contactless applet, only the pr ocess( ) method is used to deal with
contactless data. In order to use the SIM Toolkit interface to interact with the user, the
pr ocessTool ki t ( ) method must be called because proactive commands can only
be sent from this method.
The following method describes a way to achieve this:
1 Register to the EVENT_PROACTIVE_HANDLER_AVAILABLE event at the end of
the pr ocess( ) method.
Use STKSer vi ce. get I nst ance( ) . t r i gger STKEvent ( ) to trigger STK event.
2 Catch the EVENT_PROACTIVE_HANDLER_AVAILABLE event in the
pr ocessTool ki t ( ) method and perform the proactive action there.
NFC Demo Overview
The following part is a guide of NFC J avaCard Applet/Servlet development process,
aiming to drive you through the main NFC related features of the Developer Suite,
showing you how to develope, debug and deploy your NFC solution with the tools.
We start creating our first NFC Applet solution by using a developed demo shipped
with the Developer Suite V3.2 tool, which covers two out of the three interaction modes
of a NFC Applet (refer to the Three Modes of Interaction on page 47), to make it clear
to you how a typical NFC (Near Field Communication) Card Applet/Servlet works.
This demo consists of two NFC J avaCard Applets (SWSC feature optional but not
mandatory), one acting in Reader Emulation mode and the other in Card Emulation
Mode. Then two applets then interact with each other.
The general steps will be:
1 Create two NFC J avaCard Projects (i.e. a J avaCard project with NFC with
Proprietary/Standard SCWS chosen as the Target Card Type).
2 Create a NFC Applet (Servlet optional) in the first project, choosing Card
Emulation in Select NFC Mode.
3 Create a NFC Applet (Servlet optional) in the second project, choosing Card
Reader in Select NFC Mode.
4 Trigger Mode Switching to change the second NFC applets current mode from
Emulation to Reader.
5 Start communication between two applets from the NFC Management Window.
Creating An NFC Demo
Here is the DEMO already developed to display the simulation to you.
The DEMO needs two projects to display.One works in the Emulation mode and the
other works in the Reader mode. Then you start two instances of Mobile Simulator 3G
(the NFC solution is based on a 3G card).
The two virtual handsets can communicate with each other in the NFC mode.
Creating Emulation and Reader Project
1 Build a NFC J ava Card project and name it as, e.g. emulation. To create a NFC
project, keep the default seletion NFC with Proprietary SCWS in the third window
of the project creation wizard and then click Finish to complete.
Note:
We put this working example ahead of all the other applets/servlets because it is the
main new feature we want to introduce to you with Developer Suite V3.2.
If Developer Suite V3.2 is complete new to you, please start from the Worked
Example with USIM Toolkit Applet on page 77 and then get back to this chapter after
finishing other parts in this guide.
2 In the same way, create the second NFC J ava Card project and name it as
reader.
Creating an Emulation Servlet
1 Select the project emulation and click icon from the Application Wizards
panel to start adding an applet/servelet into this project.
2 On the Technology selection window displayed, select Emulation to build a NFC
card project of emulation mode. Here you can either choose SCWS to create a
servlet or unselect this feature to add an applet. In our sample screen below, we
create a servlet.
Figure 47 - Emulation Servlet Creation - Step 1 - Technology Selection
3 Click OK to continue. This will add a servlet (by default named as MyServlet 1)
into your project because in the example here SCWS is selected.
4 Follow the Wizard or directly click Finish to quickly complete creating project.
5 Now you have created a NFC servlet project which will be run in emulation mode in
our demostration.
Creating a Reader Servlet
To create a Reader servlet is almostly the same as the process of creating an
emulation one.
1 Select the project reader and click icon from the Application Wizards panel
and add a servlet into it.
Note: On the Target Card Type window, you can also select NFC with Standard
SCWS instead. The difference between an NFC&SCWS Proprietary card project and
an NFC&SCWS Standard card project is the library of project and the code generated.
2 The Technology selection window appear. Choose NFC and Card Reader icons;
;also select SCWS and STK to enable the SCWS and STK features.
Figure 48 - Reader Servlet Creation - Step 1 - Technology Selection
3 Click OK to continue.
4 Follow the wizard to complete creation.
5 On the displayed like below, click the button after Emulation Applet AID field.
Figure 49 - Reader Servlet Creation Step 1
6 A dialogue prompts to you, on which all available emulations are displayed.
Figure 50 - Select An Emulation
7 Select the emulation servlet (emulation MyServlet1) we previously created in the
emulation project above, and click OK to go on.
8 Follow the wizard or directly click Finish to complete the creation.
9 Now you have a servlet (default name MyServlet1) added to your project.
Debugging the Servlet Using the Mobile Simulator 3G
After the process above, we have successfully created an emulation project and a
reader one. In the coming we will see how to debug these two projects.
The example shows you how to debug a servlet using the Mobile Simulator 3G to test
our solution. Since we have selected two technologies, i.e. SCWS and STK, we can
use the demo in two ways.
Starting the Projects
Starting the Reader Project
1 Select the reader project or MyServlet1 under it.
Figure 51 - Start Reader Project - Select Reader Project
2 Then click the top button to run the 3G simulator. This launches the card
simulator, loads the servlet and runs some personalization scripts to and launches
the Mobile Simulator 3G.
Figure 52 - Start Reader Project- Mobile Simulator Launching In Process
3 The Mobile Simulator 3G window appears like below.
Figure 53 - Start Reader Project - MS 3G Started With Reader Servlet
4 Press the power button on the Mobile Simulator 3G to start simulation.
Figure 54 - Start Reader Project - Enter Pin Code for MS 3G
5 Enter PIN code 1234 and press or OK. Then you see the picture below.
Figure 55 - Start Reader Project - Mobile Simulator Home Screen
Starting the Emulation Project
1 Run the emulation project in the same way described in Starting the Reader
Project on page 53.
2 This starts another instance of Mobile Simulator 3G for the card emuation servlet
MyServlet1 we created before.
Figure 56 - Start Emulation Project - MS 3G Started With Emulation Servlet
Two Ways To Use
Use The STK Method:
1 By default Mobile Simulator is started in emulation mode. So we need to switch
the mobile simulator of the Reader servlet into reader mode first.
2 On the Mobile Simulator 3G screen of the Reader servlet, select USAT
applications entry under Main Menu (see the Mobile Simulator screen in the
figure above).
3 Then, click thrice on the OK button to see the Reader tag appears on the top
white banner of the mobile screen, like below:
Figure 57 - Using STK Method - Switch Reader Servlet To Reader Mode
4 On the Mobile Simulator 3G window of the Emulation servlet, click Simulation ->
NFC Window, like Figure 58 shows.
Figure 58 - Using STK Method - NFC Window Menu
5 The NFC Management Window appears.
Figure 59 - Using STK Method - NFC Management Window
6 Click the button .
7 This trigger the transfer between two Mobile Simulators.
The tag has been
switched
8 If the communication completes successfully, you can see the picture below.
Please note the Mobile Simulator in reader mode changes back to Emulation
mode.
Figure 60 - Using STK Method - Transfer Completed
Use The SCWS Feature:
1 Click the Select button at the center of the Mobile Simulator interface:
Figure 61 - Using the SCWS Feature - Mobile Simulator Select Button
2 On the menu list display, select Load URL:
Figure 62 - Using the SCWS Feature - Load URL Menu
3 On the Load URL window, add MyServlet1 (your reader servlet name) after the
existing url. Then it looks like below:
Figure 63 - Using the SCWS Feature - Load URL Dialogue
4 Click Load button. An NFC Application Reader Demo page displays.
Figure 64 - Using the SCWS Feature - NFC Application Reader Demo
5 Enter what you want to transfer in the blank, e.g. 1 Menu1. Then click the Start
button.You can see the mode change into the Reader mode.
Figure 65 - Using the SCWS Feature - Switch Reader Servlet Mode
6 On the Mobile Simulator 3G window of the Emulation servlet, click Simulation ->
NFC Window. The NFC Management Window appears, like Figure 58 - Using
STK Method - NFC Window Menushows.
7 Click the button .
8 This trigger the transfer between two Mobile Simulators.
The tag has been
switched
9 If the communication completes successfully, you can see the picture below.
Please note the Mobile Simulator in reader mode changes back to Emulation
mode.
The Card Simulator Proxy
This proxy can monitor all the card simulators working at the time. The console window
looks like below:
Figure 66 - Card Simulator Console
On the left the tabs list all card types that is running; on the right you can see some
trace information.
1 Clicking on the button will pop up the configuration dialogue. The dialogue will
let you choose the parameter as you want. Click OK to save your changes.
Figure 67 - Card Simulator Console - Configuration Dialogue
2 The button is used to terminate running card simulator(s). On clicking on this
button, a warning message appears, asking for your confirmation.
Figure 68 - Card Simulator Console - Confirm Terminating
3 Click OK to continue. This closes the currently selected card simulator.

Note: If the simulator started from the project you can terminate it by clicking the red
button on right bottom.
Click to
stop card
simulator
The OCF View
This view allows your to manage multiple card simulator instances started from
J avaCard projects.
Figure 69 - OCF View
On the above view, you can:
Click on the red square button to end the currently selected card simulator.
Click the downward arrow next to the red square to show the card simulators
list, like below:
List Of All Running Card Simulators
Click arrow to show card
simulators list
Contact-less Tag Application:
How to create a contact-less tag application
1 Click File->New->Other you will see the Picture below
Figure 70 - Tag Wizards
2 Select the Contact-less Tag Wizard,and Click the Next to continue.
3 After you fill the Project name,Package and Name ,click Finish to complete the
Wizards
How to program a contact-less tag application
Contact-less Tag Application enable you to simulate a contact-less tag and
communicate with the card simulator.
1 You can specify the command you want to send and the response you expected to
receive in an XML file .
Following is an example of the format of the XML file( The same format as contact-less
reader application):
This xml file is expressing the following information.
The contact-less Tag expects to receive a first command C024 from the tag reader
application on card simulator side, then it will response 31323334 to the card
simulator.
And if second command C128 from he tag reader application on card simulator side,
it will response 35363738 to the card simulator.
2 You can implement more complicated function by programming in the java file
which automatically generated with the contact-less tag application.
There are some API you should implement in the java file.
In the processData (byte[] data) , you can judge each command if the one you
expected, and response the command you want to send.
sessionStarted () is called when the tag re-enterField, so you maybe want to clear
some variable in this method. sessionEnded()is called when one session ended.
Figure 71 - Souce Code
How to run a contact-less tag application
To run a tag project there needs to be a J ava Card project works together,We will build
the J ava Card project first then run the tag.java file
Run a Java Card project
1 Build the J ava Card project with the name nfc_tag_reader_stkapplet
2 Select NFC,STK and Tag Reader,then Click OK
Figure 72 -
3 Then you will see the icon
on the left
4 Run the project and change the card to reader mode
Figure 73 -
Run the tag.java file
1 Find the J ava File to run
Figure 74 -
2 Right Click the file to select Run As->1 Java Application to run
Figure 75 -
3 After Step 2 you will see the panel below.
Figure 76 -
1 You can Click the Select button to import the XML file
Figure 77 -
2 You can select the available reader
3 Click the Enter Field button.You can see the tag communicates with the card
simulator.
Figure 78 -
Contact-less Reader Application
How to create a contact-less reader application
1 Click File->New->Other you will see the Picture below
Figure 79 -
2 Select the Contact-less Reader Application Wizard,and Click the Next to
continue.
Figure 80 -
3 After you fill the Project name,Package and Name ,click Finish to complete the
Wizards
How to program a contact-less reader application
Contact-less Reader Application enable you to create a contact-less reader application
to communicate with the card simulator or real card.
1 You can specify the command you want to send and the response you expected to
receive in an XML file .
Following is an example of the format of the XML file:
This xml file is expressing the following information.
The contact-less application first send a command
00A4040010A0000000185000000000000052414441 to card simulator/real card,
then it expected to receive 9000, which mean the card emulation application aid
A0000000185000000000000052414441 was selected successfully in card simulator/
real card side.
Then it sends second command 00770000026162to card simulator/real card.
2 You can implement more complicated function by programming in the java file
which automatically generated with the contact-less reader application.
There are some API you should implement in the java file.
firstCmd()return the first command you want to send, normally it will be select the card
emulation application aid , like in the xml file the cmd is
00A4040010A0000000185000000000000052414441.
In the processData (byte[] data) , you can judge each command if the one you
expected, and response the command you want to send.
sessionStarted () is called when click start button( the commnucation between the card
simulator/real card and the contact-less reader application start) , so you maybe want
to clear some variable in this method. sessionEnded()is called when one session
ended.
Figure 81 -
How to run a contact-less reader application.
To run a contact-less reader application there needs to be a J ava Card project works
together,We will build the J ava Card project first then run the reader.java file
Run the reader.java
1 Find the reader.java file
Figure 82 -
2 Right Click the reader.java file to select Run As->1 Java Application
Figure 83 -
3 Then you can see the panel below
Figure 84 -
4 You can select Click the Select button to select the XML file then Click the Start
button
Figure 85 -
Figure 86 -
Run a Java Card Project
1 Build the J ava Card project with the name nfc_emulation_stkapplet
2 Select NFC,STK and CardEmulation,then Click OK
Figure 87 -
3 Run the project and Click the NFC Window to see how they work
4 You will see the picture below to select the available reader mode simulator
Figure 88 -
5 Click the Enter Field button.You will see how they work
7
Worked Example with USIM
Toolkit Applet
This chapter takes you stepbystep through a worked example of how to create an
applet in your smart card.
In this chapter you will learn how to:
1 Create a J ava Card Project
2 Add a USIM Toolkit Applet to the J ava Card Project.
3 Debug the applet (using the Mobile Simulator 3G)
4 Load and install the applet into a card using Eclipse
5 Test the applet in the Card (Mobile Simulator 3G)
Creating the Java Card Project with the Eclipse IDE
To create the Java Card project within the Eclipse IDE:
2 Switch to Developer Suite perspective as described in Developer Suite
Perspective on page 31.
3 On the Java Card Project Management view as Figure 25 - J ava Card Project
Management View on page 32 shows, double-click Java Card Project (the top
icon on the left column).
4 The Java Card Project wizard starts and displays the first step to let you define the
settings for your project files: Name and Path Name. For the Path Name you can
Note: You can also use the J CardManager and Application Manager to load and
install an applet in the card. For the former, refer to Appendix B - The
J CardManager. For the latter, refer to Chapter 14 - Using the Application Manager.
Note: To see detailed information concerning the completion of any step of the
wizard, click the button in the window of the displayed wizard step.
78 Worked Example with USIM Toolkit Applet
use the browse button to the right of the box to select the path.
Enter the required information and click Next to continue.
Figure 89 - Java Card Project Creation Wizard - Step 1
5 The Java Card Project wizard displays the next step to let you define your
Package name and Package AID. Enter the required information and click Next to
continue.
6 The Java Card Project wizard displays the next step to let you select the type of
card for which you are creating the project. It also provides details about the
standards that will be used for your project. In Card type, select USIM Card R5
and click Next to continue.
Note: The Name must not contain any spaces.
Note: At any time during the execution of the wizard you can click: Back to return to
the previous step, Finish to complete the wizard using the default settings, or Cancel
to stop the wizard.
Worked Example with USIM Toolkit Applet 79
7 The Java Card Project wizard displays the next step to let you optionally choose a
sample as the template for your new project, as below:
To use a sample template, select the Create a project from one of available
sample templates checkbox and select a template from the Available
Samples combo box.
Click Next button to continue.
On the Sample Template Information page, select dependencies projects for
the main project and click Finish to complete the wizard.
If you dont want to use a sample template, click Next button to continue.
8 The Java Card Project wizard displays the next step to let you select whether or
not you want to use an APDU trace format (ATF) personalization script for the
project. This script would be run before the applet is loaded in the card or simulator.
It could for example be used to create files that will be used by the applet. To use a
script, check the box Select a personalization script, then enter the path and
name of the script file in ATF Script. You can use the browse button to the right
of the box to select the script file. Click Next to continue.
9 The Java Card Project wizard displays the next step to let you choose which tool
you want to use for running and debugging your applet:
Mobile Simulator 3G
Mobile Simulator GSM
Midlet Test Application
Command Line
J CardManager
Simulation Chain 2G
Simulation Chain 3G
Mobile Simulator CDMA
Client Test Application (OCF/J CRMI client)
None
For this example, choose Mobile Simulator 3G and click Next.
Note: You can also include personalization scripts by customizing the generated
_.load.gxsc file using the Script Editor.
10 The Java Card Project wizard displays the next step to let you add external export
files to the project.
To add export files to the project:
a) Click .
b) When the Select the directory window opens, browse to the export file that
you want to add to the project. Repeat this operation for each file to be added.
To edit the path name of an export file:
a) Select the export file in the Step 7 Export Files window.
b) Click .
c) Edit the path name.
To remove an export file from the selected list:
a) Select the export file to be removed in the Step 7 Export Files window.
b) Click .
11 Set the class path and optionally the source path of the external library.
To set the class path:
a) Click the Class Path tab in the Step 7 Export Files window.
Note: Adding external files is optional. It is necessary, however, if you are importing
an external library into your project:
Export Path entries for the conversion process
Class Path entries for compiling
Source Path entries to be able to step into the library's code when debugging
Note: You only need to set the source path if you want to debug this external library.
b) Use the buttons to add, edit or remove paths in the same way as for export
files.
The class path is used when compiling the project (an external library configuration
is created).
To set the source path:
a) Click the Source Path tab in the Step 7 Export Files window.
files.
12 Click Next to continue. The Java Card Project wizard displays the final step to let
you add DAP load parameters as shown in the following figure:
Note: This step is optional. To simplify your project, you can omit DAP settings during
initial development, debugging and testing. Then if you want to use DAP to load your
application, you can add it at a later stage by downloading it with the J CardManager or
Application Manager.
To add DAP parameters:
a) Click Add. This opens the Adding a DAP control dialog box as shown in the
following figure:
Figure 94 - Adding a DAP Control
b) In Security Domain, enter the AID of a security domain or select it from the list.
c) Either choose the option button Manual, and enter the value of the DAP
parameters in DAP Value, or choose the option button Automatic and specify
the Key Definition parameters. In Key Definition field:
Select Key File option button. Check Use default key file or enter values for
Key file, Key set version (hex), and Key index in set.
Or select Key value, and then either enter the value in Key or select it from the
list.choose one of the option buttons Key file or Key value.
Click OK to return to step 8 of the Java Card Project wizard.
To edit DAP Parameters:
a) Select the security domain AID in the step 8 of the Java Card Project wizard.
b) Click Modify. This opens the Modifying a DAP Control dialog box, which
apart from its title is identical to the Adding a DAP Control dialog box shown in
Figure 94 on page 83.
c) Modify the parameters and click OK to return to step 8 of the Java Card
Project wizard.
To remove DAP Parameters:
b) Click Delete.
13 Click Finish to continue. If you specified export files, you are asked if you want to
copy these files to your project workspace. Click Yes or No.
14 You project is completed now. You can see an icon followed by your project
name in Package Explorer view on the left-hand of current workbench.
15 After creation, the Project Properties Editor launches with the created projects
definition. Please refer to Project Properties Editor on page 38 for more
information.
Adding a USIM Toolkit Applet to a Project
The Toolkit Applet wizard helps you add a Toolkit Applet (in this example, a USIM
Toolkit Applet) to your J ava Card project.
In Package Explorer, select the java card project your just created (or any existing
java card project you want to add the applet to). On the Java Card Project
Management view (as in J ava Card Project Management View on page 32), double-
click Toolkit Applet (second icon from the top in the right column) to start the Toolkit
Applet wizard.
The Toolkit Applet Wizard
1 When you start the wizard, the first step window displays to let you define the
package settings for your USIM Toolkit applet:
Figure 95 - The Toolkit Applet Wizard Step 1
Enter the Applet name and Applet AID, then click Next to continue.
2 The Toolkit Applet wizard displays the next step, as shown in Figure 96, to let
you define the applet's Instance AID and any optional Application specific
parameters that will be used for the applet. These parameters are the Application
specific parameters passed in the applets i nst al l ( ) method defined in the J ava
Card specification and also in the Install command, as specified in the Global
Note: The same Toolkit Applet wizard is used for SIM Toolkit, USIM Toolkit and CCAT
Toolkit applets. The wizard differs slightly according to the type of target you defined in
Step 3 of the Java Card Project wizard. A separate wizard is available for SIM Toolkit
applets.
Platform specification. For this USIM R5 example, the corresponding specification
versions are Java Card 2.2 and GlobalPlatform Card Specification, Version 2.0.1.
Enter the Instance AID value. If you are entering application specific parameters,
check the box Application specific parameters and enter the value in Specific
parameters. Click Next to continue.
The Toolkit Applet wizard displays the next step to let you select the event(s) that
trigger the applet as shown in the following figure:
3 Select the event(s) that you want to trigger the applet in the Toolkit events
available column and click the right arrow. The events appear in the Toolkit
events selected column. To remove any selected events, select them in the right
pane and click the left arrow. Click Next to continue.
4 The Toolkit Applet wizard displays the next step to let you to define the USIM
Toolkit applet's installation parameters. Click each folder in turn to expand it and
reveal the parameters.
5 Click the +next to Menus, to display the menus as shown in the following figure:
Figure 99 - The Toolkit Applet Wizard Step 4 Menus
Note: If you had chosen a (U)SIM R6 or R-UIM card instead of a USIM card as your
card type when creating the J ava Card project, this fourth step would contain a slightly
different list of parameters.
a) If you want to add one or more menus, click +for each new menu. You can
remove a menu by selecting it and clicking -. The Max Menu Entries
automatically displays the number of menus. For this example, click +once to
add a second menu.
b) Enter a value in hex for Max Text Length.
c) If you want to change the values for Position and/or Identifier, double-click the
value you want to change and enter the new value. By default, the wizard gives
a position of 0, which means that the operating system chooses the position for
you.
d) Click the - next to Menus to hide the menu parameters.
6 Click the +next to Priority and Timer, to display the priority level and maximum
number of timers as shown in the following figure:
Figure 100 - The Toolkit Applet Wizard Step 4 Priority and Timers
Enter the Priority Level value (01hFFh where FFh is the lowest priority) and Max
timer value (the maximum number of timers).
e) Click the - next to Priority and Timer, to hide the priority level and maximum
number of timers parameters.
7 Click the +next to Channels, to display the maximum number of channels
information as shown in the following figure:
Figure 101 - The Toolkit Applet Wizard Step 4 Channels
a) By default the maximum number of channels is set to one. If you want to
change this, check the box Maximum number of channels for this
application instance and use the spin box to change the number up to a
maximum of 7.
b) Click the - next to Channels, to hide the maximum number of channels
information.
8 Click the +next to Minimum security level, to display these parameters as shown
Figure 102 - The Toolkit Applet Wizard Step 4 Min. Security Level
These parameters specify the minimum security requirements to access the
USIM Toolkit applet in OTA (over the air) mode.
a) If you want to specify values, check the box Enable Minimum security level
parameters.
b) In Minimum security level, do one of the following:
Choose Proprietary Mechanisms, enter the MSL parameter and MSL data
Choose Minimum SPI1, and click Edit to display the Security Parameters
dialog box as shown in the following figure:
Figure 103 - The Toolkit Applet Wizard Step 4 Security Parameters
Check Ciphering to specify that all communication with the applet is to be
ciphered.
Choose one of the options in Security and one of the options in Counter.
Click OK.
c) Click the - next to Minimum security level to hide these parameters.
9 Click the + next to SIM Access parameters, to display these parameters, as
shown in the following figure:
Figure 104 - The Toolkit Applet Wizard Step 4 SIM Access Parameters
10 Choose the required File System access conditions.
If you choose APDU access mechanism, click Edit and in the dialog box Set
the access rights, check the codes that the applet is considered to know, that
is the code is considered as being correctly presented. This is used to access
the files in the file system.
If you choose 3GPP access mechanism, enter the value in Access Domain
Data.
If you choose Custom Access domain, enter the values in Access Domain
Parameter and Access Domain Data.
Click Next to continue.
11 The Toolkit Applet wizard displays the next step to let you enter titles for the
menus you specified in the previous step. Click each title that you want to edit and
enter the title. When you have finished, click Next.
12 The Toolkit Applet wizard displays the last step to let you select whether or not
you want to use an ATF personalization script for the applet, for example to update
files. To use a script, check the box Select a personalization script, then enter
Note: For more detailed information about the individual parameters, click Help. For
information about the Access Domain Data values, refer to 3GPP TS 23.048 for
details.
the path and name of the script file in ATF Script. You can use the browse button
to the right of the box to select the script file.
13 Click Finish to complete the wizard. Eclipse displays the J ava code for your newly
created applet as shown in the following figure:
Figure 105 - The Toolkit Applet Wizard Termination
Debugging the USIM Toolkit Applet
The following section describes how you can use the Eclipse IDE to interactively debug
the applet. This is possible because Developer Suite V3.2s Eclipse plug-in used in
conjunction with the applet wizards automatically configure Eclipses project settings
with the card simulator as the main class of the applet. It also launches the relevant
client application to run for the debugging session, the Mobile Simulator 3G (or Mobile
Simulator GSM and Mobile Simulator CDMA), J CardManager, or Simulation Chain (or
Simulation Chain 3G).
Client Applications Used
The actual client application you use to debug an applet depends on the type of applet
you want to debug.
You use:
The Mobile Simulator GSM, Mobile Simulator 3G, or Mobile Simulator CDMA.
The J CardManager for J ava CardGP applets (but you can also use it to send
APDU commands to a Toolkit applet).
Note:
A personalization script is used to perform tasks that are only required once when the applet is
initially installed. A typical example is initializing objects (for example, key values) used by the
applet - in this case the script would contain APDU commands to be executed by the applet via its
pr ocess( ) method.
You can also include personalization scripts by customizing the _. l oad. gxsc file using the
Script Editor.
Simulation Chain 2G (for SIM Toolkit or CCAT Toolkit applets), or Simulation Chain
3G for USIM Toolkit applets).
As the applet in this example is a USIM Toolkit Applet, this chapter describes how to
debug the applet with the Mobile Simulator 3G. Examples for debugging with
J CardManager or the OCF client or J CRMI client applications, are given in Chapter
8 - Worked Example with J CRMI Applet and Client.
Mobile Simulator Versions
The type of Mobile Simulator you use depends on what version of Developer Suite
V3.2 you are using, the evaluation version or full version. Not all the features in the full
version are available in the evaluation version.
The following table lists the major differences between the various versions of the
Mobile Simulator (please refer to the Mobile Simulator On-Line Help for full details of
the different functions available for the version of the Mobile Simulator installed on your
computer):
Note: You can change the client application in the Run or Debug window by selecting
a different application in the Choose the client application to run list (see Figure
108 - Debug window on page 94). In fact the two windows are almost identical apart
from the Run or Debug button at the final step.
Table 7 - Mobile Simulator Capabilities
Evaluation Version Full Version
Simulated Cards Only Simulated and Real Cards
No dual slot capability Can load and simulate two cards and simulate dual slot operation
No APDU Exchange Custom APDU Exchange Feature
No pause mode Pause feature during the exchange of APDU commands between
the Mobile Simulator and a card
Note: These capabilities are valid for all the Mobile Simulators.
Applet Debugging Steps
The following illustration shows the user interaction steps and automated (Developer
Suite V3.2 Eclipse plug-in) steps involved in using interactive debugging for an applet:
Figure 106 - Interactive Debugging of USIM Toolkit Applets
Debugging the Applet Using the Mobile Simulator 3G
This example describes how to debug your project using the Mobile Simulator 3G as
the client application. The choice of which client application to use for debugging is
defined with the project settings.
Step 1: Setting breakpoints in the applets code
1 Select the project you created in the Eclipse IDE.
2 In the . j ava source file, set a breakpoint at the menuAction line (single menu that
you specified in step 4a) on page 87).
To set a break point:
Double lick the gray bar to the left of current line. A bullet (which the red arrow
points to) indicates the presence of the breakpoint in the following figure:
Figure 107 - Setting Breakpoints in the Java Code
User IDE Applet
Card
Simulator
Client
Application
Set Breakpoint (Step 1)
Debug
(Step 2)
Start & Load the applet
Start
Operate client application (Step 3)
Send APDU
Trigger
Applet
Stop
on
Breakpoint
Notify
execution
stopped
(Step 4)
User Interaction
Automated Action
To remove a breakpoint:
Double-click the gray bar to the left of current line. The bullet disappears.
Step 2: Debugging the project
1 In Eclipse, select Project > Run > Debug to open the Debug window.
2 In the tree structure in the left pane, click the Javacard Project Launch node and
select your project to display the runtime configuration as shown in the following
figure:
Figure 108 - Debug window
3 From the Choose client application to run dropdown menu, select Mobile
Simulator 3G. Features availability varies according to the license status of
Simulation Suite V2.0 on your PC.
4 Click Apply and then Close to close Debug window if you want to debug later.
Click Debug to close the Debug window and start debugging right away.
5 This: launches the card simulator, loads the applet and runs any personalization
scripts, and launches the Mobile Simulator 3G.
Figure 109 - Mobile Simulator 3G Waiting for User Interaction
Step 3: Operating the Client Application (Mobile Simulator)
1 Press the power button on the Mobile simulator.
2 Enter PIN code, 1234 and press for OK.
3 Select the USAT application option and press for OK.
4 Select 1Menu1 item and press for OK.
5 A dialogue prompts to you, asking whether you like to switch to Debug perspective
or keep using current one. Click No to continue.
6 Execution stops.
Step 4: Notification that execution has stopped on a breakpoint
When you selected the menu item above, the breakpoint set in the Eclipse IDE is
triggered and control is returned to the Eclipse IDE, as shown in the following
illustration:
Figure 110 - The Triggered Breakpoint in the Eclipse IDE
Step 5: Bug detection and correction
You can now use the built-in debugging facilities of the Eclipse IDE to detect and
correct any problems in the code. For information on how to do this, refer to your
Eclipse documentation.
Loading and Installing the Applet in a Card using
Eclipse
For each project, Developer Suite V3.2 generates a load script that performs the
following commands sequentially for you:
Authenticate
Install for Load
Load
Install for Install
You can edit the script by rightclicking the _l oad. gxsc file in the Package Explorer
window, and choosing Script >Edit as shown in the following figure:
Figure 111 - Accessing the Script File in Eclipse
This action opens the Script Editor as shown in the following figure:
Figure 112 - Script Editor Showing the Load Script
To edit the parameters of a command, select the command in the Command list on
the left.
You can also use the Script Editor to add applet or card personalization scripts. To load
and install the USIM Toolkit Applet, run the load script by rightclicking the _l oad. gxsc
file in the Project window, and choose Script >Play.
Testing the USIM Toolkit Applet in a Real Card
Now that you have loaded your USIM Toolkit Applet in a card, you can test it as follows:
1 Stop the card simulator by clicking the button at the bottom of the screen.
2 Load the applet on the card, for example, using the GXSC deployment script.
3 In J CardManager, in Terminal, select the card reader containing your card.
4 Run the test application on the card to test the applet.
8
Worked Example with JCRMI
Applet and Client
This chapter presents an example of how to create a J ava Card RMI applet and a J ava
Card RMI client application.
In this example, you will create a J CRMI applet that defines and implements an
interface with a method called sum that returns the result of two numbers added
together. You will also create a J CRMI Client project that connects to the applet and
calls the sum method in the applet.
This example uses the following steps:
2 Create a Remote Object Interface
3 Add a J CRMI Applet to the J ava Card Project that will use the remote object
4 Create a J CRMI Client Project that will use the J CRMI applet
5 Debug the J CRMI applet using the J CRMI Client application
6 Load and install the applet into a card using Eclipse
7 Test the Applet in the card using the J CRMI Client application
Creating the Java Card Project with Eclipse IDE
The creation procedure was described in the previous chapter. Refer to Creating the
J ava Card Project with the Eclipse IDE on page 77.
In step 5, choose Client Test Application as the tool you want to use to run and debug
the applet.
Creating a Remote Object Interface
In this step you will create a remote object that can be accessed by an RMI client
application.
Note: Typically, the Remote Object Interface wizard is invoked during step 2 of the
J CRMI applet wizard. This example runs it before the J CRMI Applet Wizard in order to
describe it more clearly.
Caution: This example illustrates what happens for USim R6 cards, so make sure
you choose USim Card R6 at step 3 of the Java Card Project wizard.
100 Worked Example with J CRMI Applet and Client
1 Make sure you are in Developer Suite perspective. More information on this
perspective has been mentioned in the previous chapter on page 31.
2 On Java Card Project Management view panel, double-click Remote Object.
The Remote Object Wizard
When you start the wizard, the first step window displays to let you create a new
interface or use an existing interface as follows:
Figure 113 - Remote Object Wizard Step 1
1 For this example, click Create a new interface, and enter the values for Interface
name, Implementation name and select a Base Class.
2 Click Next.
Note: You can only select the Remote Object wizard if you have previously created a
project with the Java Card Project wizard specifying card type USIM card R5, USIM
card R6, or R-UIM card. This example shows a typical USim Card R6 project. At any
time during the execution of the wizard you can click Back to return to the previous
step, Finish to complete the wizard using the default settings, or Cancel to stop the
wizard.
Note: You could also select Use existing interface and use the browse button to
select the existing interface. In this case, the wizard skips the next wizard step.
Worked Example with J CRMI Applet and Client 101
3 The wizard displays step 2 as shown in the following figure where you define the
new interface.
4 Click to open the Add Method dialog box as shown in the following figure:
Figure 115 - The Add Method Dialog Box
5 In Method name enter sum.
In Return type, select short and leave Array empty.
In Parameters click the button to open the Add Parameter dialog box. Add two
parameters, param1and param2 both with Type short and leave Array empty in
both cases. The Add Method dialog box looks like the following figure:
Figure 116 - The Add Method Dialog Box (2)
You do not need them for this example, but you can use the edit buttons and
remove buttons to edit and remove parameters and exceptions. In the
Parameters section, you can change the order by using the up and down arrow
buttons. For more detailed help, click Help.
In this example you have not added any exceptions, but the buttons operate in the
same way as Parameters.
When you have completed the Add Method information, click OK. This returns you
to the Step 2 window. Again you can use the edit and remove buttons to
edit and remove methods.
In the step 2 window, click Next.
6 The final step of the wizard lets you specify the stub generators, as shown in the
following figure:
Check the box for the stub generators that you want to include (you must check at
least one of the boxes). If you want you can change the Directory Target by using
the browse buttons.
If you included the SATSA stub generator, enter the version of WTK in WTK Home
by selecting it from the list or using the browse button to reference it from your hard
disk. Optionally, check the Preverification box if you want to preverify the remote
object.
When you have finished, click Finish.
Eclipse creates and displays the remote object.
7 In the Java Card project, select the class containing the interface implementation
on the Implementation tab to display the J ava source code.
Note: The preverify process checks for the existence of finalizers, native method calls,
or floating point operations which may be prohibited by the connected limited device
configuration (CLDC).
8 Locate the / **@todo YOUR CODE HERE*/ line and replace it with content
highlighted in the following figure. Also remember to change the result line below.
Figure 118 - Java Card Project Implementation Source
9 Compile the project by choosing Run >Run As > Java Card Project or using the
direct button in Eclipse Toolbar.
Adding a JCRMI Applet to a Project
The J CRMI Applet wizard helps you add a J CRMI Applet to your J ava Card project.
To start the JCRMI Applet wizard:
On Java Card Project Management view panel, double-click JCRMI Applet Wizard.
Note: You can only select the JCRMI Applet wizard if you have previously created a
project with the Java Card Project wizard specifying card type USim card R5, USim
card R6, or R-UIM. At any time during the execution of the wizard you can click: Back
to return to the previous step, Finish to complete the wizard using the default settings,
or Cancel to stop the wizard.
The JCRMI Applet Wizard
1 When you start the wizard, the first step window displays to let you define the
package settings for your J CRMI Applet:
Figure 119 - The JCRMI Applet Wizard Step 1
Enter the Applet name, and Applet AID then click Next to continue.
2 The JCRMI Applet wizard displays the next step as shown in Figure 120 to let
you select the remote object to use as the initial reference. For this example leave
the remote object you have just created as the initial reference. The wizard can let
you select an external project or create a new remote object. For more details
about these, click .
Check GP secure channel if the J CRMI applet is to use a GP secure channel, that
is, it is to be a J ava CardGP applet.
Click Next.
3 The JCRMI Applet wizard displays the next step as shown in Figure 121 to let
you define the applet's Instance AID and any optional Application specific
specific parameters used in the Install command, as specified in GP 2.1.1. Refer
to GlobalPlatform Card Specification, Version 2.1.1 for more details.
Note: Alternatively you can use the button to define the Remote Object Interface.
This takes you into the Remote Object Interface wizard and returns you to step 2 of
the J CRMI Applet wizard.
4 The JCRMI Applet wizard displays the last step to let you select whether or not
you want to use an ATF personalization script for the applet, for example to update
files. To use a script, check the box Select a personalization script, then enter
the path and name of the script file in ATF Script. You can use the browse button
to the right of the box to select the script file.
created applet.
Creating a JCRMI Client Project
In this step you will create a project for the J CRMI Client application:
In Java Card Project Management view, double-click JCRMI / APDU OCF Client
Project.
The JCRMI/APDU OCF Client Project Wizard
1 In Step 1, enter the information for the J CRMI client application and click Next.
Note: At any time during the execution of the wizard you can click Back to return to
to stop the wizard.
2 In Step 2, enter the information for the J CRMI applet and click Next. This displays
the third and final step as follows:
Figure 122 - JCRMI/OCF Client Project Wizard Step 3
3 If you checked GP Secure Channel in step 2 of the J CRMI applet wizard (see
Figure 120 on page 106), check Use GP Authentication and complete the
section Card Property File. In the Card Property File, either leave Use default
key file checked or clear it and browse to the key file that you want to use for
authentication. In this case you can use the dropdown combo boxes to modify the
Key set version. You can also change the values of the keys themselves by
clicking Edit.
4 In Security Level (SCP01) choose the level of security you want for the secure
channel by clicking one of the option buttons.
5 Click Finish.
Debugging the JCRMI Applet Using the JCRMI Client
Application
The steps in debugging a J CRMI applet are the same as for a USIM Toolkit Applet.
Refer to Applet Debugging Steps on page 93.
This example describes how to debug your project using the J CRMI Client application.
Step 1: Call the new function in the JCRMI client
1 Open the J CRMI Client Project (for example, testClient.java).
2 Locate the line / **@todo ADD YOUR TEST HERE*/ . Replace it with the lines 23-
29 as shown in the following figure:
Figure 123 - Call New Function
1 Open the J ava Card project in Eclipse IDE.
2 Select the tab with the projects remote interface implementation and in the . j ava
source file, set breakpoints (see Step 1: Setting breakpoints in the applets code
on page 93 for more details about breakpoints). For this example, set a breakpoint
in the line shown in the following figure:
Figure 124 - Setting the Breakpoint for JCRMI Client Example
1 In Eclipse, select Debug from the Run menu. This opens the debug window.
2 To create a Debug configuration for client project, expand Java Application node
in the tree structure in the left pane. Click the button. A new item named
New_configuration is added under Java Application and by default selected.
3 On the configuration page shown on the right, enter a name for the new
configuration(e.g. J CRMIClient). Click Browse and select your client project. Click
Search and select the class package of your client project.
Figure 125 - New Debug Configuration for Client Test Project
4 Click Apply to save current page.
5 Then, in the tree structure in the left pane, switch to the applet project. On the run
time configuration pane to the right, select Client Test Application from the
Choose client application to run drop-down list, as shown in the following figure:
Figure 126 - Edit Runtime Configuration Window
6 Click Customize. This opens the Application Parameter Editor dialog box.
7 In the Application Parameter Editor dialog box, click Browse and select the
J CRMI client project.
8 Click OK to close the Application Parameter Editor dialog box.
9 Click OK to close the Application Parameter Editor settings window.
10 If you dont start debugging immediately, click Apply to save changes and then OK
to close the Debug window.
11 If you want to start debugging right away, click Debug button. This builds (compiles
and converts) the project, launches the card simulator, loads the applet in the card
simulator and runs any personalization scripts, and launches the client application.
triggered and control is returned to the Eclipse IDE.
Eclipse
The steps to load and install an applet in a card are the same as previously described
for the USIM Toolkit Applet example. For details see Loading and Installing the Applet
in a Card using Eclipse on page 97.
Testing the JCRMI Applet in a Real Card
Now that you have loaded your J CRMI applet in a card, you can test it as follows:
1 Stop the card simulator by clicking the button at bottom of the screen.
2 Load the applet in the card, using the _l oad. gxsc script.
3 Switch to the client project.
4 Select the card reader containing your card.
5 Run the client project.
Note: Eclipse may prompt a dialogue to you, asking whether to change current
perspective to Debug. Click No to discard it.
9
Worked Example with
JavaCard Applet and Client
This chapter presents an example of how to create a J avaCard applet and a J ava Card
client application.
A J ava Card applet can be debugged and tested using either an OCF Client application
or the J CardManager. This example shows how to use both options and uses the
following steps:
2 Add a J avaCard applet to the J ava Card Project
3 Debug the J avaCard applet using J CardManager
4 Create an OCF client application
5 Debug the J avaCard applet using the OCF client application
6 Load and install the applet into a Card using Eclipse.
7 Test the Applet in the Card using the J CardManager and OCF client application.
Creating the Java Card Project with Eclipse IDE
This step was described in the previous chapter. Refer to Creating the J ava Card
Project with the Eclipse IDE on page 77.
After creation of your Java Card Project, add J ava Card Applet to it as described
below.
Adding a JavaCard Applet to the Java Card Project
In this step you will add a J ava Card applet to your project.
1 Make sure you are in Developer Suite perspective. More information on this
perspective has been mentioned in the previous chapter on page 31.
Caution: This example illustrates what happens for USim R6 cards, so make sure
you choose USim Card R6 at step 3 of the Java Card Project wizard.
114 Worked Example with J avaCard Applet and Client
2 In Java Card Project Management view, double-click JavaCard Applet. This
starts the JavaCard Applet wizard.
The JavaCard Applet Wizard
1 When you start the JavaCard Applet wizard, the first step window displays the first
step to let you define the package settings for your J avaCard applet. Enter the
Applet name, and Applet AID then click Next to continue.
2 The JavaCard Applet wizard displays the next step to let you define the applet's
Instance AID and any optional Application specific parameters that will be used
for the applet. These parameters are the Application specific parameters used in
the Install command, as specified in GP 2.1.1. Refer to GlobalPlatform Card
Specification, Version 2.1.1 for more details.
3 The JavaCard Applet wizard displays the next step to let you select whether or not
you want to use an ATF personalization script for the project. To use a script, check
the box Select a personalization script, then enter the path and name of the
script file in ATF Script. You can use the browse button to the right of the box
to select the script file.
4 Click Next. This displays the final step of the wizard in which you choose the
following J ava Card options for the applet
Object deletion mechanism
Package and Applet Deletion
Logical channels mechanism
Global Platform specifications
Check as many boxes as you wish and click Finish.
Debugging the Java Card Applet Using
JCardManager
1 Open the project you created in the Eclipse IDE.
2 Set breakpoints for the Initialize Update and External Authenticate commands in
the . j ava source file.
Note: You can only select the JavaCard Applet wizard if you have previously created
a project with the Java Card Project wizard.
to stop the wizard. To see detailed information concerning the completion of any step
of the wizard, click the button in the window of the displayed wizard step.
Note: A personalization script is used to perform tasks that are only required once
when the applet is initially installed. A typical example is initializing objects (for
example, key values) used by the applet - in this case the script would contain APDU
commands to be executed by the applet via its pr ocess( ) method.
Worked Example with J avaCard Applet and Client 115
Step 2: Debugging the project with JCardManager
1 In Eclipse, select Debug from the Run menu. This opens the debug window.
2 In the tree structure in the left pane, switch to the applet project. On the run time
configuration pane to the right, select JCardManager from the Choose client
application to run drop-down list, as shown in the following figure:
Figure 127 - Edit Runtime Configuration Window
4 If you want to start debugging right away, click Debug button. This: builds
(compiles and converts) the project launches the card simulator, loads the applet
and runs any personalization scripts, and launches the J CardManager.
In J CardManager, send the Authenticate command. The processing stops on the
break points and triggers the applet.
If you implemented APDUs in the pr ocess method, use the Send APDU command to
trigger them.
Creating the OCF Client Application
In this step you will create a project for the OCF Client application.
In Application Wizards view, double-click JCRMI / APDU OCF Client Project. This
starts the JCRMI/APDU OCF Client Project wizard. For details on how to complete
the wizard, see The J CRMI/APDU OCF Client Project Wizard on page 107.
Debugging the Java Card Applet Using the OCF
Client Application
The steps in debugging a J ava Card applet are the same as when debugging with the
J CardManager. Refer to Debugging the J ava Card Applet Using J CardManager on
page 114. The only difference is that in the Edit Runtime Configuration window. Here
you must follow these steps:
1 In the Choose client application to run dropdown list, select Client Test
Application.
116 Worked Example with J avaCard Applet and Client
2 Create a Debug configuration for your Client Test project, as described by 2-5 in
Step 3: Debugging the project on page 109.
3 Click Customize. This opens the Application Parameter Editor dialog box.
4 In the Application Parameter Editor dialog box, click Browse and select the OCF
client project.
5 Click OK to close the Application Parameter Editor dialog box.
7 If you want to start debugging right away, click Debug button. This builds (compiles
and converts) the project, launches the card simulator, loads the applet in the card
simulator and runs any personalization scripts, and launches the client application.
Eclipse
The steps to load and install an applet in a card are the same as previously described
for the USIM Toolkit Applet example. For details see Loading and Installing the Applet
in a Card using Eclipse on page 97.
Testing the Java Card Applet in a Real Card
Now that you have loaded your J ava Card applet in a card, you can test it as follows:
1 Stop the card simulator by clicking button at bottom of the screen.
2 If necessary, change the client program in the Edit Runtime Configuration dialog
box as follows:
For the OCF client, choose Client Test Application, and click Customize to
select the OCF client project.
For the J CardManager, choose JCardManager.
3 In J CardManager, In Terminal, select the card reader containing your card.
4 In J CardManager choose the Select command from the Commands treestructure
on the left (Commands >USim Card R6 >Platform >GP >Select).
In the Select command check Specific AID and select the J CRMI applet from the
list, then click Go.
5 If the applet is a GP applet, perform an Authenticate command in J CardManager
and in this command, clear the box Select the Issuer Security Domain before
Authentication. Click Go to perform the command.
If the applet is a GP applet, issue the commands you want to test the applet in the card
using Send APDU Secure (Commands >USim Card R6 >Platform >GP >Send
APDU Secure).
If the applet is not a GP applet, issue the commands you want to test the applet in the
card using APDU Commands (directly under Commands).
10
Worked Example with SATSA
MIDlets
This chapter presents an example of how to create a Security and Trust Services API
(SATSA) compatible midlet and configure it to access an applet on a card.
A MIDlet is a J ava program for embedded devices, more specifically the J ava ME
virtual machine. Generally, these are games and applications that run on a cell phone.
It is an application written for MIDP. MIDlet applications are subclasses of the
javax.microedition.midlet.MIDlet class that is defined by MIDP (Mobile Information
Device Profile). SATSA provides a standard API to allow MIDlets to communicate with
J ava Card applets.
Overview
The major steps described in this example are:
1 Develop an applet. For SATSA, this applet can be a J ava Card Applet, a Toolkit
Applet, or a J CRMI Applet.
2 Create a J 2ME MIDlet.
3 In the MIDlet, add a SATSA access method to allow it to communicate with the
applet.
4 Debug the applet and midlet.
Creating the Applet
To create the project:
1 Create a new J ava Card project: On the Java Card Project Management view,
double-click Java Card Project from Application Wizards field.
2 At Step 1 of the wizard, specify a name for the project and the Directory in which to
store project files.
3 At Step 3 of the wizard, choose USim Card R5 as the Card type.
4 At Step 5 of the wizard, choose Midlet Test Application from the list of available
Tools.
Note: Before starting this example, make sure that you have already installed Eclipse
Enterprise or Developer editions, and the Wireless Toolkit (WTK) 2.3. For details on
how to install WTK 2.3, refer to Importing WTK Devices Into Eclipse on page 16.
118 Worked Example with SATSA MIDlets
5 Click Finish to complete the wizard.
To add an applet (in this example a JCRMI applet)
1 Double-click JCRMI Applet Wizard in the Application Wizards field to start
J CRMI Applet creation wizard.
2 On Step 2 of the J CRMI Wizard, click to define a new remote object.
3 On the Remote Object Wizard - Step 1 of 3 windows, ensure Create a new
interface is selected and click Next.
4 On the Remote Object Wizard - Step 2 of 3 window, click .
5 On the Add Method window, define an Add method in the remote interface with a
return type of Short and two Short parameters:
shor t add( shor t v1, shor t v2)
The corresponding Add Method window is as follows:
Figure 128 - Remote Method Definition
6 Complete the J CRMI Applet Wizard to generate skeleton code.
Worked Example with SATSA MIDlets 119
7 In the source code for the remote interface implementation, find the Add method.
Modify the code as follows and set a breakpoint on the highlighted line:
Figure 129 - Adding the Add Method
Building the Midlet
To create a midlet project:
1 In Eclipse, from the File menu select New > Project. This action starts the New
Project window.
2 On the New Project window, unfold J2ME and select J2ME Midlet Suite under it,
as shown by the following figure:
Figure 130 - Create New Midlet Suite Project
3 Click Next to start step 1 of New J2ME Project wizard.
4 In Name enter a name for your project, for example satsamidlet. Optionally you
can choose to change the default values for Location or enable preprocessing.
5 In step 2 of the Project Wizard, select a device group and choose the device. You
can click Manage Devices button to import devices. Here Wireless Toolkit 2.5
should have been imported by you during post-installation phase following the
steps described in Importing WTK Devices Into Eclipse on page 16.
Figure 131 - J2ME Midlet Project Wizard Step 2
6 Click Finish to complete the wizard and generate skeleton code for the applet in
Eclipse.
Creating the MIDlet
To create the midlet:
1 In Eclipse, from the File menu select New > Other. This action starts the New
window.
2 On the New window, unfold J2ME and select J2ME Midlet under it, as shown by
the following figure:
Figure 132 - Create New J2ME Midlet
3 Click Next to start step1 of New J2ME Midlet wizard:
Figure 133 - New J2ME Midlet Wizard - Step 1
4 For Source Folder, browse to select the midlet project you created (or any midlet
project you want to add the midlet to) in Source Folder Selection window.
Figure 134 - Source Folder Selection Window
5 Click OK to close Source Folder Selection window. Back on step1of New J2ME
Project wizard window, enter a name for the midlet (e.g. midlet1) and click Finish
to complete creation of the new midlet.
You have now created a midlet. In our example this is called mi dl et 1. j ava (the name
chosen in step 1 of the wizard).
Adding a SATSA Card Access Method
The next step is to add SATSA compatibility to allow the midlet to communicate with
the J ava Card applet.
To add the SATSA card access method to the midlet project:
1 On Application Wizards area, double-click the SATSA Midlet Access icon. This
starts step1 of the SATSA Midlet Access wizard.
Figure 135 - SATSA Midlet Access Wizard Step 1
2 In Midlet Project, click the browse button and select the project that contains
your midlet. The currently selected midlet project is displayed by default. In Target
Midlet, select the midlet from the list.
3 Click Next to go to step 2 as shown in the following figure:
Figure 136 - SATSA Midlet Access Wizard Step 2
4 In Project Path, use the browse button to select the project that contains the
applet with which you want to communicate.
5 After selection, the boxes Applet Name, Applet AID and Instance AID display the
values used by the applet.
6 Check one or both of the boxes SATSA JCRMI Access and SATSA APDU
Access according to whether you want to access the J CRMI applet directly, with
APDU commands, or both. By default, SATSA APDU Access is already checked.
In this example, we only check SATSA JCRMI Access (as Figure 136 shows).
When SATSA JCRMI Access is checked, the corresponding Initial Reference is
automatically displayed.
The wizard adds SATSA card connection code to the midlets source code. For
example:
8 Modify the source code as shown below to call the remote J CRMI method in the
MIDlet and set a breakpoint on the line:
Figure 137 - Calling the Remote JCRMI Method
Debugging the Applet and MIDlet
You can now proceed to debug and test the SATSA access between the midlet and the
applet.
To debug the applet:
1 Load the applet project in Eclipse.
2 In Eclipse menu bar, select Run > Debug to open Debug window.
3 In the tree structure in the left pane, select the project which contains the applet to
debug. On the run-time configuration page for current project to the right, click
Choose the client application to run drop-down menu and select Midlet Test
Application as the client application to run.
Figure 138 - Debug Configuration for the JCRMI Applet Project
4 Click Customize and select the path to the MIDlet project:
Figure 139 - Specifying the MIDlet Project
5 Launch a project debug session to interactively debug the applet/midlet
combination. The WTK Mobile Simulator is launched, showing the mi dl et 1 midlet:
Figure 140 - The WTK Mobile Simulator
6 Run the midlet from the WTK mobile simulator window. The previously set
breakpoints are triggered (for example, the breakpoint set in the applets remote
Add methodsee Figure 129 on page 119). The results printed by the remote
J CRMI method (see Figure 137 on page 123) are printed to the Messages area of
the Eclipse IDE.
You can now proceed to perform on-card testing by downloading the applet to a real
card.
11
Worked Example with Servlet
and Toolkit
This chapter takes you stepbystep through a worked example of how to create an
servlet and test it in your SCWS card.
In this chapter you will learn how to:
1 Create an J avaCard Project
2 Add a servlet to the J avaCard Project.
3 Debug the servlet (using the Mobile Simulator 3G)
4 Load and install the servlet into a card using Eclipse
5 Test the servlet in the Card (Mobile Simulator 3G)
Creating the Java Card Project with the Eclipse IDE
To create the Java Card project within the Eclipse IDE:
2 Switch to Developer Suite perspective as described in Developer Suite
Perspective on page 31.
3 On the Java Card Project Management view as Figure 25 - J ava Card Project
Management View on page 32 shows, double-click Java Card Project (the top
icon on the left column).
4 The Java Card Project wizard starts and displays the first step to let you define the
settings for your project files: Name and Path Name. For the Path Name you can
Note: You can also use the J CardManager and Application Manager to load and
install an servlet in the card. For the former, refer to Appendix B - The
J CardManager. For the latter, refer to Chapter 14 - Using the Application Manager.
128 Worked Example with Servlet and Toolkit
use the browse button to the right of the box to select the path. Enter the
required information and click Next to continue.
5 The Java Card Project wizard displays the next step to let you define your
Package name and Package AID. Enter the required information and click Next to
continue.
6 The Java Card Project wizard displays the next step to let you select the type of
card for which you are creating the project. It also provides details about the
standards that will be used for your project. In Card type, select NFC with
propriety SCWS to continue.
Note: The Name must not contain any spaces.
to stop the wizard.
Worked Example with Servlet and Toolkit 129
7 The Java Card Project wizard displays the next step to let you optionally choose a
sample as the template for your new project, as below:
To use a sample template, select the Create a project from one of available
sample templates checkbox and select a template from the Available
Samples combo box.
Click Next button to continue.
On the Sample Template Information page, select dependencies projects for
the main project and click Finish to complete the wizard.
If you dont want to use a sample template, click Next button to continue.
8 The Java Card Project wizard displays the next step to let you select whether or
not you want to use an APDU trace format (ATF) personalization script for the
project. This script would be run before the applet is loaded in the card or simulator.
It could for example be used to create files that will be used by the applet. To use a
script, check the box Select a personalization script, then enter the path and
name of the script file in ATF Script. You can use the browse button to the right
of the box to select the script file. Click Next to continue.
9 The Java Card Project wizard displays the next step to let you choose which tool
you want to use for running and debugging your applet:
Mobile Simulator 3G
Mobile Simulator GSM
Midlet Test Application
Command Line
J CardManager
Simulation Chain 2G
Simulation Chain 3G
Mobile Simulator CDMA
Client Test Application (OCF/J CRMI client)
None
For this example, choose Mobile Simulator 3G and click Next.
Note: You can also include personalization scripts by customizing the generated
_.load.gxsc file using the Script Editor.
10 The Java Card Project wizard displays the next step to let you add external export
files to the project.
To add export files to the project:
a) Click .
b) When the Select the directory window opens, browse to the export file that
you want to add to the project. Repeat this operation for each file to be added.
To edit the path name of an export file:
a) Select the export file in the Step 7 Export Files window.
b) Click .
c) Edit the path name.
To remove an export file from the selected list:
a) Select the export file to be removed in the Step 7 Export Files window.
b) Click .
11 Set the class path and optionally the source path of the external library.
To set the class path:
a) Click the Class Path tab in the Step 7 Export Files window.
files.
Note: Adding external files is optional. It is necessary, however, if you are importing
an external library into your project:
Export Path entries for the conversion process
Class Path entries for compiling
Source Path entries to be able to step into the library's code when debugging
Note: You only need to set the source path if you want to debug this external library.
The class path is used when compiling the project (an external library configuration
is created).
To set the source path:
a) Click the Source Path tab in the Step 7 Export Files window.
files.
12 Click Next to continue. The Java Card Project wizard displays the final step to let
you add DAP load parameters as shown in the following figure:
Note: This step is optional. To simplify your project, you can omit DAP settings during
initial development, debugging and testing. Then if you want to use DAP to load your
application, you can add it at a later stage by downloading it with the J CardManager or
Application Manager.
To add DAP parameters:
a) Click Add. This opens the Adding a DAP control dialog box as shown in the
following figure:
Figure 146 - Adding a DAP Control
b) In Security Domain, enter the AID of a security domain or select it from the list.
c) Either choose the option button Manual, and enter the value of the DAP
parameters in DAP Value, or choose the option button Automatic and specify
the Key Definition parameters. In Key Definition field:
Select Key File option button. Check Use default key file or enter values for
Key file, Key set version (hex), and Key index in set.
Or select Key value, and then either enter the value in Key or select it from the
list.choose one of the option buttons Key file or Key value.
Click OK to return to step 8 of the Java Card Project wizard.
To edit DAP Parameters:
b) Click Modify. This opens the Modifying a DAP Control dialog box, which
apart from its title is identical to the Adding a DAP Control dialog box shown in
Figure 146 on page 133.
c) Modify the parameters and click OK to return to step 8 of the Java Card
Project wizard.
To remove DAP Parameters:
b) Click Delete.
13 Click Finish to continue. If you specified export files, you are asked if you want to
copy these files to your project workspace. Click Yes or No.
14 The step 9 of Java Card Project wizard displays.
On this page, select a set of static contents to be loaded in the SCWS card before
launching applications. This setting can be changed in the launch configuration
page later.
Follow the steps below to finish adding static content:
a) Click the button to display file explorer.
b) Browse to locate the files and folders to add. Only a single file or folder can be
added at one time.
c) Add files and folders one by one.
d) During this process, user can also select an added file or folder and click the
button to remove it.
e) After selection, click Finish to complete the wizard.
15 You project is completed now. You can see an icon followed by your project
name in Package Explorer view on the left-hand of current workbench.
16 After creation, the Project Properties Editor launches with the created projects
definition. Please refer to Project Properties Editor on page 38 for more
information.
Adding a Servlet to a Project
The Servlet wizard helps you add a servlet to your J ava Card project. In Developer
Suite V3.2, two types of servlets are available:
Servlet - a J ava Card Applet with extended SCWS features
Servlet with STK features - a USIM R5 Toolkit Applet with extended SCWS
features
Both servlet types share that same SCWS Card profile the project definition.
In Package Explorer, select the J ava Card project your just created (or any existing
J ava Card project you want to add the servlet to). On the Java Card Project
Management view (as in J ava Card Project Management View on page 32), double-
click Servlet or Servlet with STK features to start the Servlet wizard.
The Servlet Wizard
1 When you start the wizard,you should choose the servlet and toolkit (refer to the
Demo of the NFC Card )the window displays to let you define the package settings
for your servlet:
Figure 147 - The Servlet Wizard Step 1
Enter the Servlet name, Servlet AID and Servlet URL, then click Next to
continue.
2 The Servlet wizard displays the next step, as shown in Figure 148, to let you
define the applet's Instance AID and any optional Application specific
specific parameters passed in the applets i nst al l ( ) method defined in the J ava
Card specification and also in the Install command, as specified in the Global
Platform specification. For this SCWS example, the corresponding specification
versions are Java Card 2.2.1 and GlobalPlatform Card Specification, Version 2.1.1.
3 This displays step 3 of the Servlet wizard which lets you set servlet parameters.
Figure 149 - The Servlet Wizard - Step 3
In the HTTP Methods combo box, click checkboxes in list to select HTTP Methods
to use. Use Select/Deselect All button to select/deselect all options.
In the Servlet Options field, check to use Chunked encoding or leave it
deselected.
After specify the above two options, click Next to proceed.
If you are creating a Servlet, jump to 17, the last step of the wizard.
If you area creating a Servlet with STK features, go step by step to finish the
wizard.
4 The Servlet wizard displays the next step to let you select the event(s) that trigger
the applet as shown in the following figure:
Select the event(s) that you want to trigger the applet in the Toolkit events
available column and click the right arrow. The events appear in the Toolkit
events selected column. To remove any selected events, select them in the right
pane and click the left arrow. Click Next to continue.
5 The Servlet Applet wizard displays the next step to let you to define the USIM
Toolkit applet's installation parameters. Click each folder in turn to expand it and
reveal the parameters.
6 Click the +next to Menus, to display the menus as shown in the following figure:
Figure 152 - The Servlet Wizard Step 5 Menus
a) If you want to add one or more menus, click +for each new menu. You can
remove a menu by selecting it and clicking -. The Max Menu Entries
automatically displays the number of menus. For this example, click +once to
add a second menu.
b) Enter a value in hex for Max Text Length.
c) If you want to change the values for Position and/or Identifier, double-click the
value you want to change and enter the new value. By default, the wizard gives
a position of 0, which means that the operating system chooses the position for
you.
d) Click the - next to Menus to hide the menu parameters.
7 Click the +next to Priority and Timer, to display the priority level and maximum
number of timers as shown in the following figure:
Figure 153 - The SCWS Wizard Step 5 Priority and Timers
Enter the Priority Level value (01hFFh where FFh is the lowest priority) and Max
timer value (the maximum number of timers).
e) Click the - next to Priority and Timer, to hide the priority level and maximum
number of timers parameters.
8 Click the +next to Channels, to display the maximum number of channels
information as shown in the following figure:
Figure 154 - The SCWS Wizard Step 5 Channels
a) By default the maximum number of channels is set to one. If you want to
change this, check the box Maximum number of channels for this
application instance and use the spin box to change the number up to a
maximum of 7.
b) Click the - next to Channels, to hide the maximum number of channels
information.
9 Click the +next to Minimum security level, to display these parameters as shown
Figure 155 - The SCWS Wizard Step 5 Min. Security Level
These parameters specify the minimum security requirements to access the
USIM Toolkit applet in OTA (over the air) mode.
a) If you want to specify values, check the box Enable Minimum security level
parameters.
b) In Minimum security level, do one of the following:
Choose Proprietary Mechanisms, enter the MSL parameter and MSL data
Choose Minimum SPI1, and click Edit to display the Security Parameters
dialog box as shown in the following figure:
Figure 156 - The SCWS Wizard Step 5 Security Parameters
Check Ciphering to specify that all communication with the applet is to be
ciphered.
Choose one of the options in Security and one of the options in Counter.
Click OK.
c) Click the - next to Minimum security level to hide these parameters.
10 Click the + next to SIM Access parameters, to display these parameters, as
Figure 157 - The SCWS Wizard Step 5 SIM Access Parameters
11 Choose the required File System access conditions.
If you choose APDU access mechanism, click Edit and in the dialog box Set
the access rights, check the codes that the applet is considered to know, that
is the code is considered as being correctly presented. This is used to access
the files in the file system.
If you choose 3GPP access mechanism, enter the value in Access Domain
Data.
If you choose Custom Access domain, enter the values in Access Domain
Parameter and Access Domain Data.
Note: For more detailed information about the individual parameters, click Help. For
information about the Access Domain Data values, refer to 3GPP TS 23.048 for
details.
12 Click the +next to Number of services, to display these parameters as shown in
the following figure:
Figure 158 - The SCWS Wizard Step 5 Number of services
You can either use the default value or change the number by clicking the spin box.
The maximum value is 8.
13 Click the +next to Toolkit Parameters DAP, to display these parameters as
Figure 159 - The SCWS Wizard Step 5 Toolkit Parameters DAP
If you want to enter DAP information, check Compute DAP and select the
Algorithm from the list, otherwise leave this box empty.
14 Click the +next to UICC Access Application specific parameters, to display
these parameters as shown in the following figure:
Figure 160 - The SCWS Wizard Step 5 UICC Access Application paras
The UICC Access Application Specific Parameters folder lets you specify the ADF
AID (except for parameter 1), the file system access conditions and DAP
information. Use the Add and Remove buttons for each parameter that you want to
add or remove. Expand each parameters folders by clicking +.
15 Click the +next to UICC Admin Access Application specific parameters, to
display these parameters as shown in the following figure:
Figure 161 - The SCWS Wizard Step 5 UICC Admin Access Application paras
The UICC Admin Access Application Specific Parameters folder lets you specify
the ADF AID (except for parameter 1), the file system access conditions and DAP
information. Use the Add and Remove buttons for each parameters that you want
to add or remove. Expand each parameters folder by clicking +.
16 The Servlet wizard displays the next step to let you enter titles for the menus you
specified in the previous step. Click each title that you want to edit and enter the
title. When you have finished, click Next.
17 The Servlet wizard displays the last step to let you select whether or not you want
to use an ATF personalization script for the applet, for example to update files. To
use a script, check the box Select a personalization script, then enter the path
and name of the script file in ATF Script. You can use the browse button to the
right of the box to select the script file.
created applet as shown in the following figure:
Figure 162 - The Servlet Wizard Termination
Debugging the Servlet
The following section describes how you can use the Eclipse IDE to interactively debug
the servlet. This is possible because Developer Suite V3.2s Eclipse plug-in used in
conjunction with the servlet wizards automatically configure Eclipses project settings
with the card simulator as the main class of the servlet. It also launches the relevant
client application to run for the debugging session, the Mobile Simulator 3G,
J CardManager, or Simulation Chain.
Client Applications Used
The Mobile Simulator 3G.
The Static Content Explorer.
Note:
A personalization script is used to perform tasks that are only required once when the applet is
initially installed. A typical example is initializing objects (for example, key values) used by the
applet - in this case the script would contain APDU commands to be executed by the applet via its
pr ocess( ) method.
You can also include personalization scripts by customizing the _. l oad. gxsc file using the
Script Editor.
Simulation Chain 3G.
In this chapter, we use Mobile Simulator 3G and Static Content Explorer as example.
Mobile Simulator Versions
The type of Mobile Simulator you use depends on what version of Developer Suite
V3.2 you are using, the evaluation version or full version. Not all the features in the full
version are available in the evaluation version.
The following table lists the major differences between the various versions of the
Mobile Simulator (please refer to the Mobile Simulator On-Line Help for full details of
the different functions available for the version of the Mobile Simulator installed on your
computer):
Servlet Debugging Steps
The following illustration shows the user interaction steps and automated (Developer
Suite V3.2 Eclipse plug-in) steps involved in using interactive debugging for an servlet:
Figure 163 - Interactive Debugging of USIM Toolkit Applets
Note: You can change the client application in the Run or Debug window by selecting
a different application in the Choose the client application to run list (see Figure
165 - Debug Window on page 148). In fact the two windows are almost identical
apart from the Run or Debug button at the final step.
Table 8 - Mobile Simulator Capabilities
Evaluation Version Full Version
Simulated Cards Only Simulated and Real Cards
No dual slot capability Can load and simulate two cards and simulate dual slot operation
No APDU Exchange Custom APDU Exchange Feature
No pause mode Pause feature during the exchange of APDU commands between
the Mobile Simulator and a card
Note: These capabilities are valid for all the Mobile Simulators.
User IDE Applet
Card
Simulator
Client
Application
Set Breakpoint (Step 1)
Debug
(Step 2)
Start & Load the applet
Start
Operate client application (Step 3)
Send APDU
Trigger
Applet
Stop
on
Breakpoint
Notify
execution
stopped
(Step 4)
User Interaction
Automated Action
Debugging the Servlet Using the Static Content Explorer
This example describes how to debug a J ava Card project using the Static Content
Explorer as the client application.
The choice as which client application to use for debugging is defined with the project
settings.
Step 1: Setting breakpoints in the Servlets code
1 Select the project you created in the Eclipse IDE.
2 In the . j ava source file, set a breakpoint at the return line of process(APDU)
command on page 138).
To set a break point:
Double lick the gray bar to the left of current line. A bullet (which the red arrow
points to) indicates the presence of the breakpoint in the following figure:
Figure 164 - Setting Breakpoints in the Java Code
To remove a breakpoint:
Double-click the gray bar to the left of current line. The bullet disappears.
1 In Eclipse, select Project > Run > Debug to open the Debug window.
2 In the tree structure in the left pane, click the Javacard Project Launch node and
select your project to display the runtime configuration as shown in the following
figure:
Figure 165 - Debug Window
3 From the Choose client application to run dropdown menu, select Static
Content Explorer.
5 This launches the card simulator, loads the servlet and runs any personalization
scripts, and launches the Static Content Explorer.
Figure 166 - Static Content Explorer
Step 3: Operating the Client Application (Static Content Explorer)
When Static Content Explorer is running, it provides easy access to the oncard static
contents.
Use the toolbar at the top of Static Content Explorer to manage the oncard files.
The Static Content Explorer provides the following ways to administrate oncard static
contents:
Launch system web browser in Eclipse Editor view panel to display a selected
oncard file.
Add local files to card.
Add local folders to card and retain the original structure.
Create oncard folder(s) at any node of the static content tree structure.
Delete files or folders from the card.
Get oncard files or folders to a local place.
For more details on the Static Content Explorer, please refer to Static Content
Explorer on page 20.
The Static Content Explorer is
automatically launched from within
Eclipse
triggered and control is returned to the Eclipse IDE, as shown in the following
illustration:
Figure 167 - The Triggered Breakpoint in the Eclipse IDE
Debugging the Servlet Using the Mobile Simulator 3G
This example shows you how to debug a servlet using the Mobile Simulator 3G as a
client test application.
1 Follow Step 1: Setting breakpoints in the Servlets code on page 147 to complete
setting breakpoints.
2 Refer to Step 2: Debugging the project on page 147 to open the Debug window.
3 On the Debug window as Figure 165 - Debug Window on page 148 shows,
select Mobile Simulator 3G from the Choose client application to run drop
down menu. Features availability varies according to the license status of
Simulation Suite V2.0 on your PC.
5 This launches the card simulator, loads the applet and runs any personalization
scripts, and launches the Mobile Simulator 3G.
Figure 168 - Mobile Simulator 3G Waiting for User Interaction)
6 Press the power button on the Mobile simulator.
7 Enter PIN code, 1234 and press for OK.
8 Select the USAT application option and press for OK.
9 Select On Card Portal menu. This launches the browser within the Mobile
Simulator 3G and displays On Card Portal default page.
If no page has been specified for On Card Portal home, the browser displays the
HTTP 404 Error The page can not be found information.
10 A dialogue prompts to you, asking whether you like to switch to Debug perspective
or keep using current one. Click No to continue.
11 Execution stops.
12 Continue with Step 4: Notification that execution has stopped on a breakpoint on
page 150 and Step 5: Bug detection and correction on page 150.
Loading and Installing the Servlet in a Card using
Eclipse
For each project, Developer Suite V3.2 generates a load script that performs the
following commands sequentially for you:
Authenticate
Install for Load
Load
Install for Install
You can edit the script by rightclicking the _l oad. gxsc file in the Package Explorer
window, and choosing Script >Edit as shown in the following figure:
Figure 169 - Accessing the Script File in Eclipse
This action opens the Script Editor as shown in the following figure:
Figure 170 - Script Editor Showing the Load Script
To edit the parameters of a command, select the command in the Command list on
the left.
You can also use the Script Editor to add applet or card personalization scripts. To load
and install the USIM Toolkit Applet, run the load script by rightclicking the _l oad. gxsc
file in the Project window, and choose Script >Play.
Testing the Servlet in a Real Card
Now that you have loaded your Servlet in a card, you can test it as follows:
1 Stop the card simulator by clicking the button at the bottom of the screen.
2 Load the applet on the card, for example, using the GXSC deployment script.
3 In J CardManager, in Terminal, select the card reader containing your card.
4 Run the test application on the card to test the applet.
12
Worked Example with HTTP
MIDlet
This chapter presents an example of how to create a J 2ME MIDlet and configure it to
access a servlet on SCWS card.
A MIDlet is a J ava program that runs on a J ava Mobile Edition (J 2ME) virtual machine.
Overview
The major steps described in this example are:
1 Develop an servlet. Servlet is the test target and can be visited with a HTTP access
enabled midlet.
2 Create a HTTP MIDlet. This step involves creating a J 2ME MIDlet and giving it
access to a servlet via HTTP protocol. The HTTP midlet is then used as a midlet
test application in servlet debugging.
3 Debug the servlet and MIDlet.
Creating the Servlet
General steps of creating a new Java Card Project:
1 On the Java Card Project Management view, double-click Java Card Project.
2 At Step 1 of the wizard, specify project name and project file location.
3 At Step 3 of the wizard, choose SCWS Card from the Card type drop down list.
4 At Step 5 of the wizard, choose Midlet Test Application from the list of available
Tools.
Quickly add a servlet to the Java Card Project
1 Select the Java Card Project we just created.
1 Double-click Servlet on the Application Wizards area. This starts Servlet creation
wizard.
Note: Before starting this example, make sure that you have already installed Eclipse
Enterprise or Developer editions, and the Wireless Toolkit (WTK) 2.3 or higher. For
details on how to install WTK 2.3, refer to Importing WTK Devices Into Eclipse on
page 16.
156 Worked Example with HTTP MIDlet
2 Follow the instructions to finish the wizard and generate skeleton code.
Creating the HTTP MIDlet
Follow steps below to create a HTTP MIDlet:
1 In Eclipses Package explorer, select the J ava Card Project we just created.
2 The Applications Wizards area shifts to a J ava Card Project particular display.
3 On Application Wizards area, we can find shortcuts to Servlet and HTTP MIDlet
creation wizard.
4 Double-click the HTTP Midlet icon to starts step 1 of the HTTP Midlet Access
Wizard.
Figure 171 - HTTP Midlet Access Wizard- Step 1
5 Click the button to select a J2ME MIDlet project from all existing projects.
6 If no MIDlet project exists, click the button to create a new MIDlet project.
On the New J2ME Project window displayed, enter a name for the new MIDlet
project, e.g. httpmidlet. Click Finish to complete the new MIDlet project creation.
This adds the new MIDlet projects directory in Midlet Project text field and
enables the button next to Target Midlet drop-down list.
7 In the Target Midlet drop-down list, select a MIDlet to use. The Target Midlet list
contains all midlet under the selected MIDlet project.
Tip: Chapter 11 - Worked Example with Servlet and Toolkit contains detailed
information on how to create a J ava Card Project as well as to add a Servlet.
If you still feel unclear about J ava Card Project and servlet creation, you are
recommended to write that chapter first.
Worked Example with HTTP MIDlet 157
8 You can also click button to create a new MIDlet. This displays the J2ME
Midlet window. Enter a name for the new MIDlet, e.g. httpmidlet. Click Finish to
complete creation of the new MIDlet. The new MIDlet is automatically added into
Target Midlet list.
9 Back on the Http Midlet Access Wizard step 1, after you specify a MIDlet to use,
click Next to proceed.
10 The step 2 of HTTP Midlet Access Wizard is displayed, as the figures shows
below:
Figure 172 - HTTP Midlet Access Wizard - Step 2
11 In Project Path field, the J ava Card Project and servlet we created before are
selected by default.
12 HTTP Host is set to http://127.0.0.1:3516 by default.
13 Click Finish to complete the wizard and generate skeleton code.
Debugging the Applet and MIDlet
You can now proceed to debug and test the HTTP Midlet access between the MIDlet
and the servlet.
To debug the servlet:
1 Load the servlet project in Eclipse.
2 In Eclipse menu bar, select Run > Debug to open Debug window.
3 From the left pane, select the launch profile for this servlet project. It is usually
under the JavaCard Project Launch folder.
158 Worked Example with HTTP MIDlet
4 On the run-time configuration page to the right, click Choose the client
application to run drop-down menu and select Midlet Test Application.
Figure 173 - Debug Configuration for the JCRMI Applet Project
5 Click Customize and specify the path of the MIDlet project.
Figure 174 - Specifying the MIDlet Project
6 Launch a project debug session to interactively debug the servlet/midlet
combination. The WTK Mobile Simulator is launched, showing execution of the
midlet.
13
Creating and Using Libraries
This chapter provides details of how to create and use libraries in Developer Suite
V3.2. It covers:
How to create libraries. This shows you how to initially create a library.
How to use a library. This shows you how to use the library in an applet.
How to use a gxsc script file. This shows you how to modify the automatically
generated project_Load. gxsc script file so that it can be used to load the library
onto the card before the applet.
To illustrate these topics, working examples are provided that make use of some of the
samples included with Developer Suite V3.2, the SMSLibrary package and the
SIMAPIExample applet.
How to Create Libraries
The SMSLibrary example illustrates how to create a library of utilities that can be used
in applets. The SMSLibrary project does not define an applet, but simply a package
that can be imported into one or more applets.
The SMSLibrary package contains a set of methods used to build Send Short
Message proactive commands. In the Developer Suite V3.2 sample projects, this
library is used by the SIMAPIExample and STKCryptoExample applets.
To create a library project:
1 In Eclipse, run the J ava Card Project wizard, as described in Creating the J ava
Card Project with the Eclipse IDE on page 77.
2 After creation of the project, double-click Library icon in Java Card Project
Management view, as shown in Figure 25 on page 32, this add a MyClass.java
file to your project. Once created, add any methods that you want to the library
project.
How to Use Libraries
For a J ava Card project to use a library, it needs to know the location of the librarys
export files and class files.
To specify the location of a library in a Java Card project:
1 In Eclipse, run the J ava Card Project wizard, as described in Creating the J ava
Card Project with the Eclipse IDE on page 77.
160 Creating and Using Libraries
2 In step 6, as shown in Figure 92 - J ava Card Project Creation Wizard - Step 7 on
page 81, add the librarys export files. Export files are necessary to convert the
project for target cards. Click and select the root directory of the libraries
export files. Typically, this directory is the Oncard directory of the library project.
3 Click the Class Path tab and add the path for the directory containing the librarys
class files. Typically this directory is the Classes directory of the library project.
4 Click the Source Path tab and add the path to the librarys source files. This is
necessary if you want to step into the library code when you debug your project.
5 At the end of the wizard you are asked Do you want to copy the selected export
files into your project workspace. Click Yes if you want to copy the files locally to
your project. This is recommended if the imported libraries are unlikely to be
modified, that is, the export and class files are not likely to change.
6 When you have finished with the wizards, modify the code in your project to access
the library.
How to Modify the Gxsc Script File
The elements required to load and test the library can be included automatically in the
download by means of a gxsc script file. When you initially create a Developer Suite
V3.2 project, a basic GXSC script file is created automatically.
To view the generated gxsc script file:
1 In Package Explorer window, right-click the projectname_l oad. gxsc script file
and choose Script >Edit in the contextual menu.
2 The Script Editor window is opened displaying the commands included in the gxsc
script (Load Context, Authenticate, Install for Load, Load and Install for Install
when the project is initially generated).
When using libraries in an applet, for practical reasons it is recommended that you edit
this script file in order to load the library package you have created. Use the Script
Editor to add the Install for Load, and Load commands, necessary to load the library
and replay the personalization script. The SIMAPIExample_load.gxsc file included in
the SIMAPIExample project has been modified as follows:
Install for Load and Load commands have been added to load the SMSLibrary
package before the applet.
The Select and ATF Script Player commands have been added to select the GSM
application and personalize the EFadn file after downloading the applet.
14
Using the Application
Manager
This chapter introduces the Application Manager tool supplied with Developer Suite
V3.2. The Application Manager is used to download packages onto real cards and
install and delete applets or applet instances.
Introduction
The main features of the Application Manager are that it:
Provides an easy to use application repository in which to store information about
the applications that are ready to be loaded onto cards. You can create, copy,
import, export, and delete applications and modify their properties.
Supports downloading applications to real cards.
Supports two loading modes:
Over-the-air (OTA) mode, which uses the 3GPP TS 23.048 Short Message
Service (SMS) facility to remotely download applications. The Application
Manager generates the appropriate envelope commands and parameters and
sends the application to the target card encapsulated within one or more SMS
point-to-point data download messages.
Input/Output (I/O) mode, with which the Application Manager sends
GlobalPlatform commands directly to the Card Manager applet on the target
card.
Uses card profiles to configure all the parameters necessary to send applications to
specific card types in I/O or OTA mode. Each card profile is based on a template. A
preconfigured and fully tested template is supplied for each of the sample card
types delivered with the product you have purchased, for example, the GemXplore
3G V3. You can create, copy, and delete card profiles and modify their properties
as necessary.
Provides flexibility in terms of the tasks you can perform. For example, you can
load packages that contain only J ava library classes referenced by other applets,
load packages and install several different applets from the package, or create
multiple instances of an applet that has already been loaded onto the card. You can
also choose to perform separate load and install operations. For example, you load
a package initially, then install the applets it contains later.
Allows you to debug the load and install process by means of an easy to
understand trace window.
162 Using the Application Manager
Overview of Defining and Running an Application
To define and run an application:
1 Start the Application Manager.
2 Configure the terminal profile settings.
3 Select the terminal containing the target card.
4 Create, configure, or select the application to load into the target.
5 Select the loading mode.
6 Create, configure, or select a suitable target card profile for the card.
7 Select the action to perform on the application.
8 Execute the selected action.
9 Optionally, analyze the results in the Trace panel.
For detailed instructions on performing these tasks, start the Application Manager then
click the Help button in the top right-hand corner of the Application Manager
window that appears.
Starting the Application Manager
To start the Application Manager:
1 Start Eclipse.
2 From within Eclipse, choose the Developer Suite menu and select Application
Manager 2G or Application Manager 3G as appropriate.
The Application Manager Window
When first started, the main window of the Application Manager is displayed, as shown
in Figure 175:
Figure 175 - The Application Manager Main Window
Toolbar
Available Terminals
Current operating mode Online Help
Actions to perform
Carry out the
selected action
Card profiles
Trace window
Application repository
15
The Script Editor
What is a Script?
A script is a file that contains a list of commands that are executed in sequence.
Scripts can either be created manually, as described in this chapter, or generated
automatically using the J CardManagers trace recorder (see Script Files on
page 186).
The Script Editor is a tool that enables you to create and edit configuration files and
scripts. You can use it to add, remove or rename the commands in the list and change
the order in which the commands are executed. You can also use the Script Editor to
set the parameters of individual commands in the sequence.
Starting the Script Editor
You can start the script editor from within either J CardManager or Eclipse.
To start the Script Editor from Eclipse:
1 Right click a .gxsc script file in the Package Explorer view.
2 Choose Script >Edit or Script >Play as shown in Figure 111 - Accessing the
Script File in Eclipse on page 97.
To start the script editor from JCardManager:
From the Tools menu, choose Script Editor.
164 The Script Editor
The Script Editor Interface
An example of the interface is shown in the following figure:
Figure 176 - Script Editor Window
For detailed help about how to use the Script Editor, click the Script Editor Help button
. This section provides an outline of the main operations that you can perform.
For detailed help about a particular command, select the command in the command list
and click Help at the bottom right of the window.
Use the Card list to select the type of card on which the script is to be run.
The Quick Access Tool Bar at the top left of the screen is mainly for operations on a
script file, opening, creating, saving and so on.
The Command List contains the list of commands that are to be executed in the
current script, in the order that they appear.
The Command Management Controls are used to move, sort or delete commands
from the Command List.
To add a command to the list:
1 Click the button in the Quick Access Tool Bar. This opens the Add/Remove
Commands window as shown in the following figure:
Figure 177 - Script Editor The Add/Remove Commands Window
Command Management Controls
Command Parameters Area
Script Editor Help
Script Editor Help for Commands
Quick Access Tool Bar Card List
The Script Editor 165
2 The Script Commands List on the right displays the commands currently in the
script. Use the arrow buttons to add and remove commands.
3 Click OK to exit the Add/Remove Commands window or Cancel if you want to
exit without saving your changes.
To change the order of commands in the Command List:
In the Command List, select the command that you want to move and use the up or
down arrow buttons in the Command Management Controls (see Figure 176 on
page 164). You can also arrange the commands in alphabetical order by clicking the
button.
To rename a command in the Command List:
1 In the Command List, select the command that you want to rename.
2 Click the button.
3 In the Name Definition window, enter the new name and click OK.
To specify the parameters of commands in the Command List:
1 In the Command List, select the command whose parameters you want to specify.
This action displays the parameters for the command in the Command
Parameters Area.
2 Specify the values for the parameters.
To save your changes to the Command List:
Click the Save Script File button in either the Quick Access Tool Bar or the
Command Management Controls.
16
The File System Editor
What is the File System Editor?
This tool enables you to view the file structure in a card or a card simulator and the
properties and access conditions for any file. In addition it can be used to perform
certain commands on files.
You can launch the File System editor either from within the J CardManager, or from
the Developer Suite menu in Eclipse.
To start the File System Editor from JCardManager:
1 Select the card simulator or reader in the Terminal list in the toolbar.
2 Select the card type in the tree structure in the left pane.
3 Click the File System Editor button in the toolbar.
To start the File System Editor from Eclipse:
1 Choose File System Editor from the Developer Suite menu.
2 In the Select the Target window that appears, choose the type of card you are
using and click Select:
Figure 178 - The Select the Target Window
168 The File System Editor
The File System Editor Interface
The File System Editor window is shown in the following figure:
Figure 179 - File System Editor
Depending on the Scan Model you select, the File System Editor operates in 2G or 3G
mode. The current mode is displayed to the right of the toolbar.
Select a file in left pane to display the following properties in the right pane:
Type, identifier and very brief description
Properties
Access type
PINs and their statuses, that is, whether or not they have been successfully
presented. This last feature applies to the MF and DFs only.
The File System Editor 169
Contextual Commands
You can perform certain commands on a file in the file system editor. The commands
available depend on the type of file. The following table describes the commands
available for each file type:
To perform a contextual command:
1 Choose the file in the left pane on which you want to perform the command.
2 Rightclick and select the command from the contextual menu.
3 For Create, PIN commands and Update commands, complete the dialog box for
the command and click the button with the command name, for example Update
Binary.
4 Click Close.
The pane at the bottom of the File System Editor displays the APDU code for the
command.
For details about individual commands, refer to the document ETSI TS 102 221 V7.0.0
(2004-12); Technical Specification; Smart cards; UICC-Terminal interface; Physical
and logical characteristics (Release 7), available at www.etsi.org.
Table 9 - Contextual Commands
Command Description File type
Scan Updates the information displayed in the right
pane
MF, DF,
ADF (3G only)
Select Makes the selected file the current file MF, DF, EF,
ADF (3G only)
File Access
Management:
Verify PIN
Change PIN
Enable PIN
Disable PIN
Unblock PIN
Performs the PIN command on all the files in
the card.
MF, DF, EF,
ADF (3G only)
Create Creates an EF or DF under the chosen file.
Note: This command is only available for
R6-compliant card profiles (USIM R6 and
R-UIM).
Note: This command is not available for the
default scan model: you must create a copy of
a default scan model before you are able to
create files.
MF, DF,
ADF (3G only)
Delete Deletes the chosen file.
Note: This command is only available for
R6-compliant card profiles (USIM R6 and
R-UIM.
Note: This command is not available for the
default scan model: you must create a copy of
a default scan model before you are able to
delete files.
DF, EF,
ADF (3G only)
Update Record/Binary Updates a record or data in a data file EF
17
The Key File Editor
The Key File Editor tool can be used to manage key profiles. It can be accessed either
from Eclipse or from the J CardManager.
To start the key file editor from Eclipse:
Choose Key File Editor from the Developer Suite menu.
To start the key file editor from JCardManager:
Choose Key File Editor from the Tools menu.
When opened, the Key File Editor appears as shown in the following figure:
Figure 180 - Key File Editor
Keys are stored in key profiles. A key profile comprises a mother key and one or more
key sets although it is possible to have a profile with just a mother key or with just one
or more key sets.
A key set normally contains three keys, but you can add or remove keys.
Each function is performed by clicking one of the icons on the toolbar. For information
about each function, click the online help button .
To find out which version of the Key File Editor you are using, click .
A
Managing OTA Profiles
This appendix describes how to configure OTA profiles in the OTA Profile Manager. To
start the OTA Profile Manager, select a card profile in the Target area of the
Application Manager and click .
The OTA Profile Manager
The main window of the OTA Profile Manager is shown in Figure 181:
Figure 181 - The OTA Profile Manager Window
This window allows you to modify the selected OTA profile, in this example the
GemXplore 3G V3.0 displayed on the windows title bar.
The card template upon which the profile is based is displayed in the top right-hand
corner of the window.
An OTA profiles parameters are spread across three property sheets:
SMS. These parameters select optional features of SMS messaging, such as
whether to implement concatenation, use a reply path, or request a status report.
These options are described in detail in SMS Options on page 174.
Secured Message. These parameters determine which optional values of the
3GPP TS 23.048 specification to use when formatting command and response
packets.
These options are described in detail in Secured Message Options on page 176.
174 Managing OTA Profiles
Expert. These parameters are intended for use by expert users only, and concern
the format of an SMS messages concatenation header, command packet and
response packet headers.
These parameters are described in Expert Options on page 180.
Optionally, click Apply to save the current values of parameters on the selected
property sheet.
Click OK to save the current values of all parameters on all property sheets and close
the OTA parameters window.
SMS Options
The SMS property sheet contains options relating to the Short Message Service
(SMS). The default values displayed are read from the template upon which this card
profile is based.
You can specify values for the following parameters:
Originating Address
It is usual for the receiving entity to implement a number of security mechanisms, which
may include a check that the message was sent by an authorized application provider.
This is done by checking the originating address (TP-OA field) included in the
messages OTA header.
To modify the default originating address, click Edit to display the Originating
Address Editor window:
Figure 182 - The Originating Address Editor Window
Specify the Type of Number (TON), Numbering Plan Identification (NPI), and
Address components of the originating address:
TON. Indicates the format of a number. The most commonly used settings are:
National number. A sequence of digits, usually beginning with a 0.
International number. In this format, the number starts with a + followed by
the country code, even for national calls. This format is recommended for
roaming and international calls, and highly recommended for stored numbers
and call forwarding.
NPI. Used to ensure compatibility between numbering plans (for example, for a
private network) in which the digit sequences may have a different meaning and
Note: The originating address is the network address (MSISDN) of the messages
originator, that is, the sending entity, not that of the SMSC that forwards the message
to the SIM card.
Note: The digits in parentheses following the options refer to the normative values of
the TON/NPI byte, bits 4 to 6. For example, 001 indicates use of the International
TON.
Managing OTA Profiles 175
structure than in the networks default numbering plan. The most commonly used
setting is ISDN/Telephone Number Plan.
Address. A string specifying the number of an entity (service center, mobile
station) on the network.
Reply Path (RP)
Specifies whether the receiving entity is requested to reply to the SMS message:
True. A reply is to be sent. The value in the Originating Address field is used to
route the reply.
False. No reply is to be sent.
Status Report Indication (SRI)
Indicates whether the receiving entity is requested to send a status report:
True. A status report is to be generated and sent.
False. No status report is to be sent.
The SRI is coded as the TP-SRI field of the SMS DELIVER TPDU defined by the
3GPP 23.040 standard.
Enable 23.040 Concatenation
Indicates whether concatenation is to be used.
Concatenation, described in the 3GPP 23.040 specification, provides a mechanism for
transmitting command packets containing large blocks of data by breaking the data up
into segments and transmitting each segment as a separate SMS message. The
segments are then reassembled by the receiving entity (provided that it supports
concatenation: not all SIM cards in the field today support concatenation).
Without concatenation, a single SMS message can only contain up to 160 characters
of text (where each character is 7 bits according to the 7-bit default alphabet), or up to
140 characters of 8-bit binary data.
Specify either:
True. This message implements concatenation; the receiving entity should expect
other messages in the sequence.
False. This message does not implement concatenation.
If you choose to implement concatenation, refer to the Concatenation property sheet
to set optional values for concatenation; see Expert Options on page 180.
Text and Data Format
Use the Text and Data property sheets to indicate to the receiving entity the method to
use to load the text and data contained in the message onto the SIM card:
PID
Select the Protocol Identifier (PID) to use:
Update Record. Download the text or data using an Update Record SIM Toolkit
command to update the EF
SMS
elementary file in the SIM cards GSM file system.
Envelope. Download the text or data by sending an SMS Point-To-Point Data
Download Envelope command to the SIM card.
DCS
Select the Data Coding Scheme (DCS) that the receiving entity is to use to encode the
text or data. The choice affects the maximum number of characters or bytes that a
single SMS message can contain:
8-bit. Unpacked format (eight-bit data), bit 7 is set to 0. Unused bytes are set to
FFh. A Text message string may contain up to 210 characters. A Data message
may contain up to 210 bytes.
7-bit. Packed format, the default seven-bit alphabet is used, packed into bytes. A
Text message string may contain up to 240 characters. A Data message may
contain up to 210 bytes.
UCS-2. In UCS-2 format, the UCS-2 alphabet is used. In a Text message, each
character uses two bytes and the string may contain up to 105 characters. A Data
message may contain 210 bytes.
Custom. The text or data in the message is in a custom format understood by the
receiving entity.
Secured Message Options
These parameters determine the 3GPP 23.048 formatting of the messages command
packet. The parameters are further divided into three sub-property sheets: click on the
SPI, KIc or KID tabs on the right of the window to access the other property pages.
SPI
The Secured Packet Information (SPI) is a 2-byte field of the messages command
packet indicating:
In byte 1, the security mechanisms to implement in order to secure the message.
In byte 2, the settings to build the response packet returned by the receiving entity.
Ciphering
Whether the contents of the message are ciphered:
True. The contents are ciphered
False. The contents are in clear.
If ciphering is to be implemented, use the options on the KIc property sheet to configure
the ciphering mechanism. Refer to KIc on page 178.
Security
Indicates which security mechanism is to be implemented:
No RC, CC, or DS. No security mechanism is used: the text or data to be sent are
written in clear into the body of the message.
Redundancy check. A redundancy check (RC) is the simplest to implement and
least secure of the security mechanisms outlined in the 3GPP 23.048 specification.
Note: Regardless of the method chosen, the capabilities of the mobile equipment
determine which method is actually used. For example, the SMS Point-To-Point Data
Download Envelope command is only supported by Phase 2+mobile equipment.
Phase 2 mobile equipment systematically loads OTA messages using the Update
Record command, even if the Envelope option is selected.
It can only really be used to check that the message was correctly received by the
receiving entity. If you select this option:
a) Click Apply.
a) Select the KID property sheet.
b) In the RC Security area of the window, select the Algorithm to use to
calculate the redundancy checksum.
c) If you select the DES or Triple DES algorithm, you must enter the Key to use.
The receiving entity calculates a checksum based on the contents of the message
and compares it with the checksum value sent in the message. If the two match,
the receiving entity goes on to process the contents of the message. If a
discrepancy is detected, the message is rejected. If status reporting is switched on,
an error is returned to the sending entity.
Cryptographic Checksum. A cryptographic checksum is a string of bits derived
from a secret key, part or all of the messages contents, and possibly additional
information (for example, part of the command header). This secret key must be
known to both the sending entity and the receiving entity. If you select this option:
a) Click Apply.
b) Select the KID property sheet
c) Specify the algorithm and key to use in the CC Security area of the window, as
described in KID on page 179.
The receiving entity authenticates the message by comparing the content of the CC
field extracted from the command packet with a value computed internally by the
SIM card using the same secret key as the sender.
Digital Signature. A digital signature (DS) enables the messages recipient to
verify the authenticity of the informations origin, and also verify that the information
is intact. If you choose this option, you must:
a) Click Apply.
b) Select the KID property sheet.
c) Specify the algorithm and key to use in the DS Security area of the window, as
described in KID on page 179.
Counter
A synchronization counter is used to prevent replay attacks and to re-synchronize the
OTA platform and SIM card when OTA message transmission fails for whatever
reason. Synchronization consists in comparing two values; one stored in the SMS
messages command packet, the second stored on the SIM card itself.
The following options are available:
No counter available. Do not use a synchronization counter.
Counter available but no replay or sequence checking. Include a
synchronization counter in the message, but the receiving entity does not perform
any checks on its value.
Process if counter is higher than RE. Process the message if the value of the
synchronization counter in the message is greater than the current value stored on
the SIM card.
Process if counter is one higher than RE. Process the message if the value of
the synchronization counter in the message is exactly one more than the current
value stored on the SIM card.
Refer to the 3GPP 23.048 specification for details.
If you choose to use a synchronization counter, enter the initial value to use in the
Counter value field.
The maximum possible value of synchronization counter and the method used to
format the synchronization counter can be set on the Expert property sheet. See
Expert Options on page 180.
The receiving entity retrieves the value of the synchronization counter from the
message and compares it to the value of the synchronization counter in the SIM card.
The message is considered to be valid if the counters value is greater than the value
stored in the SIM card, in which case the local counter is incremented.
Counter Value
Enter the initial value of synchronization counter to use. The default value is zero (0).
Click the Refresh button to read the most recently saved value of synchronization
counter from the card profile file. For example, if you replace the current value 0 with
999 and click Refresh, the value 0 reappears.
Proof of Receipt
The values you specify for the options in this area of the window are written into the
second SPI byte of the messages command header.
Proceed as follows:
1 To specify that no Proof of Receipt (PoR) is required, select No PoR reply to the
Sending Entity (SE).
2 To specify that a PoR is always sent, select PoR required to be sent to the SE.
3 To specify that a PoR is only to be sent when an error occurs, select PoR required
only when an error has occurred.
If you request that a PoR is sent, you can choose the security mechanism to apply to it:
No security to be applied
Apply a cryptographic check (CC) check only
Apply a digital signature (DS) check
You can optionally choose whether the PoR is to be ciphered or not.
Finally, you can specify whether the PoR is to be sent using an SMS-DELIVER-
REPORT TPDU or an SMS-SUBMIT TPDU.
These options are explained in greater detail in the 3GPP 23.040 specification.
KIc
This property sheet is used to determine the contents of the key certificate (KIc) byte in
the command header.
The values on this property sheet are only used if ciphering of the message has been
requested. Check the value of the Ciphering field on the SPI property sheet, described
in SPI on page 176.
The window is divided into two parts:
In the top half of the window, specify the ciphering values to use when data
encryption is being used. See Configuring Data Encryption on page 179 below.
In the bottom half of the window, specify the settings for the ciphering key: see
Ciphering Key.
Note: Depending on the target chosen, not all of the above options may be available.
Ciphering Key
Select the algorithm type and mode to use to cipher the messages contents.
Algorithm. The following algorithms are available:
Value set in template. The value is read from the template upon which this profile
is based.
DES/CBC/None. DES in CBC mode, with no padding
DES/ECB/None. DES in ECB mode, with no padding
TripleDES/CBC/None. Triple DES in outer-CBC mode, with no padding
TripleDES/ECB/None. Triple DES in ECB mode, with no padding.
Key. Type the key value to use. The key should be:
8 bytes (56 bits) long if the algorithm selected is DES/CBC/None or DES/ECB/
None.
8 bytes (56 bits), 16 bytes (112 bits), or 24 bytes (168 bits) long if the algorithm
selected is Triple DES/CBC/None or Triple DES/ECB/None.
KID
This property sheet is used to determine the contents of the key identifier (KID) byte in
the command header. The window is divided into two parts:
In the top half of the window, specify the ciphering values to use when data
encryption is being used. See Configuring Data Encryption on page 179 below.
In the bottom half of the window, specify the RC, CC, or DS algorithm and key to
use: see Configuring CC, RC, or DS Security Settings on page 180.
Configuring Data Encryption
Algorithm Type
First, choose the algorithm type:
An algorithm known to both the sending and receiving entity.
A Data Encryption Standard (DES) algorithm.
A proprietary algorithm.
Algorithm
Choose the encryption algorithm. The OTA Profile Manager supports the following
encryption algorithms:
DES. DES uses a binary number called a key to encrypt and decrypt sensitive data.
In the OTA Profile Manager, you simply type in the entire 192-bit (24 character) key
rather than entering each of the three keys individually.
Triple DES, with two or three keys. Triple DES is simply another mode of DES
operation. The procedure for encryption is exactly the same as regular DES, but it
is repeated three times (hence the name triple DES). The data is encrypted with the
first key, decrypted with the second key, and finally encrypted again with the third
key, as shown in Figure 183below:
Figure 183 - Triple DES Encryption
In the 3-key variant, the three keys are all different, whereas in the two-key version,
Key 3 is the same as Key 1. In both cases, the chaining features of CBC mode are
also employed.
Key Set
Choose the key set to use from the key set file. Each key set must contain either 16
characters, that is, 112 bits (when using two 56-bit keys), or 24 characters, that is, 192
bits (when using three 56-bit keys).
Configuring CC, RC, or DS Security Settings
The items in the bottom half of the property sheet depend on the value of the Security
field on the SPI property sheet (see Security on page 176):
If Security is set to Cryptographic Checksum, specify a cryptographic checksum
in the CC Security area:
a) Select the Algorithm to use: XOR4, CRC32, XOR8, DES or Triple DES.
b) If you select the DES or Triple DES algorithms, specify the Key to use; 8 bytes
(56 bits) for DES, 16 bytes (112 bits) or 24 bytes (168 bits) for Triple DES.
If Security is set to the value Digital Signature, specify the digital signature to use
in the DS Security area of the window:
a) Choose the algorithm: XOR8, DES, or Triple DES.
b) If you select the DES or Triple DES algorithms, specify the Key to use; 8 bytes
(56 bits) for DES, 16 bytes (112 bits) or 24 bytes (168 bits) for Triple DES.
If Security is set to the value Redundancy check, specify the algorithm and key to
use in the RC Security area:
a) Select the Algorithm to use, XOR4 or CRC32.
Expert Options
The options on the Expert property sheet are typically parameters that are optional or
open to different interpretations in the 3GPP 23.040 or 3GPP 23.048 specifications.
Specific values may therefore be necessary to create OTA profiles compatible with
different manufacturers interoperable cards.
DES Decryption
DES Encryption
DES Encryption
Ciphered text
Plain text
Key 1
Key 2
Key 3
The parameters are divided into three sub-property sheets: click on the
Concatenation, Command Packet Header or Response Packet Header tabs to the
right of the window to access the other property pages.
Concatenation
When concatenation is being used, the first concatenated message contains three
elements:
The command header
A concatenation header.
The first part of the secured data, if there is room for it.
Subsequent messages contain only the concatenation header and secured data.
The options on this property sheet set the format of these components.
Concatenation Header Size (IEIa)
The length of Information Element Identifier A field to use when formatting messages.
Possible values are:
Value set in template, to use the value in the template upon which this card profile
is based.
One byte (0x00), if the concatenation header reference number size is one byte.
Two bytes (0x08), if the concatenation header reference number size is two bytes.
TPUD Max Length
Defines the maximum possible length of message (TP-User Data field length) that can
be generated by the OTA platforms formatting library (UDH plus command header
plus secured data). For point-to-point SMS messages, this value must be 140 (bytes).
However, you can specify a different value for the maximum length if necessary.
Command Packet Header
CHI expected length
Specify the maximum length of the Command Header Identifier (CHI) field. This field is
always null (0 bytes) in SMS point-to-point messages.
CHI value
Defines the expected length of the CHI value in an unformatting process. The most
suitable value is 0.
CP synchronization counter maximum
Specify the largest valid value of synchronization counter within a command packet
that is supported by the target card.
CP synchronization counter formatter
The default value codes the synchronization counter as a 5-byte unsigned value. For
example, the synchronization counter 703696 is coded as 0Ah 0Bh 0Ch 0Dh 00h
(hexadecimal). To use a different format, select Value set in template to use the
format specified in the template upon which this card profile is based.
Fields included in the RC/CC/DC calculation
For generalized command packets, the RC/CC/DS field is computed from the SPI, KIc,
KID, TAR, CNTR, and PCNTR fields, together with additional data and padding.
However, part or all of the CPL and CHL fields can also be used in this computation.
Therefore, to fully comply with the 3GPP 23.048 specification, the OTA Profile
Manager allows you to choose which fields are included in the RC/CC/DS computation.
The default formatting library provides two alternatives:
Extract data from the SPI, KIc, KID, TAR, CNTR, and PCNTR fields, together with
additional data and padding from the input stream.
Extract the data from the CPL, CHL, SPI, KIc, KID, TAR, CNTR, and PCNTR fields,
together with additional data and padding from the input stream.
To use a different format, select Value set in template to use the format specified in
the template upon which this card profile is based.
Data to cipher padder
Determines how to pad data that is to be ciphered. The default formatting library
always pads data with zeros.
Response Packet Header
RHI expected length
Specify the maximum length of the Response Header Identifier (RHI) field. The value
0 is the default.
RHI value
Defines the expected length of the RHI value in an unformatting process. The most
suitable value is 0.
RP synchronization counter maximum
Specify the largest valid value of synchronization counter that is supported by the
target card within a response packet.
RP synchronization counter formatter
The default value codes the synchronization counter as a 5-byte unsigned value. For
example, the synchronization counter 703696 is coded as 0Ah 0Bh 0Ch 0Dh 00h
(hexadecimal). To use a different format, select Value set in template to use the
format specified in the template upon which this card profile is based.
Fields included in the RC/CC/DS calculation
For generalized response packets, the RC/CC/DS field is computed from the TAR,
CNTR, and PCNTR, and status fields, together with additional data and padding.
However, part or all of the RPL, RHL, UDHL and RPI UDH fields can also be used in
this computation. Therefore, to fully comply with the 3GPP 23.048 specification, the
OTA Profile Manager allows you to choose which fields are included in the RC/CC/DS
computation.
There are two alternatives:
Extract data from the TAR, CNTR, and PCNTR fields, together with additional data
and padding from the input stream.
Extract data from the RPL, RHL, TAR, CNTR, and PCNTR fields, together with
additional data and padding from the input stream.
Extract data from the UDHL, RPI UDH, RPL, RHL, TAR, CNTR, and PCNTR fields,
together with additional data and padding from the input stream.
B
The JCardManager
The J CardManager is a powerful tool that provides the following functions:
Perform individual command APDUs on a card or a card simulator
Record and replay script files (sequence of commands)
Display the results of APDU exchanges with the card or simulator and save them in
a trace file
A file system editor enabling you to view the files in a card and their properties. This
is described separately in Chapter 16 - The File System Editor.
J CardManager can be started in one of two ways:
In Eclipse, from the Developer Suite menu, choose JCardManager.
From the Start button, choose All Programs > Gemalto > Wireless Solutions >
JCardManager.
Both these actions open the initial JCardManager window as shown in the following
figure:
Figure 184 - The Initial JCardManager Window
For detailed help about J CardManager, click the JCardManager Help button . This
section provides an outline of the main operations that you will want to perform.
Tool bar
Current Trace
186 The J CardManager
For detailed help about a particular command, select the command in the command list
and click Help at the bottom right of the window.
To execute a command:
1 Expand the tree structure in the left pane and select the command. The parameters
for the command display in the right pane.
2 Complete the parameters in the right pane (these could include option buttons, text
fields, check boxes and so on and vary according to the command chosen).
3 Click Go.
Logical Channels
To select a logical channel, click the corresponding button in the multichannel bar.
APDUs will then be sent to this logical channel.
Script Files
Script files contain a sequence of command APDUs. You can make your own script file
by recording a sequence of commands and play back the script file.
There are two main types of script file:
.atf files, which store the data values directly.
.xml and .gxsc, which store the parameters and rebuild the APDUs, for example
they recalculate random numbers for you.
In J CardManager you can use the record and play tools described below to record and
play both types of file. However, J CardManager also contains specific script players,
the ATF Script player and the XML Script player (which can also play .gxsc scripts).
To record a script file:
1 Start recording by clicking in the toolbar or by choosing Script >Record or
pressing the <F5>key.
2 In the Record Script. Output File Selection window, browse to the directory
where you want to save the script file and enter the file name (with a .gxsc or .xml
suffix).
3 Click Save.
4 Perform the sequence of commands that you want to record in your script.
5 After the last command, stop recording by clicking in the toolbar or by choosing
Script >Stop or pressing the <F10>key.
To play a script file (general):
1 Start playing by clicking in the toolbar or by choosing Script >Play or pressing
F12.
2 In the Play Script. File Selection window, browse to the directory that contains the
script file you want to play and select the file.
Note: During recording you can pause recording by pressing or by choosing
Script >Hold or pressing F9. This stops commands being written to the script file. To
continue writing commands to the script file press or choose Script >Record or
pressing F5 .
The J CardManager 187
3 Click Open.
To play an .atf script using the ATF Script Player:
1 Select ATF Script Player in the left pane.
2 In ATF file, either select the .atf file from the list (the list stores all the previously
selected .atf files) or navigate to an .atf file.
3 Use the ATF Script Command buttons to:
Rename a command
Change the order of the commands in the list
Delete one or more commands from the list
Save the .atf file under the same or a different name.
4 Click Go to play the script. The results of the script execution are displayed in the
Message area of the window.
To play an .xml or .gxsc script using the XML Script Player:
1 Expand the folder in the left pane corresponding to your type of card, for example
USim Card R5, and select XML Script Player.
2 In GXSC(XML) file, either select the file from the list (the list stores all the
previously selected .gxsc and .xml files) or click the browse button and navigate to
a file.
3 Use the Command List buttons to:
Rename a command
Change the order of the commands in the list
Delete one or more commands from the list
Save the .gxsc or .xml file under the same or a different name.
4 Click Go to play the script. The results of the script execution are displayed in the
Message area of the window.
Traces
The lower pane in the J CardManager displays a log file known as a trace. You can
make this trace pane disappear and reappear (known as toggling), clear its contents or
save the contents to a file.
To make the trace pane disappear or reappear:
Click in the toolbar or choose View >Trace >SwitchTrace Action or press Alt+X.
To clear the trace pane:
Click in the toolbar or choose View >Trace >CleanTrace Action or press Alt+E.
To save the trace in a file:
Click in the toolbar or choose View >Trace >SaveTrace Action or press Alt+S.
Note: For more detailed information about the ATF Script Player, click Help.
Note: You can also edit XML files graphically using the Script Editor tool.
Note: For more detailed information about the XML Script Player, click Help.
T
e
r
m
i
n
o
l
o
g
y
Abbreviations
3GPP 3rd Generation Partnership Project
AID Application Identifier
APDU Application Protocol Data Unit
API Application Programming Interface
ATF APDU Trace Format
ATR Answer To Reset
CAD Card Acceptance Device
CAP Card Applet Package
CAT Card Application Toolkit
CBC Cipher Block Chaining
CCAT CDMA Application Toolkit
CLA Class byte
CLDC Connected Limited Device Configuration.
CPLC Card Production Life Cycle
DES Data Encryption Standard
ECB Electronic Code Book
ETSI European Telecommunications Standards Institute
EXP J ava Card Export file
FSD Full Serialized Data
GSM Global System for Mobile communications
ICV Initial Chaining Vector
IDE Integrated Development Environment
INS Instruction byte
ISO International Standards Organization
J2ME J ava 2 Platform Micro Edition
JAR J ava Archive file
JCA J ava Card Assembler
JCRE J ava Card Runtime Environment
JCVM J ava Card Virtual Machine
JDK J ava Development Kit
JSR J ava Specification Request
JVM J ava Virtual Machine
190 Terminology
Glossary
Lc Data length
Le Expected length of data to be returned
MAC Message Authentication Code
ME Mobile Equipment
MIDP Mobile Information Device Profile
OCF OpenCard Framework
OP Open Platform
OTA Over The Air
PC/SC Personal Computer/Smart Card
PIX Proprietary Identifier Extension
PK Public Key
RID Registered Identifier
R-UIM Removable User Identity Module
SAP Simulator Applet Package (card simulator-proprietary load
format)
SAT SIM Application Toolkit
SATSA Security And Trust Services API
SIM Subscriber Identity Module
TCP/IP Transmission Control Protocol/internet Protocol
TPDU Transport Protocol Data Unit
TPUD TP User Data
UICC Universal Integrated Circuit Card
USAT USIM Application Toolkit
USIM Universal Subscriber Identity Module
VM Virtual Machine
WTK Wireless Toolkit
Applet In J ava Card terminology, a J ava Card applet is an
independent J ava application loaded into a J ava Card.
Application
identifier
A string of between 5 and 16 bytes that identifies a
package or an application in a card and which
corresponds to the naming scheme defined in ISO7816-5.
It may contain a registered application provider number. If
it contains no application provider number, then this
identification may be ambiguous.
Application
Protocol Data
Units (APDU)
Standard communication messaging protocol between a
card acceptance device and a smart card.
Terminology 191
Application
Provider
The entity that owns an application and is responsible for
the applications behavior.
ATF file A Gemlato APDU Trace Format script file.
ATR When a card is inserted into a card reader, it stimulates a
contact, which provokes the terminal to reset itself by
sending a reset signal to the card. The cards response is
called an Answer To Reset (ATR).
The ATR is described in two standards:
ISO 7816-3: Electronic signals and transmission protocols,
which defines the two possible low-level communication
(or transport) protocols between the terminal and the card.
It is strongly advised to refer to this standard for details.
ISO 7816-4: Interindustry commands for interchange,
which defines a set of standard commands for smart
cards, as well as a hierarchical file system structure for
cards. These commands are the basis of most existing
card protocols.
Bytecode A VM instruction code as a sequence of binary bytes.
CAP files A file format that can be loaded into a card. CAP files are
generated by .
Card
Application
Toolkit (CAT)
A set of generic commands and procedures for use by the
UICC, irrespective of the access technology of the network
(for example, USAT for 3G, or CCAT for CDMA).
CCAT CDMA Card Application Toolkit. A set of commands and
procedures for use during the network operation phase of
CDMA.
CAT See Card Application Toolkit.
Card Simulator A software environment that simulates a J ava Card
context. Used for testing applet functionality before
loading the applet into a card.
Class files A compiled J ava code file.
Client
application
An application that requests services from a an applet in
the J ava Card environment.
Connected
limited device
configuration
(CLDC)
Defines the base set of application programming
interfaces and a virtual machine for resource-constrained
devices like mobile phones, pagers, and mainstream
personal digital assistants
Conversion A post-compilation step necessary to convert J ava Class
bytes into a form (.CAP files) understood by the card. This
is carried out automatically by Developer Suite V3.2 when
the project is built.
Converter A utility provided by Sun to convert J ava Class files into a
form understood by the card.
JAR file J ava Archive file. A compressed file containing J ava Class
files, or CAP load files. Used by the GxpLoader, for
example.
192 Terminology
Java Card-GP
applet
An applet that is fully compliant with the J ava Card and
GlobalPlatform specifications.
Java-GP Card Smart cards that are fully compliant with both the J ava
Card and GlobalPlatform specifications.
JCA file A J ava Card Assembler file, generated by the
GxpConverter or Suns Converter tool.
JCardManager A Developer Suite V3.2 tool that simulates a client
application, enabling a user to exchange commands with
an applet installed in either a card or the card simulator.
Key index Identifies a key within a key set.
Key set A set of encryption keys used to authenticate the owner.
Key version A number between 0 and 127 identifying the key version to
use.
Load file The physical data files that are uploaded to J ava-GP cards
to modify the cards contents.
MAC (Message
Authentication
Code)
A symmetric cryptographic transformation of data that
provides data origin authentication and data integrity.
MIDlet A MIDlet is an application written for MIDP. MIDlet
applications are subclasses of the
javax.microedition.midlet.MIDlet class that is defined by
MIDP.
Mobile
Information
Device Profile
(MIDP)
Mobile Information Device Profile. Set of J ava APIs that is
generally implemented on the Connected Limited Device
Configuration (CLDC). It provides a basic J 2ME
application runtime environment targeted at mobile
information devices, such as mobile phones and two-way
pagers. The MIDP specification addresses issues such as
user interface, persistent storage, networking, and
application model.
OTA interpreter The OTA Interpreter tool displays an interpreted view of
a sequence of OTA data bytes. Details of the
interpretation are displayed for envelope, command
packet header, and response packet message parts,
according to a specific OTA profile and the relevant 3GPP
TS 23.048 specifications
Package A J ava term to describe a collection of related classes and
interfaces. A package can contain, for example several
applets.
PC/SC The PC/SC (Personal Computer/Smart Card) Workgroup
was formed in May 1996 to resolve interoperability issues
between PCs and smart cards.
Members include Gemalto, IBM, Sun Microsystems,
Toshiba, Groupe Bull, Hewlett-Packard, Microsoft,
Schlumberger, and Siemens Nixdorf.
Project A collection of one or more applets, together with the
necessary system classes, with or without libraries. Also
used to describe a Eclipse IDE project.
Terminology 193
RID The first five bytes of an AID, registered with ISO,
indicating the Application Provider.
SCR file A Sun script file.
Scripts A list of commands. Gemalto scripts (.atf) or Sun scripts
(.scr) can be exchanged with a card or the card simulator.
SIM Application
Toolkit (SAT)
A set of commands that defines how a card should interact
with the outside world and extends the communication
protocol between the card and the handset. With SAT, the
card has a proactive role in the handset (this means that
the SIM initiates commands independently of the handset
and the network).
In 2G networks, SIM Application Toolkit (SAT) was defined
in the GSM 11.14 standard.
SIM Toolkit A set of commands and procedures for use during the
network operation phase of GSM, in addition to those
defined in TS 11.11.
Target The entity in which a J ava Card applet or package is
eventually installed. The target can be either the card
simulator or a specific type of card in a card reader.
Trace A log that shows the results of exchanges between the
reader and the card or card simulator. Traces can be
saved in a trace file.
Universal
Integrated
Circuit Card
(UICC)
A physically secure device, an IC card (or smart card),
that can be inserted and removed from the terminal
equipment. It may contain one or more applications. One
of the applications may be a USIM.
USIM Toolkit Provides mechanisms which allow applications, existing in
the UICC, to interact and operate with any ME which
supports the specific mechanism(s) required by the
application.These mechanisms are dependent upon the
commands and protocols relevant to USAT in 3GPP TS
31.101.
Wireless Toolkit The Sun J ava Wireless Toolkit (formerly known as J 2ME
Wireless Toolkit) is a set of tools for creating J ava
applications that run on devices compliant with the
J SR185 specification. It consists of build tools, utilities,
and a device emulator.
Wizard A predefined project builder provided by Developer Suite
V3.2 for the Eclipse IDEs to help you specify project-
related information. The wizards generate ready-to-
compile skeleton J ava code, to which the developer need
only add the applet or client applications functionality.
R
e
f
e
r
e
n
c
e
s
Standards and Specifications
3GPP TS 23.040 3rd Generation Partnership Project; Technical Specification
Group Terminals; Technical realization of the Short Message Service (SMS)
(Releases 5 and 1999)
Group Terminals; Security mechanisms for the (U)SIM application toolkit; Stage 2,
(Release 5)
Group Terminals; Security mechanisms for the SIM application toolkit; Stage 2;
(Release 1999)
Group Terminals; UICC-Terminal interface; Physical and logical characteristics
(Releases 5 and 6)
Group Terminals; Specification of the Subscriber Identity Module - Mobile
Equipment (SIM - ME) interface (Release 5)
3GPP TS 11.11: 3rd Generation Partnership Project; Technical Specification
Group Terminals; Specification of the Subscriber Identity Module - Mobile
Equipment (SIM - ME) Interface (Release 1999)
3GPP TS 31.111: Universal Subscriber Identity Module (USIM) Application Toolkit
(USAT) (Releases 5 and 1999)
3GPP TS 11.14: Specification of the SIM Application Toolkit (SAT) for the
Subscriber Identity Module - Mobile Equipment (SIM - ME) interface (Release
1999)
3GPP TS 31.1303rd Generation Partnership Project; Technical Specification
Group Terminals; (U)SIM Application Programming Interface (API); (U)SIM API for
Java Card, (Release 6)
Group Terminals; Subscriber Identity Module Application Programming Interface
(SIM API) for Java Card, Stage 2, (Release 5)
Group Terminals; Subscriber Identity Module Application Programming Interface
(SIM API) for Java Card, (Release 1999)
ETSI TS 102221; Technical Specification; Smart cards; UICC-Terminal interface;
Physical and logical characteristics (Release 5)
ETSI TS 102223; Technical Specification; Smart cards; Card Application Toolkit
(Release 5)
ETSI TS 102241; UICC API for Java Card (Release 6)
ISO/IEC 7816-4: 1995: Identification cardsIntegrated circuit(s) cards with
contacts Part 4: Interindustry commands for interchange
ISO/IEC 7816-6: 1996 Identification cardsIntegrated circuit(s) cards with
contacts Part 6: Interindustry data elements
196 References
GlobalPlatform Card Specification 2.0.1 from GlobalPlatform, April 7th, 2000.
GlobalPlatform Card Specification 2.1.1 from GlobalPlatform, March, 2003.
Java Card Specifications 2.2., Sun Microsystems, J une 2002.
Java Card Specifications 2.2.1, Sun Microsystems, October 2003.
JSR 185: Java Technology for the Wireless Industry, Sun Microsystems, J uly 2003
Web Site Addresses
www.gemalto.com for more information about Gemalto products and services.
www.borland.com to download Eclipse.
www.globalplatform.org to download copies of the GlobalPlatform (Open Platform)
specifications.
www.java.sun.com for anything relating to J ava.
www.developers.sun.com for introduction to J ava (see Recommended Reading)
www.opencard.org for information about the Open Card Framework.
www.etsi.org for information about European Telecommunications Standards (3GPP).
Recommended Reading
For more information about J ava applet development for smart cards, see:
An Introduction to Java Card Technology, parts 13, from
www.developers.sun.com/techtopics/mobility/javacard/articles/javacard1/
(for parts two and three the link is the same but with 2 or 3 at the end, respectively)
Application Programming Notes, Java Card Platform Version 2.2.1 from Sun
Microsystems, October 2003
Open Card Framework 1.2 Programmers Guide, available from:
http://www.opencard.org.
I
n
d
e
x
Numerics
3DES
key lengths 19
performing computations using crypto tool 28
3GPP standards 27, 195
23.040 175, 178, 180
23.048 13, 161, 173, 176, 180
A
access conditions (USIM toolkit applets) 90, 142
AES key lengths 19
AIDs 6, 33
format 6
APDUs 1
commands 1
responses 1
APIs
GP 3
GSM extension to J ava Card 3
J ava Card 3
OP 2
open card framework (OCF) 2
applets 2
AIDs 6
debugging 41, 42, 9197, 114115
difference between J ava Card & J ava Card GP 3
installing 41
installing (in Eclipse) 97, 152
J ava Card 3, 42, 113116
J ava Card-GP 3, 114
J CRMI 42, 99111
loading 41, 97, 152
overview 2
testing 42, 98, 111, 116, 153
USIM toolkit 7798
application identifiers. see AID
application manager 161162
availability in different versions of GXD 19
interface 162
overview 162
starting 162
application repository (in application manager)
161
ATF
script player 187
ATF personalization scripts 79, 129, 186
atf script files. See ATF personalization scripts
C
CAD (card acceptance device) 1
cap file utility 28
CAP files 5, 10, 43
card
acceptance device (CAD) 1
life cycle management 2
card simulators
as a target 4
starting 27
use in testing 98, 153
cards
GemXplore Xpresso V3 13
class files 9
client applications 1, 4
changing choice as debugging tool 92, 146
choosing 94, 148, 150
J CardManager 4, 114115
J CRMI 42, 99111
mobile simulator 3G 4
OCF 42, 115
overview 4
Simulation Chain 2G 4, 10
to debug applets 91, 145
using Eclipse 4
client projects
J CRMI 107108
OCF 115
commands, performing in J CardManager 186
components 1929
creating
http midlet projects 156157
J ava Card applets 113114
J ava Card projects 7783
J CRMI applets 104107
J CRMI client projects 107108
libraries 159
midlet projects 119120
OCF client projects 115
remote object interface 99104
SCWS projects 127134
servlet 134145
USIM toolkit applets 8491
crypto tool 28
cryptographic capabilities 19
D
DAP parameters 83, 133
198 Index
debugging
applets 41, 42, 9197, 114115
J CRMI applets 108111
libraries 81, 131
place in development flow 43
projects 9495, 109111, 114115, 147151
servlets 145150
tools 42, 80, 91, 92, 130, 145, 146
with J CardManager 114115
with J CRMI client application 108111
with mobile simulator 3G 9197
with OCF client application 115
with static content explorer 145150
DES
key lengths 19
performing computations using crypto tool 28
development cycle (typical) 41
development phase 9
E
Eclipse 10, 43
starting the key file editor 171
use to create projects 77
use to develop client applications 4
Eclispe
as test application 80, 130
ETSI standards
102-241 3
31-130 3
example
servlet 134154
export files 81, 131
external export files 81, 131
external libraries 81, 131
F
file system access conditions (USIM toolkit ap-
plets) 90, 142
file system editor 167169
contextual commands 169
interface 168
files
CAP 5, 10, 43
class 9
external export 81, 131
formats 5
IJ C 5, 10, 43
J AR 5, 10, 43
SAP 5, 10, 43
script 9, 79, 129, 163165, 186187
G
GemXplore Xpresso V3 cards 13
generating skeleton J ava code 33
GP
API 3
secure channel 106
specifications 2, 27
GSM extension to J ava Card specification 3
gxsc script files 41, 80, 130, 160, 186
H
hardware requirements 13
hash algorithms 7
http midlet
project creation 156157
I
IJ C files 5, 10, 43
installation
afterwards 15
overview 14
preparation 14
procedure 14
wireless toolkit (WTK) 2.3 16
installing applets 41
in Eclipse 97, 152
instances 3
AIDs 6
ISO 7816-5 6
J
J 2ME emulator 29
J AR files 5, 10, 43
J ava Card
API 3
applet wizard 114
applets 3, 42, 113116
application 2
as a target 4
project wizard 77
virtual machine (J CVM) 5
J ava Card specification
2.1.1 27
2.2 27
2.2.1 5, 27
GSM extension 3
J ava Card-GP 106
declaring an applet as GP 114
J ava code
generating 33
setting breakpoints 93, 147
J ava packages
org.globalplatform 2
overview 4
visa.openplatform 2
Index 199
J CardManager 10, 185187
as client application 4
as debugging tool 42, 80, 114115, 130
interface 185
performing commands in 186
starting 185
starting the key file editor in 171
use in testing 42
J CRMI
client project wizard 107
client projects 107108
J CRMI applets 42, 99111
adding to a project 104
debugging 108111
wizard 105
K
key file editor 171
interface 171
starting from Eclipse 171
starting from J CardManager 171
key lengths 19
L
libraries 6, 159160
creating 159
debugging 81, 131
using 159
loading
applets 41, 97, 152
logical channels 186
M
midlet
project creation 119120
midlet test application 80, 130
mobile simulator 10
operating the 3G simulator 95
starting 27
use in debugging 42, 9197
use in testing 42
versions 92, 146
O
OCF
client projects 115
See also WTK-OCF bridge
OP 2.0.1 specification 2
Open Platform. see GlobalPlatform
opencard framework (OCF) 2
org.globalplatform package 2
OTA
events 28
interpreter 8, 29
minimum security for USIM toolkit applets 89,
141
profiles 173183
P
packages 4
AIDs 6
See also J ava packages
personalization scripts. See ATF personalization
scripts
PIXs 6
profiles
OTA 173183
projects 10
creating http midlet 156157
creating J ava Card 7783
creating J CRMI client 107108
creating midlet 119120
creating OCF clients 115
creating SCWS 127134
debugging 9495, 109111, 114115, 147
151
overview 6
R
remote object
creating interface 99104, 106
preverification 103
wizard 100103, 106
requirements
hardware 13
software 13
RIDs 6
RSA key lengths 19
S
SAP converter 5
SAP files 5, 10, 43
generated by gxpConverter 5
SATSA midlets 4, 16, 42
script editor 9, 98, 153, 163165
interface 164
starting 163
script files 9, 41, 163165, 186187
atf. See ATF personalization scripts
gxsc 160, 186
xml 186
secure channel 2
GP (for J CRMI applets) 106
200 Index
serial cable 1
servlet
example 134154
servlets
debugging 145150
SIM
access parameters (USIM toolkit applets) 90,
142
card simulator 27
SIM toolkit java card 13
Simulation Chain 2G 4, 14
as client application 10
as debugging tool 80, 130
Simulation Chain 3G.see Simulation Chain 2G.
simulators
card 4, 27, 98, 153
mobile 27
smart card reader 1
software requirements 13
static content explorer
use in debugging 145150
T
targets
loading applets onto 4
types 4
TCP/IP 1
test phase 10, 43
testing
applets 42, 98, 111, 116, 153
tools 42
TLP 224 protocol 29
tools 68, 10, 28
debugging 42, 80, 91, 130, 145
testing 42
TPDU 7, 29
traces 187
U
USIM toolkit applets 7798
adding to a project 84
debugging 91, 145
installation parameters 86
USIM toolkit java card 13
utilities 28
V
visa.openplatform package 2
W
wireless toolkit (WTK) 16, 103
installation 16
wizards
J ava Card applet 114
J ava Card project 77
J CRMI applet 105
J CRMI/OCF client project 107
OCF client project 115
remote object 100103
WTK-OCF bridge 29
X
xml
script files 186
script player 187

Developer Suite Getting Started

Transféré par

Informations du document

Copyright

Formats disponibles

Partager ce document

Partager ou intégrer le document

Options de partage

Avez-vous trouvé ce document utile ?

Ce contenu est-il inapproprié ?

Droits d'auteur :

Formats disponibles

Developer Suite Getting Started

Transféré par

Droits d'auteur :

Formats disponibles

Developer Suite V3.

Windows 2000 (with Service Pack 4)

XP (with Service Pack 2)

Windows Vista (with Service Pack 1)

Version 3.3 or higher

Reader Version 4.0 or later. This is required to read the online

28 Developer Suite V3.2 Components

Vous aimerez peut-être aussi