Developer Suite Getting Started Guide

Transcription

Developer Suite V3.2
Getting Started
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 Gemalto’s 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 particular 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
www.gemalto.com
Introduction
1
The Java Card Environment . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1
The GlobalPlatform Specifications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2
The OpenCard Framework . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2
Java Card Concepts and Terminology . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2
Applets . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2
GSM and 3G Extension to the Java Card Specification . . . . . . . . . . . . . . . . . . . . 3
CDMA Extensions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3
Client Applications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4
Targets . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4
Packages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4
File Formats . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5
CAP Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5
JAR Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5
SAP Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5
IJC 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
What’s New in This Release . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11
Who Should Read this Book . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11
Conventions Used in this Document . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11
Chapter 3
Chapter 4
Installing Developer Suite V3.2
13
System Requirements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Hardware Requirements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Software Requirements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Installation Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Before Installing Developer Suite V3.2 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Installing Developer Suite V3.2 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
After Installing Developer Suite V3.2 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Apply and Import A License for Developer Suite V3.2 . . . . . . . . . . . . . . . . . . . .
Importing WTK Devices Into Eclipse . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
13
13
13
14
14
14
15
15
16
Developer Suite V3.2 Components
19
License Key Manager . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Eclipse . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Static Content Explorer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Menu to Access . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Static Content Explorer View . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Static Content Explorer Toolbar . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
JCardManager . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
19
20
20
21
21
22
26
Contents
Chapter 1
iv
Contents
Chapter 5
Chapter 6
Application Manager 2G/3G . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Simulators . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
The SIM Card Simulators . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
The Mobile Simulators . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Simulation Chain 2G and Simulation Chain 3G . . . . . . . . . . . . . . . . . . . . . . . . .
Tools . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Cap File Utility . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Crypto Tool . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
File System Editor . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Key File Editor . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
OTA Interpreter . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Script Editor . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
WTK–OCF Bridge . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
26
26
27
27
28
28
28
28
28
29
29
29
29
Getting Started with Developer Suite V3.2
31
Developer Suite V3.2 Working Environment . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Developer Suite Perspective . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Java Card Project Management View . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Project Wizards And Applications Wizards . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Project Wizards: . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Applications Wizards - Twin displays: . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Java Card Project Import and Export . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Import and Export Menu Access . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Importing Developer Suite Projects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Exporting Developer Suite Projects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Project Properties Editor . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
How To Access . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Applications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Export Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
GDP and GBP pages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
The Out Line Viewer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
A Typical Development Cycle . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
How to import examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
31
31
32
33
33
33
34
34
35
36
38
38
40
40
41
41
41
44
M-NFC Enabled JavaCard Applet/Servlet
47
NFC Contactless Technology . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
NFC Technology Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Three Modes of Interaction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
NFC Contactless JavaCard Applets . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Card Emulation Applets . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Reader Emulation Applets . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Use of SIM / UICC Toolkit In NFC Contactless Applets . . . . . . . . . . . . . . . .
NFC Demo Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Creating An NFC Demo . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Creating Emulation and Reader Project . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Creating an Emulation Servlet . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Creating a Reader Servlet . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Debugging the Servlet Using the Mobile Simulator 3G . . . . . . . . . . . . . . . . . . . . . . .
Starting the Projects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Starting the Reader Project . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Starting the Emulation Project . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Two Ways To Use . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Use The STK Method: . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Use The SCWS Feature: . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
47
47
47
48
49
49
49
50
50
50
51
51
53
53
53
55
55
55
57
Contents
Chapter 7
Chapter 8
v
The Card Simulator Proxy . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
The OCF View . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Contact-less Tag Application: . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
How to create a contact-less tag application . . . . . . . . . . . . . . . . . . . . . . . . . . . .
How to program a contact-less tag application . . . . . . . . . . . . . . . . . . . . . . . . . .
How to run a contact-less tag application . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Contact-less Reader Application . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
How to create a contact-less reader application . . . . . . . . . . . . . . . . . . . . . . . . .
How to program a contact-less reader application . . . . . . . . . . . . . . . . . . . . . . .
How to run a contact-less reader application. . . . . . . . . . . . . . . . . . . . . . . . . . . .
60
62
63
63
64
65
69
69
70
72
Worked Example with USIM Toolkit Applet
77
Creating the Java Card Project with the Eclipse IDE . . . . . . . . . . . . . . . . . . . . . . . .
Adding a USIM Toolkit Applet to a Project . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
The Toolkit Applet Wizard . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Debugging the USIM Toolkit Applet . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Client Applications Used . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Mobile Simulator Versions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Applet Debugging Steps . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Debugging the Applet Using the Mobile Simulator 3G . . . . . . . . . . . . . . . . . . . .
Step 1: Setting breakpoints in the applet’s code . . . . . . . . . . . . . . . . . . . . . .
Step 2: Debugging the project . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Step 3: Operating the Client Application (Mobile Simulator) . . . . . . . . . . . . .
Step 4: Notification that execution has stopped on a breakpoint . . . . . . . . .
Step 5: Bug detection and correction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Loading and Installing the Applet in a Card using Eclipse . . . . . . . . . . . . . . . . . . . . .
Testing the USIM Toolkit Applet in a Real Card . . . . . . . . . . . . . . . . . . . . . . . . . . . .
77
84
84
91
91
92
93
93
93
94
95
96
97
97
98
Worked Example with JCRMI Applet and Client
99
Creating the Java Card Project with Eclipse IDE . . . . . . . . . . . . . . . . . . . . . . . . . . . 99
Creating a Remote Object Interface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 99
The Remote Object Wizard . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 100
Adding a JCRMI Applet to a Project . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 104
The JCRMI Applet Wizard . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 105
Creating a JCRMI Client Project . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 107
The JCRMI/APDU OCF Client Project Wizard . . . . . . . . . . . . . . . . . . . . . . . . . 107
Debugging the JCRMI Applet Using the JCRMI Client Application . . . . . . . . . . . . . 108
Step 1: Call the new function in the JCRMI client . . . . . . . . . . . . . . . . . . . . 108
Step 2: Setting breakpoints in the applet’s 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 JCRMI Applet in a Real Card . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 111
Chapter 9
Worked Example with JavaCard Applet and Client
113
Creating the Java Card Project with Eclipse IDE . . . . . . . . . . . . . . . . . . . . . . . . . .
Adding a JavaCard Applet to the Java Card Project . . . . . . . . . . . . . . . . . . . . . . . .
The JavaCard Applet Wizard . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Debugging the Java Card Applet Using JCardManager . . . . . . . . . . . . . . . . . . . . .
Step 1: Setting breakpoints in the applet’s code . . . . . . . . . . . . . . . . . . . . .
Step 2: Debugging the project with JCardManager . . . . . . . . . . . . . . . . . .
Creating the OCF Client Application . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
113
113
114
114
114
115
115
vi
Contents
Debugging the Java Card Applet Using the OCF Client Application . . . . . . . . . . . . 115
Loading and Installing the Applet in a Card using Eclipse . . . . . . . . . . . . . . . . . . . . 116
Testing the Java Card Applet in a Real Card . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 116
Chapter 10
Chapter 11
Chapter 12
Chapter 13
Worked Example with SATSA MIDlets
117
Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Creating the Applet . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Building the Midlet . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Creating the MIDlet . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Adding a SATSA Card Access Method . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Debugging the Applet and MIDlet . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
117
117
119
120
122
123
Worked Example with Servlet and Toolkit
127
Creating the Java Card Project with the Eclipse IDE . . . . . . . . . . . . . . . . . . . . . . .
Adding a Servlet to a Project . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
The Servlet Wizard . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Debugging the Servlet . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Client Applications Used . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Mobile Simulator Versions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Servlet Debugging Steps . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Debugging the Servlet Using the Static Content Explorer . . . . . . . . . . . . . . . . .
Step 1: Setting breakpoints in the Servlet’s code . . . . . . . . . . . . . . . . . . . .
Step 2: Debugging the project . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Step 3: Operating the Client Application (Static Content Explorer) . . . . . . .
Step 4: Notification that execution has stopped on a breakpoint . . . . . . . .
Step 5: Bug detection and correction . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Debugging the Servlet Using the Mobile Simulator 3G . . . . . . . . . . . . . . . . . . .
Loading and Installing the Servlet in a Card using Eclipse . . . . . . . . . . . . . . . . . . .
Testing the Servlet in a Real Card . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
127
134
135
145
145
146
146
147
147
147
149
150
150
150
152
153
Worked Example with HTTP MIDlet
155
Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Creating the Servlet . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Creating the HTTP MIDlet . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Debugging the Applet and MIDlet . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
155
155
156
157
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
Chapter 15
Using the Application Manager
161
Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Overview of Defining and Running an Application . . . . . . . . . . . . . . . . . . . . . . . . .
Starting the Application Manager . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
The Application Manager Window . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
161
162
162
162
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 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
SMS Options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Text and Data Format . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Secured Message Options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
SPI . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
KIc . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
KID . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Configuring Data Encryption . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Configuring CC, RC, or DS Security Settings . . . . . . . . . . . . . . . . . . . . . . .
Expert Options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Concatenation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Command Packet Header . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Response Packet Header . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
173
174
175
176
176
178
179
179
180
180
181
181
182
The JCardManager
185
Appendix B
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 Java 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 WTK–OCF Bridge . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29
Figure 24 - Switch to Developer Suite Perspective . . . . . . . . . . . . . . . . . . . . . . . . . . 32
Figure 25 - Java 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
Figure 55 - Start Reader Project - Mobile Simulator Home Screen . . . . . . . . . . . . . .
Figure 56 - Start Emulation Project - MS 3G Started With Emulation Servlet . . . . . .
Figure 57 - Using STK Method - Switch Reader Servlet To Reader Mode . . . . . . . .
Figure 58 - Using STK Method - NFC Window Menu . . . . . . . . . . . . . . . . . . . . . . . .
Figure 59 - Using STK Method - NFC Management Window . . . . . . . . . . . . . . . . . .
Figure 60 - Using STK Method - Transfer Completed . . . . . . . . . . . . . . . . . . . . . . . .
Figure 61 - Using the SCWS Feature - Mobile Simulator Select Button . . . . . . . . . .
Figure 62 - Using the SCWS Feature - Load URL Menu . . . . . . . . . . . . . . . . . . . . .
Figure 63 - Using the SCWS Feature - Load URL Dialogue . . . . . . . . . . . . . . . . . . .
Figure 64 - Using the SCWS Feature - NFC Application Reader Demo . . . . . . . . . .
Figure 65 - Using the SCWS Feature - Switch Reader Servlet Mode . . . . . . . . . . . .
Figure 66 - Card Simulator Console . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Figure 67 - Card Simulator Console - Configuration Dialogue . . . . . . . . . . . . . . . . .
Figure 68 - Card Simulator Console - Confirm Terminating . . . . . . . . . . . . . . . . . . .
Figure 69 - OCF View . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Figure 70 - Tag Wizards . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Figure 71 - Souce Code . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Figure 72 - . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Figure 73 - . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Figure 74 - . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Figure 75 - . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Figure 76 - . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Figure 77 - . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Figure 78 - . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Figure 79 - . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Figure 80 - . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Figure 81 - . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Figure 82 - . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Figure 83 - . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Figure 84 - . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Figure 85 - . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Figure 86 - . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Figure 87 - . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Figure 88 - . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Figure 89 - Java Card Project Creation Wizard - Step 1 . . . . . . . . . . . . . . . . . . . . . .
Figure 94 - Adding a DAP Control . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Figure 95 - The Toolkit Applet Wizard – Step 1 . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Figure 99 - The Toolkit Applet Wizard – Step 4 – Menus . . . . . . . . . . . . . . . . . . . . .
Figure 100 - The Toolkit Applet Wizard – Step 4 – Priority and Timers . . . . . . . . . .
Figure 101 - The Toolkit Applet Wizard – Step 4 – Channels . . . . . . . . . . . . . . . . . .
Figure 102 - The Toolkit Applet Wizard – Step 4 – Min. Security Level . . . . . . . . . .
Figure 103 - The Toolkit Applet Wizard – Step 4 – Security Parameters . . . . . . . . .
Figure 104 - The Toolkit Applet Wizard – Step 4 – SIM Access Parameters . . . . . .
Figure 105 - The Toolkit Applet Wizard – Termination . . . . . . . . . . . . . . . . . . . . . . .
Figure 106 - Interactive Debugging of USIM Toolkit Applets . . . . . . . . . . . . . . . . . . .
Figure 107 - Setting Breakpoints in the Java Code . . . . . . . . . . . . . . . . . . . . . . . . . .
Figure 108 - Debug window . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Figure 109 - Mobile Simulator 3G Waiting for User Interaction . . . . . . . . . . . . . . . . .
Figure 110 - The Triggered Breakpoint in the Eclipse IDE . . . . . . . . . . . . . . . . . . . .
ix
55
55
56
56
56
57
57
57
58
58
58
60
60
61
62
63
65
66
66
67
67
67
68
68
69
70
71
72
72
72
73
73
74
74
78
79
80
81
82
83
84
85
85
86
86
87
88
88
89
90
91
93
93
94
95
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 - Java Card Project Implementation Source . . . . . . . . . . . . . . . . . . . . . 104
Figure 119 - The JCRMI Applet Wizard – Step 1 . . . . . . . . . . . . . . . . . . . . . . . . . . 105
Figure 122 - JCRMI/OCF Client Project Wizard – Step 3 . . . . . . . . . . . . . . . . . . . . 108
Figure 123 - Call New Function . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 109
Figure 124 - Setting the Breakpoint for JCRMI 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 - J2ME Midlet Project Wizard Step 2 . . . . . . . . . . . . . . . . . . . . . . . . . . . 120
Figure 132 - Create New J2ME Midlet . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 120
Figure 133 - New J2ME 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 JCRMI Method . . . . . . . . . . . . . . . . . . . . . . . . . . . 123
Figure 138 - Debug Configuration for the JCRMI Applet Project . . . . . . . . . . . . . . . 124
Figure 139 - Specifying the MIDlet Project . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 124
Figure 140 - The WTK Mobile Simulator . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 125
Figure 141 - Java 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 Java Code . . . . . . . . . . . . . . . . . . . . . . . . . 147
Figure 165 - Debug Window . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 148
Figure 166 - Static Content Explorer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 149
Contents
Figure 167 - The Triggered Breakpoint in the Eclipse IDE . . . . . . . . . . . . . . . . . . .
Figure 168 - Mobile Simulator 3G Waiting for User Interaction) . . . . . . . . . . . . . . .
Figure 169 - Accessing the Script File in Eclipse . . . . . . . . . . . . . . . . . . . . . . . . . .
Figure 170 - Script Editor Showing the Load Script . . . . . . . . . . . . . . . . . . . . . . . . .
Figure 171 - HTTP Midlet Access Wizard- Step 1 . . . . . . . . . . . . . . . . . . . . . . . . . .
Figure 172 - HTTP Midlet Access Wizard - Step 2 . . . . . . . . . . . . . . . . . . . . . . . . .
Figure 173 - Debug Configuration for the JCRMI Applet Project . . . . . . . . . . . . . . .
Figure 174 - Specifying the MIDlet Project . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Figure 175 - The Application Manager Main Window . . . . . . . . . . . . . . . . . . . . . . .
Figure 176 - Script Editor Window . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Figure 177 - Script Editor – The Add/Remove Commands Window . . . . . . . . . . . .
Figure 178 - The Select the Target Window . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Figure 179 - File System Editor . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Figure 180 - Key File Editor . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Figure 181 - The OTA Profile Manager Window . . . . . . . . . . . . . . . . . . . . . . . . . . .
Figure 182 - The Originating Address Editor Window . . . . . . . . . . . . . . . . . . . . . . .
Figure 183 - Triple DES Encryption . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Figure 184 - The Initial JCardManager Window . . . . . . . . . . . . . . . . . . . . . . . . . . .
xi
150
151
153
153
156
157
158
158
162
164
164
167
168
171
173
174
180
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 Java Card environment and explains the main Java 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 Java Card application.
Figure 1 - The Java Card Environment:a PC/Workstation-Resident Client
Application
PC/Workstation
Smart card reader
Communications
using APDUs
Smart card reader
to PC link (USB or
serial ports)
Java Card with
applet loaded into
the card
Client application
resident on PC/
Workstation
Java 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.
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 Java Card
environment.
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.
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 card’s security by,
for example, updating keys and setting up a secure channel between the card and
the terminal.
■
An API, consisting of a single Java package, org.globalplatform (or
visa.openplatform in the case of GP 2.0.1) that can be used by application
developers to access the GP features, in particular the application’s life cycle and
the secure messaging mechanism.
■
A documented specification, which describes in detail the commands available and
the principles of interoperability between the Java 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 Java program designed to work within the Java Card environment. Apart
from being programmed in Java, a Java Card applet is very different from a web
browser-based Java applet.
Note: An applet is often referred to in specifications as a “Java Card application”. The
GlobalPlatform documentation, for example, is not specific to Java 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.
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 card’s life cycle.
On GSM cards, for example, applets can be downloaded:
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, Java 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 Java card can manage three types of API:
■
■
■
Toolkit
Java 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 Java Card applications can be written using either exclusively Java
Card API methods (Java Card applets), or a combination of Java Card and
GlobalPlatform methods (Java Card-GP applets). Both types of applets must be
created using the Java Card Applet wizard. See “Chapter 8 - Worked Example with
JCRMI Applet and Client”. The choice of Java Card or Java Card-GP is made during
step 4 of the Java 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 Java Card API has been extended with a GSM-specific API.
This API is defined in ETSI 102–241 (a common Toolkit API for Telecom technologies)
and either the 3GPP TS 43.019 (for 2G cards) or 3GPP 31–130 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.2’s Java 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)
■
Java 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 application’s requests.
The following client applications are provided with Developer Suite V3.2:
■
The Mobile Simulator GSM, Mobile Simulator 3G, and Mobile Simulator CDMA.
■
The JCardManager.
■
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 Java 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 Java Cards or a card reader and also allows you to
debug your applets.
Packages
A package is a Java 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 application’s classes must belong to a different
package than the applet’s 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 Java Card Virtual Machine (JCVM) on the card. The process is
illustrated in “Figure 2 - The Compilation, Loading and Conversion Process”:
Figure 2 - The Compilation, Loading and Conversion Process
Eclipse and Developer Suite V3.2
Compiler
Java Card plug-in
Converter
Source
Java
Code
Compiled
Java Code
.Java
. Class
Loader
Byte
Code
. SAP . CAP
. JAR .IJC
Java Card
Virtual Machine
( JCVM)
The process involves converting the Java 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 Java Card Virtual Machine.
CAP Files
The “.cap” file format is the loadable file format defined by the Java 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 Java 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 Java 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 Java Card CAP file format, see Sun’s Java Card 2.2.1
Virtual Machine Specification.
JAR Files
The “.jar” file structure is also defined in the Java 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.2’s 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 JAR files, leaving
JAR to CAP conversion open, which caused divergences in CAP file formats from one
manufacturer to another.
6
Introduction
The idea was thus to define a loadable file format containing only the components
described as mandatory by the Java Card specification (for example, the optional
“Descriptor” component has been removed in the IJC format).
In other words, the IJC 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
Application Identifier (AID)
RID (5 bytes)
PIX (up to 11 bytes)
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 Java 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.2’s 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 plugins (see also “Eclipse” on page 20). It adds a user-friendly Developer Suite
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
Java Card project, such as Java package names and default applet AID values. All
Wizards can be launched through quick access from Application Wizard view
panel (see “Java Card Project Management View” on page 32).
■
Pre-loading tools: The Developer Suite V3.2 Java 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 JCardManager 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 type’s
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 SHA–1 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 WTK–OCF Bridge assures communication between the J2ME 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 Java
Card Plug-in for Eclipse
Converting Class files to loadable files (CAP or SAP).
8
Introduction
Table 1 - Development Stages and Steps (continued)
Development Tools
Development Stages
Loading tools and Post-loading tools:
Application Manager
Loads and installs applets.
JCardManager
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
JCardManager
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.048formatted data bytes
File System Editor
Viewing the file structure and individual properties and
access conditions for a file.
WTK–OCF bridge
A bridge between Sun’s Wireless Toolkit (WTK) phone
simulator and Developer Suite V3.2's reader/card
connection. Enables communications with a real reader/
card connection (since the WTK’s TLP224 protocol is
integrated directly in the card simulators).
The Developer Suite V3.2 tools can be launched from within the plug-ins provided for
Eclipse, or from within the JCardManager. 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.
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
Introduction
9
Table 2 - Accessing Developer Suite V3.2 Tools (continued)
Tool
Accessible from:
Eclipse
Plug-in
JCardManager
Command Line
Script Editor
Yes
Yes
No
Key File Editor
Yes
Yes
No
File System Editor
No
Yes
No
OTA Interpreter
Yes
Yes
No
WTK–OCF bridge
Yes
Yes
No
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.
Note: When you debug a project, Developer Suite V3.2 automatically builds the
project for you first, that is, compiles the Java source code to Class files and converts
the Class files to CAP, JAR, or other file formats as necessary.
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.
10
Introduction
The following diagram illustrates the development phase.
Figure 4 - The Development Phase
Wizards
Eclipse IDE
Debugger
Java Class File
Project
Installed applet
triggers breakponts
Java Card Plug-in
Automation
Java Card
Project
.GBP, GDP &
.GXSC
File
Conversion
Edition of .GXSC files
Script Editor
.JAR
.SAP
.CAP
.IJC
Loader
Card Simulator
Communication
Communication
JCard Manager
Mobile Simulators
(GSM, 3G, CDMA)
Communication
Simulation Chain 2G,
Simulation Chain 3G
Tools Used During the Test Phase
Once you have built and debugged your Java Card application, it can be further tested
in a real card.
The test scenario would be:
■
Load the applet into the card with JCardManager (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
JCardManager (for Java Card applets)
OCF Client application (for Java Card applets)
JCRMI Client application (for JCRMI applets)
SATSA Midlet
What’s 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
notation
Book titles are shown in italics.
■
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.
Preface
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 Java Card applet, through
to its installation and testing.
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\bin
you may need to substitute the following directory:
c:\Program Files\Gemalto\DeveloperSuite\bin
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:
...\examples\carddir
you may need to substitute the following directory:
...\examples\USIM Card 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)
Java 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
2
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)
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 Eclipse’s menu bar, adds the
Java Card Project Management view, and configures various Java Card projectspecific property settings. The Developer Suite menu allows you to directly launch
the various tools. The Java Card Project Management view gives you quick
14
access to Java Card project and applet creation wizards. Certain tools display their
output in Eclipse’s messages window.
Note: Eclipse is installed as part of the Developer Suite V3.2 installation procedure.
3
The Java™ 2 Software Development Kit (SDK) 1.5 or higher. This is also installed
as part of the Developer Suite V3.2 installation procedure.
4
Java 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/JCE.
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 .zip
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 (16–bit).
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.
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 .zip file) to a temp directory and
double-click the executable program (like GXDev_Install.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.
2
15
Choose the Install Developer Suite V3.2 Installation option. This program guides
you through the installation process.
Note: The default software installation directory is:
c:\Program Files\Gemalto\Developer Suite
You can specify a different drive or directory. To avoid confusion, the installation
directory is referred to as “installdir” throughout this document.
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
16
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 Java 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:\DeveloperSuiteWtk.
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.
3
17
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
18
5
On the Browse For Folder window, browse to WTK 2.5’s installation directory(c:\
DeveloperSuiteWtk 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 J2ME for Eclipse. This is a global setting which
means you don’t 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 Java 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 512–bit 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)
Note: Longer values are accepted by the Evaluation Version, but in practice the
bits that exceed the allowed length are set to zero.
■
Only the SCWS card and SIM R5 card profiles (available in wizards, mobile
simulators, commands, and so on) are available in the evaluation version.
20
Eclipse
The Developer Suite V3.2 is a Java Card plug–in 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.
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
Toolbar
Static Content
Tree Structure
Right-click
Contextual
Menu
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
22
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.
Tip: Press Ctrl and click the to select multiple files in the explorer window.
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:
1
23
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 folder’s path is given. The new folder will be
added into that directory.
In the text field, enter a name for new folder.
Note: When you name the new folder, notice that space is allowed which a
backslash (\) is forbidden.
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 can’t see update in the tree structure, click Refresh button or press F5 key to
refresh the display.
24
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
1
Delete allows you to remove unwanted files or folders from the SCWS card.
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.
Warning: To delete a folder will recursively delete all files and sub-folders under
it’s directory.
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.
2
25
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.jpg 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
26
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 JCardManager 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 JCardManager, refer to “Appendix B - The
JCardManager”.
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: GlobalPlatform–compatible cards
■
OTA mode: 3GPP TS 23–048 compatible cards
■
BIP mode: 3GPP TS 23–048 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.
27
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 Java Card, Telecom and
GlobalPlatform standards. The following table illustrates the differences:
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
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 Java 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.
28
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”.
29
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
DeveloperSuite\SimulationChain2G\GettingStarted.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”.
WTK–OCF Bridge
This tool aides communication between a J2ME emulator and a smart card. The J2ME
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 WTK–OCF Bridge
WTK-OCF
Bridge
OCF Protocol
TLP 224 Protocol
TLP 224 Protocol
J2ME Emulator
Card Simulator
Smart Card
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
Java 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 Java perspective combines views that you would
commonly use while editing Java source files, while the Debug perspective contains
the views that you would use while debugging Java 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
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 Eclipse’s 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 Java
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
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:
■
Java Card Project: including several sub types of Java Card Projects, each
specifying a card profile (R-UIM, SIM R99, USIM R5, etc.).
■
JCRMI / 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 Java Card project and an SCWS project.
■
When a Java 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 Java code that is ready to compile, and gather the
information necessary to build and configure a skeleton Java Card project, such as
Java 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 Java Card project in Eclipse.
34
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 Java 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
35
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 JBuilder Java Card projects.
This wizard is used to import Java Card projects exported from a JBuilder
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 JBuilder 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.
36
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 Java Card projects
into a ZIP file.
3
37
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.
Table 4 - Export Options and Relative Files
File
Default export
DS configurations
(.gdp, .gbp,
.launch)
X
Simulation Chain
configurations
X
+Sources
+External class
paths
+External scripts
X
Java source file
Class file
Local libraries
(.jar, .zip, .class)
X
X
External libraries
(.jar, .zip, .class)
Local scripts
(.gxsc, .atf, …)
External scripts
(.gxsc, .atf…)
X
X
Note: For easy synchronization with Simulation Suite, Developer Suite export all the
Simulation Suite configuration files under project/.conf directory.
5
Specify an export directory by click Browse button. Click Finish to complete
export.
38
Project Properties Editor
How To Access
Immediately after a completion of a Java Card/SCWS project wizard, the Project
Properties Editor automatically launches with the new project’s 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 Java Card/SCWS project’s parameters in Project
Properties Editor at any time by double-clicking the project’s .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
39
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 Java Card/SCWS project definition, including.
■
Project Location: Click this link to retrieve the first page of a Java Card project
wizard.
■
Java Card Project Settings: Click this link to retrieve the second page of a Java
Card project wizard.
■
Personalization script or Set project environment: Click this link to open the current
project’s run dialogue.
■
DAP setting: Click this link to retrieve the last page of a Java Card project, or the
second last page of an SCWS project wizard.
As most of the shortcuts reuse Java Card/SCWS project wizard, you can follow the
instruction next to each link to make changes to project’s 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
.gdp File
.gbp File
Y
Y
Y
ClassDir
Y
Y
ConversionDir
Y
Y
Name
Wizards
Version
40
Applications
The Application page is displayed when the Application tab is selected. With this
page, user can easily manage a Java Card/SCWS project’s 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/servlet’s settings: Select a package and an existing applet/
servlet under it in Application area. The information panel on the right display the
current selected item’s. 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
41
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 Javacard complier
–
Two compilers are provided at your choice: Eclipse JDT compiler and Javac
complier.
GDP and GBP pages
These two pages display when the <<project name>>.gdp or <<project
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 Java code “skeleton” with wizards.
2
Debug the applet using one of the following:
3
–
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.
–
Java Card Manager (for Java Card applets)
–
APDU OCF Client application (for Java Card applets).
–
JCRMI Client application (for JCRMI applets).
–
SATSA Midlet running in Sun’s WTK emulator.
–
HTTP Midlet (for SCWS card servlet).
–
Static Content Explorer (for SCWS card servlet).
–
Command line
Load and install the applet in a real card using one of the following:
–
Eclipse (by means of the script project.name_load.gxsc)
–
JCardManager (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”.
42
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:
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
JCardManager
Java Card Applet
OCF Client Application
SATSA Midlet
JCRMI Client Application
JCRMI Applet
SATSA Midlet
Simulation Chain 3G
Servlet, Servlet with Toolkit
Features
Mobile Simulator 3G
HTTP Midlet Test Application
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”.
■
JCRMI Applet, debugged and tested using the JCRMI Client Application, described
in “Chapter 8 - Worked Example with JCRMI Applet and Client”.
■
GP Applet debugged and tested using the OCF Client Application and
JCardManager, described in “Chapter 9 - Worked Example with JavaCard 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”.
Figure 38 - Development Flow with Developer Suite V3.2 Tools
Eclipse
Wizards
Java Source
Code
.class file
Automated Tasks provided
by the Java Card Plug-in
Output Type
Java Card
Simulator
File
Conversion
File
Conversion
.JAR File
.SAP file
.CAP or .IJC file
Start Card
Simulator
Non-automated Tasks
Load the .SAP file
into the Simulator
Load the .CAP or
.IJC file in the
Java Card
Personalize the
Applet
(Optional)
Personalize the
Applet
(Optional)
Run the
application on the
simulator
Run the
application on the
Java Card
Debug
Test
43
44
How to import examples
1
Click the File ->Import
Figure 39 -
2
45
Then you will see the picture below and click the Import Examples and Click the
Next button to continue
Figure 40 -
46
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
■
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
■
49
Reader emulation applets
Card Emulation Applets
Figure 45 - Card Emulation Applets
These applets are very similar to classic JavaCard applets. All commands (APDUs) are
sent by the RF reader. At the reception of each Contactless APDU the process ()
method is called with the APDU header in parameter. The applet computes the
response and sends it back using the classic JavaCard 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 ReaderModeStart() and ReaderModeStop()
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 process() method is used to deal with
contactless data. In order to use the SIM Toolkit interface to interact with the user, the
processToolkit() 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 process() method.
Use STKService.getInstance().triggerSTKEvent() to trigger STK event.
2
Catch the EVENT_PROACTIVE_HANDLER_AVAILABLE event in the
processToolkit() method and perform the proactive action there.
50
NFC Demo Overview
The following part is a guide of NFC JavaCard 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.
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.
This demo consists of two NFC JavaCard 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 JavaCard Projects (i.e. a JavaCard 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 applet’s 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 Java 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.
2
51
In the same way, create the second NFC Java Card project and name it as
“reader”.
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.
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
and add a servlet into it.
icon from the Application Wizards panel
52
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
Figure 49 - Reader Servlet Creation Step 1
button after Emulation Applet AID field.
6
53
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
54
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
55
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.
56
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
The tag has been
switched
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.
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
57
58
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
The tag has been
switched
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 Menu”shows.
7
Click the button
8
This trigger the transfer between two Mobile Simulators.
.
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.
59
60
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
61
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
62
The OCF View
This view allows your to manage multiple card simulator instances started from
JavaCard 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
list, like below:
to show the card simulators
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
63
64
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):
65
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 Java Card project works together,We will build
the Java Card project first then run the tag.java file
Run a Java Card project
1
Build the Java Card project with the name nfc_tag_reader_stkapplet
66
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 Java 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 -
67
68
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 -
69
70
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:
71
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 ì00770000026162îto 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 -
72
How to run a contact-less reader application.
To run a contact-less reader application there needs to be a Java Card project works
together,We will build the Java 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 -
73
74
Run a Java Card Project
1
Build the Java 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
75
7
Worked Example with USIM
Toolkit Applet
This chapter takes you step–by–step 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 Java Card Project
2
Add a USIM Toolkit Applet to the Java 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)
Note: You can also use the JCardManager and Application Manager to load and
install an applet in the card. For the former, refer to “Appendix B - The
JCardManager”. For the latter, refer to “Chapter 14 - Using the Application Manager”.
Creating the Java Card Project with the Eclipse IDE
To create the Java Card project within the Eclipse IDE:
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.
1
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 - Java 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
78
use the browse button
to the right of the box to select the path.
Enter the required information and click Next to continue.
Note: The Name must not contain any spaces.
Figure 89 - Java Card Project Creation Wizard - Step 1
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.
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.
7
79
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.
–
8
If you don’t want to use a sample template, click Next button to continue.
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.
80
Note: You can also include personalization scripts by customizing the generated
“_.load.gxsc” file using the Script Editor.
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
–
–
Midlet Test Application
–
Command Line
–
JCardManager
–
Simulation Chain 2G
–
Simulation Chain 3G
–
–
Client Test Application (OCF/JCRMI client)
–
None
For this example, choose “Mobile Simulator 3G” and click Next.
81
10 The Java Card Project wizard displays the next step to let you add external export
files to the project.
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
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.
Note: You only need to set the source path if you want to debug this external library.
To set the class path:
a) Click the Class Path tab in the Step 7 Export Files window.
82
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 JCardManager or
Application Manager.
83
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.
84
15 After creation, the Project Properties Editor launches with the created project’s
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 Java Card project.
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.
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 “Java Card Project Management View” on page 32), doubleclick Toolkit Applet (second icon from the top in the right column) to start the Toolkit
Applet wizard.
The Toolkit Applet Wizard
wizard, click the
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 applet’s install() method defined in the Java
Card specification and also in the Install command, as specified in the Global
85
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:
86
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.
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 Java Card project, this fourth step would contain a slightly
different list of 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
87
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 (01h–FFh 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.
88
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
89
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.
90
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.
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.
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
91
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.
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
process() method.
You can also include personalization scripts by customizing the _.load.gxsc file using the
Script Editor.
13 Click Finish to complete the wizard. Eclipse displays the Java 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.2’s Eclipse plug-in used in
conjunction with the applet wizards automatically configure Eclipse’s 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), JCardManager, 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 JCardManager for Java Card–GP applets (but you can also use it to send
APDU commands to a Toolkit applet).
92
■
Simulation Chain 2G (for SIM Toolkit or CCAT Toolkit applets), or Simulation Chain
3G for 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
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.
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
JCardManager or the OCF client or JCRMI client applications, are given in “Chapter
8 - Worked Example with JCRMI 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):
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
No pause mode
Custom APDU Exchange Feature
“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.
93
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
User
IDE
Card
Simulator
Applet
Client
Application
Set Breakpoint (Step 1)
Debug
(Step 2)
Start & Load the applet
Start
Operate client application (Step 3)
Send APDU
Notify
execution
stopped
(Step 4)
Stop
on
Breakpoint
Trigger
Applet
User Interaction
Automated Action
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 applet’s code
1
Select the project you created in the Eclipse IDE.
2
In the .java 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
94
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 drop–down 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
on the Mobile simulator.
2
Enter PIN code, 1234 and press
3
Select the USAT application option and press
for OK.
for OK.
95
96
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
97
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 right–clicking the _load.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
98
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 right–clicking the _load.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 JCardManager, 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 Java Card RMI applet and a Java
Card RMI client application.
In this example, you will create a JCRMI 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 JCRMI Client project that connects to the applet and
calls the “sum” method in the applet.
Note: Typically, the Remote Object Interface wizard is invoked during step 2 of the
JCRMI applet wizard. This example runs it before the JCRMI Applet Wizard in order to
describe it more clearly.
This example uses the following steps:
1
2
Create a Remote Object Interface
3
Add a JCRMI Applet to the Java Card Project that will use the remote object
4
Create a JCRMI Client Project that will use the JCRMI applet
5
Debug the JCRMI applet using the JCRMI Client application
6
Load and install the applet into a card using Eclipse
7
Test the Applet in the card using the JCRMI Client application
Creating the Java Card Project with Eclipse IDE
The creation procedure was described in the previous chapter. Refer to “Creating the
Java Card Project with the Eclipse IDE” on page 77.
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.
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.
100
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.
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.
The Remote Object Wizard
wizard, click the
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.
Note: You could also select Use existing interface and use the browse button
select the existing interface. In this case, the wizard skips the next wizard step.
2
Click Next.
to
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
101
In Method name enter “sum”.
In Return type, select short and leave Array empty.
102
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
103
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.
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).
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 Java source code.
104
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 JCRMI Applet wizard helps you add a JCRMI Applet to your Java 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.
105
The JCRMI Applet Wizard
wizard, click the
1
When you start the wizard, the first step window displays to let you define the
package settings for your JCRMI 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
106
you select an external project or create a new remote object. For more details
about these, click
.
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 JCRMI Applet wizard.
Check GP secure channel if the JCRMI applet is to use a GP secure channel, that
is, it is to be a Java Card–GP 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.”
107
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.
5
Click Finish to complete the wizard. Eclipse displays the Java code for your newly
created applet.
Creating a JCRMI Client Project
In this step you will create a project for the JCRMI Client application:
In Java Card Project Management view, double-click JCRMI / APDU OCF Client
Project.
Note: At any time during the execution of the wizard you can click Back to return to
to stop the wizard.
The JCRMI/APDU OCF Client Project Wizard
wizard, click the
1
In Step 1, enter the information for the JCRMI client application and click Next.
108
2
In Step 2, enter the information for the JCRMI 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 JCRMI 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 drop–down 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 JCRMI 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 JCRMI Client application.
Step 1: Call the new function in the JCRMI client
1
Open the JCRMI Client Project (for example, testClient.java).
2
109
Locate the line /**@todo ADD YOUR TEST HERE*/. Replace it with the lines 2329 as shown in the following figure:
Figure 123 - Call New Function
1
Open the Java Card project in Eclipse IDE.
2
Select the tab with the project’s remote interface implementation and in the .java
source file, set breakpoints (see “Step 1: Setting breakpoints in the applet’s 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.
110
3
On the configuration page shown on the right, enter a name for the new
configuration(e.g. JCRMIClient). 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
JCRMI client project.
8
Click OK to close the Application Parameter Editor dialog box.
9
111
Click OK to close the Application Parameter Editor settings window.
10 If you don’t 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.
Note: Eclipse may prompt a dialogue to you, asking whether to change current
perspective to Debug. Click No to discard it.
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 JCRMI applet in a card, you can test it as follows:
1
button at bottom of the screen.
2
Load the applet in the card, using the _load.gxsc script.
3
Switch to the client project.
4
Select the card reader containing your card.
5
Run the client project.
9
Worked Example with
JavaCard Applet and Client
This chapter presents an example of how to create a JavaCard applet and a Java Card
client application.
A Java Card applet can be debugged and tested using either an OCF Client application
or the JCardManager. This example shows how to use both options and uses the
following steps:
1
2
Add a JavaCard applet to the Java Card Project
3
Debug the JavaCard applet using JCardManager
4
Create an OCF client application
5
Debug the JavaCard 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 JCardManager and OCF client application.
Creating the Java Card Project with Eclipse IDE
This step was described in the previous chapter. Refer to “Creating the Java Card
Project with the Eclipse IDE” on page 77.
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.
After creation of your Java Card Project, add Java Card Applet to it as described
below.
Adding a JavaCard Applet to the Java Card Project
In this step you will add a Java 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.
114
2
In Java Card Project Management view, double-click JavaCard Applet. This
starts the JavaCard Applet wizard.
Note: You can only select the JavaCard Applet wizard if you have previously created
a project with the Java Card Project wizard.
The JavaCard Applet Wizard
to stop the wizard. To see detailed information concerning the completion of any step
of the wizard, click the
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 JavaCard 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.
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 process() method.
4
Click Next. This displays the final step of the wizard in which you choose the
following Java 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 .java source file.
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
3
If you don’t start debugging immediately, click Apply to save changes and then OK
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 JCardManager.
In JCardManager, send the Authenticate command. The processing stops on the
break points and triggers the applet.
If you implemented APDUs in the process 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 JCRMI/APDU OCF Client Project Wizard” on page 107.
Debugging the Java Card Applet Using the OCF
Client Application
The steps in debugging a Java Card applet are the same as when debugging with the
JCardManager. Refer to “Debugging the Java Card Applet Using JCardManager” 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 drop–down list, select Client Test
Application.
116
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.
6
If you don’t start debugging immediately, click Apply to save changes and then OK
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 Java 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 JCardManager, choose JCardManager.
3
In JCardManager, In Terminal, select the card reader containing your card.
4
In JCardManager choose the Select command from the Commands tree–structure
on the left (Commands > USim Card R6 > Platform > GP > Select).
In the Select command check Specific AID and select the JCRMI applet from the
list, then click Go.
5
If the applet is a GP applet, perform an Authenticate command in JCardManager
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 Java program for embedded devices, more specifically the Java 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
Java Card applets.
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.
Overview
The major steps described in this example are:
1
Develop an applet. For SATSA, this applet can be a Java Card Applet, a Toolkit
Applet, or a JCRMI Applet.
2
Create a J2ME 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 Java 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.
118
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
JCRMI Applet creation wizard.
2
On Step 2 of the JCRMI Wizard, click
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:
to define a new remote object.
short add(short v1, short v2)
The corresponding Add Method window is as follows:
Figure 128 - Remote Method Definition
6
Complete the JCRMI Applet Wizard to generate skeleton code.
.
7
119
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.
120
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
121
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 midlet1.java (the name
chosen in step 1 of the wizard).
122
Adding a SATSA Card Access Method
The next step is to add SATSA compatibility to allow the midlet to communicate with
the Java 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.
123
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 JCRMI 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.
7
The wizard adds SATSA card connection code to the midlet’s source code. For
example:
8
Modify the source code as shown below to call the remote JCRMI 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
124
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
125
Launch a project debug session to interactively debug the applet/midlet
combination. The WTK Mobile Simulator is launched, showing the midlet1 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 applet’s remote
Add method—see “Figure 129” on page 119). The results printed by the remote
JCRMI 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 step–by–step 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 JavaCard Project
2
Add a servlet to the JavaCard 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)
Note: You can also use the JCardManager and Application Manager to load and
install an servlet in the card. For the former, refer to “Appendix B - The
JCardManager”. For the latter, refer to “Chapter 14 - Using the Application Manager”.
Creating the Java Card Project with the Eclipse IDE
To create the Java Card project within the Eclipse IDE:
wizard, click the
1
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 - Java 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
128
use the browse button
to the right of the box to select the path. Enter the
required information and click Next to continue.
Note: The Name must not contain any spaces.
to stop the wizard.
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.
7
129
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.
–
8
If you don’t want to use a sample template, click Next button to continue.
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.
130
Note: You can also include personalization scripts by customizing the generated
“_.load.gxsc” file using the Script Editor.
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
–
–
–
Midlet Test Application
–
Command Line
–
JCardManager
–
Simulation Chain 2G
–
Simulation Chain 3G
–
–
Client Test Application (OCF/JCRMI client)
–
None
For this example, choose “Mobile Simulator 3G” and click Next.
131
10 The Java Card Project wizard displays the next step to let you add external export
files to the project.
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
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.
Note: You only need to set the source path if you want to debug this external library.
To set the class path:
a) Click the Class Path tab in the Step 7 Export Files window.
files.
132
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 JCardManager or
Application Manager.
133
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.
134
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 project’s
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 Java Card project. In Developer
Suite V3.2, two types of servlets are available:
■
Servlet - a Java 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 Java Card project your just created (or any existing
Java Card project you want to add the servlet to). On the Java Card Project
Management view (as in “Java Card Project Management View” on page 32), doubleclick Servlet or Servlet with STK features to start the Servlet wizard.
135
The Servlet Wizard
wizard, click the
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 applet’s install() method defined in the Java
Card specification and also in the Install command, as specified in the Global
136
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.
–
4
137
If you area creating a Servlet with STK features, go step by step to finish the
wizard.
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.
138
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
139
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 (01h–FFh 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.
140
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
141
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.
142
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.
143
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.
144
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 parameter’s 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
145
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 parameter’s 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.
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
process() method.
You can also include personalization scripts by customizing the _.load.gxsc file using the
Script Editor.
18 Click Finish to complete the wizard. Eclipse displays the Java code for your newly
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.2’s Eclipse plug-in used in
conjunction with the servlet wizards automatically configure Eclipse’s 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,
JCardManager, or Simulation Chain.
Client Applications Used
■
The Mobile Simulator 3G.
■
The Static Content Explorer.
146
■
Simulation Chain 3G.
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.
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):
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.
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
User
IDE
Card
Simulator
Applet
Client
Application
Set Breakpoint (Step 1)
Debug
(Step 2)
Start & Load the applet
Start
Operate client application (Step 3)
Send APDU
Notify
execution
stopped
(Step 4)
Stop
on
Breakpoint
User Interaction
Automated Action
Trigger
Applet
147
Debugging the Servlet Using the Static Content Explorer
This example describes how to debug a Java 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 Servlet’s code
1
Select the project you created in the Eclipse IDE.
2
In the .java 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.
148
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 drop–down menu, select Static
Content Explorer.
4
5
149
This launches the card simulator, loads the servlet and runs any personalization
scripts, and launches the Static Content Explorer.
Figure 166 - Static Content Explorer
The Static Content Explorer is
automatically launched from within
Eclipse
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.
150
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 Servlet’s 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.
4
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
on the Mobile simulator.
7
Enter PIN code, 1234 and press
8
Select the USAT application option and press
for OK.
for OK.
151
152
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
153
You can edit the script by right–clicking the _load.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 right–clicking the _load.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
button at the bottom of the screen.
154
2
Load the applet on the card, for example, using the GXSC deployment script.
3
In JCardManager, 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 J2ME MIDlet and configure it to
access a servlet on SCWS card.
A MIDlet is a Java program that runs on a Java Mobile Edition (J2ME) virtual machine.
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.
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 J2ME 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.
5
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.
156
2
Follow the instructions to finish the wizard and generate skeleton code.
Tip: “Chapter 11 - Worked Example with Servlet and Toolkit” contains detailed
information on how to create a Java Card Project as well as to add a Servlet.
If you still feel unclear about Java Card Project and servlet creation, you are
recommended to write that chapter first.
Creating the HTTP MIDlet
Follow steps below to create a HTTP MIDlet:
1
In Eclipse’s Package explorer, select the Java Card Project we just created.
2
The Applications Wizards area shifts to a Java 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 project’s 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.
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 Java 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
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
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 Java Card Project wizard, as described in “Creating the Java
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 Java Card project to use a library, it needs to know the location of the library’s
export files and class files.
To specify the location of a library in a Java Card project:
1
In Eclipse, run the Java Card Project wizard, as described in “Creating the Java
Card Project with the Eclipse IDE” on page 77.
160
2
In step 6, as shown in “Figure 92 - Java Card Project Creation Wizard - Step 7” on
page 81, add the library’s 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 library’s
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 library’s 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_load.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 Java 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
Current operating mode
Available Terminals
Online Help
Application repository
Actions to perform
Carry out the
selected action
Trace window
Card profiles
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 JCardManager’s 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 JCardManager 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
Quick Access Tool Bar
Card List
Command Management Controls
Script Editor Help
Command Parameters Area
Script Editor Help for Commands
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
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
3
In the Name Definition window, enter the new name and click OK.
button.
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
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 JCardManager, 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 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.
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:
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
To perform a contextual command:
1
Choose the file in the left pane on which you want to perform the command.
2
Right–click 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.
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 JCardManager.
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
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 window’s title bar.
The card template upon which the profile is based is displayed in the top right-hand
corner of the window.
An OTA profile’s 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
■
Expert. These parameters are intended for use by expert users only, and concern
the format of an SMS message’s 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
message’s OTA header.
Note: The originating address is the network address (MSISDN) of the message’s
originator, that is, the sending entity, not that of the SMSC that forwards the message
to the SIM card.
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.
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.
■
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
175
structure than in the network’s 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 EFSMS elementary file in the SIM card’s GSM file system.
176
■
Envelope. Download the text or data by sending an SMS Point-To-Point Data
Download Envelope command to the SIM card.
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.
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 message’s 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 message’s 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.
177
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 message’s 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 message’s recipient to
verify the authenticity of the information’s 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
message’s 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.
178
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 counter’s 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 message’s 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
Note: Depending on the target chosen, not all of the above options may be available.
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-DELIVERREPORT 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”.
179
Ciphering Key
Select the algorithm type and mode to use to cipher the message’s 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
180
first key, decrypted with the second key, and finally encrypted again with the third
key, as shown in “Figure 183”below:
Plain text
DES Encryption
Key 1
DES Decryption
Key 2
DES Encryption
Key 3
Ciphered text
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.
181
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 platform’s 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.
182
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.
■
183
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 JCardManager 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”.
JCardManager 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
Tool bar
Current Trace
For detailed help about JCardManager, click the JCardManager Help button
. This
section provides an outline of the main operations that you will want to perform.
186
The JCardManager
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 JCardManager you can use the record and play tools described below to record and
play both types of file. However, JCardManager 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
pressing the <F5> key.
in the toolbar or by choosing Script > Record or
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
Script > Stop or pressing the <F10> key.
in the toolbar or by choosing
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 .
To play a script file (general):
1
Start playing by clicking
F12.
in the toolbar or by choosing Script > Play or pressing
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.
The JCardManager
3
187
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:
–
–
–
–
4
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.
Click Go to play the script. The results of the script execution are displayed in the
Message area of the window.
Note: For more detailed information about the ATF Script Player, click Help.
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.
Note: You can also edit XML files graphically using the Script Editor tool.
3
Use the Command List buttons to:
–
–
–
–
4
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.
Click Go to play the script. The results of the script execution are displayed in the
Message area of the window.
Note: For more detailed information about the XML Script Player, click Help.
Traces
The lower pane in the JCardManager 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.
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
Java 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
Java 2 Platform Micro Edition
JAR
Java Archive file
JCA
Java Card Assembler
JCRE
Java Card Runtime Environment
JCVM
Java Card Virtual Machine
JDK
Java Development Kit
JSR
Java Specification Request
JVM
Java Virtual Machine
Terminology
Abbreviations
190
Terminology
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
TP–UD
TP User Data
UICC
Universal Integrated Circuit Card
USAT
USIM Application Toolkit
USIM
Universal Subscriber Identity Module
VM
Virtual Machine
WTK
Wireless Toolkit
Glossary
Applet
In Java Card terminology, a Java Card applet is an
independent Java application loaded into a Java 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
Application
Provider
The entity that owns an application and is responsible for
the application’s 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 card’s 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 Java Card
context. Used for testing applet functionality before
loading the applet into a card.
Class files
A compiled Java code file.
Client
application
An application that requests services from a an applet in
the Java 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 Java 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 Java Class files into a
form understood by the card.
JAR file
Java Archive file. A compressed file containing Java Class
files, or CAP load files. Used by the GxpLoader, for
example.
191
192
Terminology
Java Card-GP
applet
An applet that is fully compliant with the Java Card and
GlobalPlatform specifications.
Java-GP Card
Smart cards that are fully compliant with both the Java
Card and GlobalPlatform specifications.
JCA file
A Java Card Assembler file, generated by the
GxpConverter or Sun’s 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 Java-GP cards
to modify the card’s 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 Java APIs that is
generally implemented on the Connected Limited Device
Configuration (CLDC). It provides a basic J2ME
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 Java 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
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 A set of commands that defines how a card should interact
Toolkit (SAT)
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 Java 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 Java Wireless Toolkit (formerly known as J2ME
Wireless Toolkit) is a set of tools for creating Java
applications that run on devices compliant with the
JSR185 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 projectrelated information. The wizards generate ready-tocompile skeleton Java code, to which the developer need
only add the applet or client application’s functionality.
193
■
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)
■
3GPP TS 31.101 3rd Generation Partnership Project; Technical Specification
Group Terminals; “UICC-Terminal interface; Physical and logical characteristics
(Releases 5 and 6)
■
3GPP TS 51.011 3rd Generation Partnership Project; Technical Specification
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.130—3rd 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 102–221; Technical Specification; Smart cards; UICC-Terminal interface;
Physical and logical characteristics (Release 5)
■
ETSI TS 102–223; Technical Specification; Smart cards; Card Application Toolkit
(Release 5)
■
ETSI TS 102–241; UICC API for Java Card (Release 6)
■
ISO/IEC 7816-4: 1995: “Identification cards—Integrated circuit(s) cards with
contacts— Part 4: Interindustry commands for interchange”
■
ISO/IEC 7816-6: 1996 “Identification cards—Integrated circuit(s) cards with
contacts— Part 6: Interindustry data elements”
References
Standards and Specifications
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, June 2002.
■
Java Card Specifications 2.2.1, Sun Microsystems, October 2003.
■
JSR 185: Java Technology for the Wireless Industry, Sun Microsystems, July 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 Java.
www.developers.sun.com for introduction to Java (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 Java applet development for smart cards, see:
■
■
■
An Introduction to Java Card Technology, parts 1–3, 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 Programmer’s Guide, available from:
http://www.opencard.org.
C
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
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
JCardManager 4, 114–115
JCRMI 42, 99–111
mobile simulator 3G 4
OCF 42, 115
overview 4
Simulation Chain 2G 4, 10
to debug applets 91, 145
using Eclipse 4
client projects
JCRMI 107–108
OCF 115
commands, performing in JCardManager 186
components 19–29
creating
http midlet projects 156–157
Java Card applets 113–114
Java Card projects 77–83
JCRMI applets 104–107
JCRMI client projects 107–108
libraries 159
midlet projects 119–120
OCF client projects 115
remote object interface 99–104
SCWS projects 127–134
servlet 134–145
USIM toolkit applets 84–91
crypto tool 28
cryptographic capabilities 19
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 Java Card 3
Java Card 3
OP 2
open card framework (OCF) 2
applets 2
AIDs 6
debugging 41, 42, 91–97, 114–115
difference between Java Card & Java Card GP 3
installing 41
installing (in Eclipse) 97, 152
Java Card 3, 42, 113–116
Java Card-GP 3, 114
JCRMI 42, 99–111
loading 41, 97, 152
overview 2
testing 42, 98, 111, 116, 153
USIM toolkit 77–98
application identifiers. see AID
application manager 161–162
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
D
DAP parameters 83, 133
Index
Numerics
198
Index
debugging
applets 41, 42, 91–97, 114–115
JCRMI applets 108–111
libraries 81, 131
place in development flow 43
projects 94–95, 109–111, 114–115, 147–151
servlets 145–150
tools 42, 80, 91, 92, 130, 145, 146
with JCardManager 114–115
with JCRMI client application 108–111
with mobile simulator 3G 91–97
with OCF client application 115
with static content explorer 145–150
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 134–154
export files 81, 131
external export files 81, 131
external libraries 81, 131
F
file system access conditions (USIM toolkit applets) 90, 142
file system editor 167–169
contextual commands 169
interface 168
files
CAP 5, 10, 43
class 9
external export 81, 131
formats 5
IJC 5, 10, 43
JAR 5, 10, 43
SAP 5, 10, 43
script 9, 79, 129, 163–165, 186–187
G
GemXplore Xpresso V3 cards 13
generating skeleton Java code 33
GP
API 3
secure channel 106
specifications 2, 27
GSM extension to Java Card specification 3
gxsc script files 41, 80, 130, 160, 186
H
hardware requirements 13
hash algorithms 7
http midlet
project creation 156–157
I
IJC 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
J2ME emulator 29
JAR files 5, 10, 43
Java Card
API 3
applet wizard 114
applets 3, 42, 113–116
application 2
as a target 4
project wizard 77
virtual machine (JCVM) 5
Java Card specification
2.1.1 27
2.2 27
2.2.1 5, 27
GSM extension 3
Java Card-GP 106
declaring an applet as GP 114
Java code
generating 33
setting breakpoints 93, 147
Java packages
org.globalplatform 2
overview 4
visa.openplatform 2
Index
JCardManager 10, 185–187
as client application 4
as debugging tool 42, 80, 114–115, 130
interface 185
performing commands in 186
starting 185
starting the key file editor in 171
use in testing 42
JCRMI
client applications 42, 99–111
client project wizard 107
client projects 107–108
JCRMI applets 42, 99–111
adding to a project 104
debugging 108–111
wizard 105
K
key file editor 171
interface 171
starting from Eclipse 171
starting from JCardManager 171
key lengths 19
L
libraries 6, 159–160
creating 159
debugging 81, 131
using 159
loading
applets 41, 97, 152
logical channels 186
M
midlet
project creation 119–120
midlet test application 80, 130
mobile simulator 10
operating the 3G simulator 95
starting 27
use in debugging 42, 91–97
use in testing 42
versions 92, 146
O
OCF
client applications 42, 115
client projects 115
See also WTK-OCF bridge
OP 2.0.1’ specification 2
Open Platform. see GlobalPlatform
opencard framework (OCF) 2
199
org.globalplatform package 2
OTA
events 28
interpreter 8, 29
minimum security for USIM toolkit applets 89,
141
profiles 173–183
P
packages 4
AIDs 6
See also Java packages
personalization scripts. See ATF personalization
scripts
PIXs 6
profiles
OTA 173–183
projects 10
creating http midlet 156–157
creating Java Card 77–83
creating JCRMI client 107–108
creating midlet 119–120
creating OCF clients 115
creating SCWS 127–134
debugging 94–95, 109–111, 114–115, 147–
151
overview 6
R
remote object
creating interface 99–104, 106
preverification 103
wizard 100–103, 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, 163–165
interface 164
starting 163
script files 9, 41, 163–165, 186–187
atf. See ATF personalization scripts
gxsc 160, 186
xml 186
secure channel 2
GP (for JCRMI applets) 106
200
Index
serial cable 1
servlet
example 134–154
servlets
debugging 145–150
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 145–150
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 6–8, 10, 28
debugging 42, 80, 91, 130, 145
testing 42
TPDU 7, 29
traces 187
U
USIM toolkit applets 77–98
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
Java Card applet 114
Java Card project 77
JCRMI applet 105
JCRMI/OCF client project 107
OCF client project 115
remote object 100–103
WTK-OCF bridge 29
X
xml
script files 186
script player 187

Developer Suite Getting Started Guide

Transcription

Similar documents

bowling challenge - Friends of We Care

Succeeding in Mobile Advertising

Time Sheet Reminder

Writing documentation with Asciidoctor

Howl`s Moving Castle

Important Performance Analysis, SWOT, EFAS, IFAS

HOME DEVELOPMENT MUTUAL FUND Corporate - Pag

The Curious Contraption.indd

Quick Start Guide for Power Users (Java)

Game Post Mortems