C H A P T E R 4 - Running Applets in an Emulated Card Environment

C H A P T E R 4

Running Applets in an Emulated Card Environment

The Java Card platform Workstation Development Environment ("Java Card Workstation Development Environment" or "Java Card WDE") tool allows the simulated running of a Java Card applet as if it were masked in ROM. It emulates the card environment.

The Java Card WDE is not an implementation of the Java Card virtual machine. It uses the Java virtual machine to emulate the Java Card RE. Class files that represent masked packages must be available on the classpath for the Java Card WDE.

For the version 2.2.2 release of the Java Card platform reference implementation, Java Card WDE adds support for Java Card Remote Method Invocation (Java Card RMI).

Some of the Java Card RE features that are not supported by Java Card WDE are:

package installation

persistent card state

firewall

transactions

transient array clearing

object deletion

applet deletion

package deletion

The Java Card WDE tool uses the jcwde.jar, api.jar (with cryptography extensions) and apduio.jar files. The main class for Java Card WDE is com.sun.javacard.jcwde.Main. A sample batch and shell script are provided to start Java Card WDE.

Preparing to Run Java Card WDE

Before you run the Java Card WDE tool, you must ensure that the environment variables are set appropriately and the applets to be configured are listed in a configuration file.

Setting Environment Variables

To set the environment variables correctly, refer to Setting Environment Variables for the Solaris or Linux Platform or Setting Environment Variables for Microsoft Windows Platform.

Configuring the Applets in the Java Card WDE Mask

The applets to be configured in the mask during Java Card WDE simulation need to be listed in a configuration file that is passed to the Java Card WDE as a command line argument. Also, the CLASSPATH environment variable needs to be set to reflect the location of the class files for the applets to be simulated. In this release, the sample applets are listed in a configuration file called jcwde.app. Each entry in this file contains the name of the applet class, and its associated AID.

The configuration file contains one line per installed applet. Each line is a white space(s) separated {CLASS_NAME AID} pair, where CLASS NAME is the fully qualified Java name of the class defining the applet, and AID is an Application Identifier for the applet class used to uniquely identify the applet. AID may be a string or hexadecimal representation in form:

0xXX[:0xXX]

where the construct 0xXX is repeated as many times as necessary.

Note that AID should be 5 to 16 bytes in length.

For example:

com.sun.javacard.samples.wallet.Wallet 0xa0:0x0:0x0:0x0:0x62:0x3:0x1:0xc:0x6:0x1

Note - The installer applet must be listed first in the Java Card WDE configuration file.

If you write your own applets for public distribution, you should obtain an AID for each of your packages and applets according to the directions in Section 4.2 of the Virtual Machine Specification for the Java Card Platform, Version 2.2.2, and in the ISO 7816 Specification Parts 1-6.

Running the Java Card WDE Tool

The general format of the command to run the Java Card WDE and emulate the Java Card RE is:

jcwde [-help] [-verbose] [-p port] [-t0] [-version] [-nobanner] <config-file>

TABLE 4-1 describes the command line options for Java Card WDE.

TABLE 4-1 Command Line Options for Java Card WDE
Option	Description
`<`config-file`>`	The configuration file described above.
`-help`	Prints a help message.
`-nobanner`	Suppresses all banner messages.
`-p` port	Allows you to specify a TCP/IP port other than the default port.
`-t0`	Runs T=0 single interface only.
`-verbose`	Prints more verbose output.
`-version`	Prints the Java Card WDE version number.

Java Card WDE starts listening to APDUs in T=1 as the default format, unless otherwise specified, on the TCP/IP port specified by the -p port parameter for contacted and port+1 for contactless. The default port is 9025.