Chapter   3

Development Kit Samples and Demonstrations

This release includes several demonstration programs which illustrate the use of the Java Card API, and a scenario of post-manufacture installation.

The Demonstrations

Version 2.2.1 of the Development Kit includes the following demonstration programs:

Demo 1 (demo1)—illustrates the use of packages masked into card ROM: JavaPurse, JavaLoyalty, Wallet and SampleLibrary.
Demo 2 (demo2)—downloads these packages into the C-language Java Card RE using the installer applet: JavaPurse, JavaLoyalty, Wallet, SampleLibrary, RMIDemo, SecureRMIDemo, and photocard. demo2 also exercises the JavaPurse, JavaLoyalty, and Wallet applets.
Demo 2 Cryptography Demo (demo2crypto)—is similar to demo2, except it uses a version of JavaPurse that uses a DES MAC algorithm.
Demo 3 (demo3)—illustrates the second time power-up of an already initialized mask. It uses the card state file created by demo2.
Java Card RMI Demo (RMIDemo)—demonstrates the use of the Java Card platform Remote Method Invocation (“Java Card RMI”) API. The basic example used is a program that manages a counter remotely, and is able to decrement, increment, and return the value of an account. On cref, RMIDemo uses the card state file created by demo2.
Logical Channels Demo (channelDemo)—demonstrates the use of logical channels which allows selecting multiple applets at the same time.
Object Deletion Demo 1 (odDemo1)—demonstrates applet and package deletion, as well as the object deletion mechanism which removes unreachable objects.
Object Deletion Demo2 (odDemo2)—demonstrates package deletion and checks that persistent memory has been returned to the memory manager.
Photo Card Demo (photocard)—demonstrates how you can store images in the large address space which is available in the 32-bit version of the reference implementation for the Java Card platform (“Java Card reference implementation”), version 2.2.1.
Secure Java Card RMI Demo (SecureRMIDemo)—is similar to RMIDemo, but demonstrates additional security at the transport level. It also uses the card state file created on cref by demo2.

Directories and Files in the demo Directory

The directories and files for the Development Kit demonstrations are described in TABLE 3 and TABLE 4.

Several of the Development Kit demonstrations use the output generated by the Demo 2 demonstration. These demonstrations are stored in subdirectories of demo2. The demo2 directory also contains the files that the demos need to run JavaPurse, JavaLoyalty, and Wallet. The demonstrations and subdirectories contained in demo2 are described in TABLE 4.

Preliminaries

All demo programs are pre-built. If you make any changes to the demos, the following sections describe how you can rebuild them.

Building Samples

A script file is provided to build the samples. To understand what is going on behind the scenes, it is very instructive to look at the script.

The script file is $JC_HOME/samples/build_samples (for a Solaris or Linux platform installation) or %JC_HOME%\samples\build_samples.bat (for a Microsoft Windows 2000 platform installation).

Running the Script

The command line syntax for the script is:

build_samples [options] 

TABLE 5 describes the possible values for options.

Setting Environment Variables

The build_samples script uses the environment variables JC_HOME and JAVA_HOME. To correctly set these environment variables, refer to "Setting Environment Variables for the Solaris or Linux Platform" or "Setting Environment Variables for Microsoft Windows 2000 Platform".

Building the Sample Applets

Run the script without parameters to build the samples:

build_samples  

  Preparing to Compile the Sample Applets

Compiling the Sample Applets

The next step is to compile the Java sources for the sample applets. For example, from the samples directory, issue the following command:

Solaris or Linux platform:

javac -g -classpath ./classes:../lib/api.jar:../lib/installer.jar src/com/sun/javacard/samples/HelloWorld/*.java  

Microsoft Windows 2000 platform:

javac -g -classpath .\classes;..\lib\api.jar;..\lib\installer.jar src\com\sun\javacard\samples\HelloWorld\*.java  

where:

api.jar contains the Java Card API
installer.jar contains the installer applet
the classes directory is required for packages that import other sample packages

Converting the Class Files

The next step is to convert the Java class files.

Conversion parameters for each package are specified in a configuration file.

For example, a configuration file contains items such as:

-out EXP JCA CAP 
-exportpath . 
-applet  0xa0:0x0:0x0:0x0:0x62:0x3:0x1:0xc:0x1:0x1 
com.sun.javacard.samples.HelloWorld.HelloWorld 
com.sun.javacard.samples.HelloWorld 
0xa0:0x0:0x0:0x0:0x62:0x3:0x1:0xc:0x1 1.0 

In this example, the converter will output three kinds of files: export (*.exp), CAP (*.cap) and Java Card Assembly (*.jca) files.

Refer to the “Convert samples” section of the script file to see the detailed converter tool steps.

For more information about the converter tool, refer to Chapter 5, "Converting Java Class Files.”

Running scriptgen to Generate Script Files

Generate script files for apdutool using the scriptgen tool. This step must be done for each package to be downloaded. For example:

scriptgen -o JavaLoyalty.scr ./classes/com/sun/javacard/samples/JavaLoyalty/javacard/JavaLoyalty.cap  

The new scripts are included into the demonstration scripts. For example, demo2.scr file is composed of these scripts:

Header.scr—a script that initializes the session
SampleLibrary.scr, JavaLoyalty.scr, JavaPurse.scr, Wallet.scr, RMIDemo.scr, SecureRMIDemo.scr, photocard.scr—package installation scripts
AppletTest.scr—a script that creates the JavaLoyalty, JavaPurse, Wallet, JavaPurseCrypto, RMIDemo, and SecureRMIDemo applets so that you can see each of them invoked when the simulation is run. AppletTest.scr also excercises the JavaLoyalty.scr, JavaPurse.scr, and Wallet.scr applets.
Footer.scr—a script that terminates the session

Running the Demonstrations

The following sections describe the Development Kit demonstrations and how to run them.

A demonstration can use a card EEPROM image created by another demonstration. The cref command line option -o <filename> lets you save the EEPROM image into a file after a simulated card session. The option -i <filename> restores the image from the file for a new card session. For more information, see Chapter 11, "Using the Java Card Reference Implementation”.

Demo 1

The Demo 1 demonstration, demo1, exercises the JavaPurse, JavaLoyalty, and Wallet applets by simulating transactions where amounts are credited and debited from the card. The demonstration begins by powering up the Java Card technology-enabled smart card and creating the applets JavaPurse, JavaLoyalty, and Wallet.

The JavaPurse applet demonstrates a simple electronic cash application. The applet is selected and initialized with various parameters such as the Purse ID, the expiration date of the card, the Master and User PINs, maximum balance, and maximum transaction. Transaction operations perform the actual debits and credits to the electronic purse. If there is a configured loyalty applet assigned for the CAD performing the transaction JavaPurse communicates with it to grant loyalty points. In this case, JavaLoyalty is the provided loyalty applet.

A number of transaction sessions are simulated where amounts are credited and debited from the card. In an additional session, transactions with intentional errors are attempted to demonstrate the security features of the card.

The JavaLoyalty applet is designed to interact with the JavaPurse applet, and to demonstrate the use of shareable interfaces. The shareable JavaLoyaltyInterface is defined in a separate library package, com.sun.javacard.SampleLibrary.

JavaLoyalty is a minimalistic loyalty applet. It is registered with JavaPurse when a Parameter Update APDU command with an appropriate parameter tag is executed, and when the AID part of the parameter corresponds to the AID of the JavaLoyalty applet. The applet contains a grantPoints method. This method implements the main interaction with the client. When the first 2 bytes of the CAD ID in a request by a JavaPurse transaction correspond to the 2 bytes of CAD ID in the corresponding Parameter Update APDU command, the grantPoints method implementing the JavaLoyaltyInterface is requested.

JavaLoyalty maintains the balance of loyalty points. The applet contains methods to credit and debit the account of points and to get and set the balance.

The Wallet applet demonstrates a simplified cash card application. It keeps a balance, and exercises some of the Java Card API features such as the use of a PIN to control access to the applet.

  Running demo1

demo1 runs in the Java Card WDE.

Demo 2

The Demo 2 demonstration, demo2, illustrates downloading Java Card packages onto the card. This demonstration contains the installer applet in the mask image. After the card is powered up, the Photocard, SampleLibrary, JavaPurse, JavaLoyalty, Wallet, RMIDemo, and SecureRMIDemo packages are downloaded. The commands from demo1 are repeated. Finally, the card is powered down.

  Running demo2

demo2 runs in the C-language Java Card RE because the Java Card WDE is not able to support the downloading of CAP files.

Demo 3

The Demo 3 demonstration, demo3, illustrates the capabilities of a Java Card technology-enabled smart card to save its state across sessions. After running demo2, the state of the card can be saved. This card state must be used as the initial state for running demo3.

  Running demo3

demo3 should be run after demo2. demo3 runs in the C-language Java Card RE because the virtual machine state must be restored after the initial run.

Java Card RMI Demo

Every Java Card RMI application consists of two parts: a card applet and a client program communicating with it. In this case, the RMIDemo applet is installed in EEPROM image when you run demo2 on CREF. On Java Card WDE, the applets are included in the simulated mask.

The client framework uses the OCF framework, version 1.2 (files base-core.jar, and base-opt.jar), to communicate with C-language Java Card RE. The OCF settings are stored in file opencard.properties. The file opencard.properties is located in the demo\demo2\rmi directory.

Note that OCF searches for this file in the following locations:

[java.home]/lib/opencard.properties
[user.home]/.opencard.properties
[user.dir]/opencard.properties
[user.dir]/.opencard.properties

where [java.home], [user.home], and [user.dir] correspond to the Java system properties.

The RMIDemo uses the card applet PurseApplet, the Purse interface and its implementation PurseImpl. These classes reside in the package com.sun.javacard.samples.RMIDemo. The client-side program PurseClient resides in the package com.sun.javacard.clientsamples.purseclient.

The Purse interface describes the supported functionality: methods for getting the account balance, debiting and crediting the account, and getting and setting an account number. The interface also defines the constants used for error reporting. The PurseImpl class implements Purse.

The card applet PurseApplet creates and registers instances of the dispatcher and the Java Card RMI service.

The client-side program, PurseClient, represents a simple Java Card RMI client and uses the Open Card Framework (OCF) as the client side framework. The program initializes the OCF, creates the Java Card RMI Connect instance, and selects the Java Card applet (in this case, the PurseApplet). The program then gets the initial reference from PurseApplet (the reference to an instance of PurseImpl) and casts it to the Purse interface type. This allows PurseImpl to be treated as a local object. The program can then exercise the card by debiting and crediting different amounts, and by setting and getting the account number. The program demonstrates error handling by intentionally attempting to set an account number of incorrect size. This will cause a UserException to be thrown with the appropriate error code.

The client part of the RMIDemo can be run without parameters or with the -i parameter:

If the demo is run without parameters, remote references are identified using the class name of the remote object.
If the demo is run with the -i parameter, remote references are identified using the list of remote interfaces implemented by the remote object.

For more information on these formats, see Chapter 8 of the Runtime Environment Specification for the Java Card™ Platform, Version 2.2.1 (Sun Microsystems, Inc., 2003).

  Running the Java Card RMI Demo

The RMIDemo can be run on either C-language Java Card RE or Java Card WDE. On C-language Java Card RE, RMIDemo can be run only after demo2 has successfully completed.

The RMIDemo applet can be run in Java Card WDE by listing it on the first line of the applet configuration file jcwde_rmi.app.

If the run is successful, the output in the file will be the same as contained in file rmidemo.scr.expected.out.

To Run RMIDemo on the C-Language Java Card RE:

To Run RMIDemo on Java Card WDE:

Secure Java Card RMI Demo

The secure Java Card RMI demo, SecureRMIDemo, can be thought of as a version of the RMIDemo with an added security service. SecureRMIDemo uses the card applet SecurePurseApplet, the Purse interface and its implementation SecurePurseImpl, and a definition of the security service MySecurityService. These classes reside in the package com.sun.javacard.samples.SecureRMIDemo. The demo also uses the client-side program SecurePurseClient and the specialized card accessor SecureOCFCardAccessor. These classes reside in the package com.sun.javacard.clientsamples.securepurseclient.

The Purse interface is similar to the interface used in the non-secure case, however, there is an extra constant: REQUEST_DENIED. This constant is used to report situations where the client tries to invoke a method that it is not allowed to access.

The MySecurityService class is a security service that is responsible for ensuring data integrity by verifying checksums on incoming commands and attaching checksums to outgoing commands. The program also requires the client to authenticate itself as the principal application provider or principal cardholder by sending a two-byte PIN.

The implementation of Purse, SecurePurseImpl, is similar to the non-secure case, however, at the beginning of each method call, there is a call to the security service which ensures that the business rules are satisfied and that the data is not corrupted.

The applet SecurePurseApplet is similar to the non-secure case, but it also creates and registers an instance of MySecurityService.

The client-side program, SecurePurseClient, is similar to the non-secure case, but instead of a generic card accessor, it uses its own implementation: SecureOCFCardAccessor, which performs additional pre- and post-processing of data and supports the additional command authenticateUser.

SecurePurseClient also requires verification of the user. After the applet is inserted, a PIN must be given to the card-side applet by calling authenticateUser on SecureOCFCardAccessor.

When authenticateUser is called, SecureOCFCardAccessor prepares and sends the following command:

On the card side, MySecurityService processes the command. If the PIN is correct, then the appropriate flags are set in the security service and a confirmation response is returned to the client. Once authentication is passed, the client program receives the balance, credits the account, and again receives the balance. The program demonstrates error handling when the client attempts to debit a number of units from the account. This will cause the program to throw a UserException with the code REQUEST_DENIED.

As with RMIDemo the client part of the SecureRMIDemo can be run without parameters or with the -i parameter:

If the demo is run without parameters, remote references are identified using the class name of the remote object.
If the demo is run with the -i parameter, remote references are identified using the list of remote interfaces implemented by the remote object.

For more information on these formats, see Chapter 8 of the Runtime Environment (JCRE) Specification for the Java Card™ Platform, Version 2.2.1.

  Running the Secure Java Card RMI Demo

SecureRMIDemo can be run on either the C-language Java Card RE or Java Card WDE. The SecureRMI demo applet is installed in the EEPROM image when you run demo2.

The SecureRMIDemo can be run in Java Card WDE by listing it on the first line of the applet configuration file jcwde_securermi.app.

If the run is successful, the output in the file will be the same as contained in file securermidemo.scr.expected.out.

To Run SecureRMIDemo on the C-Language Java Card RE:

To Run SecureRMIDemo on Java Card WDE:

Object Deletion Demo 1

The Object Deletion Demo 1, odDemo1, demonstrates the object deletion mechanism, applet deletion, and package deletion. The odDemo1 demonstration has three parts:

odDemo1-1.scr demonstrates the object deletion mechanism and verifies that memory for objects referenced from transient memory of type CLEAR_ON_DESELECT has been reclaimed after an applet is deselected.

odDemo1-1.scr does not depend on any other demo. The final state of cref memory must be saved to a file for odDemo1-2.scr to use.

odDemo1-2.scr demonstrates the object deletion mechanism and verifies that memory for objects referenced from transient memory of type CLEAR_ON_RESET has been reclaimed after card reset.

The odDemo1-2.scr demo must be run after odDemo1-1.scr because the initial state of cref must be the same as its final state after running odDemo1-1.scr. After running odDemo1-2.scr, the final state of cref must be saved to a file so it can be used by odDemo1-3.scr.

odDemo1-3.scr performs applet deletion, package deletion, and employs the AppletEvent.uninstall method to uninstall an applet. The demo verifies that all transient memory of type CLEAR_ON_RESET and CLEAR_ON_DESELECT has been returned to the memory manager. The demo also demonstrates the use of the AppletEvent.uninstall() method.

The odDemo1-3.scr demo must be run after odDemo1-2.scr because the initial state of cref must be the same as its final state after running odDemo1-2.scr.

  Running odDemo1

odDemo1 runs only in the C-language Java Card RE. This is because the Java Card WDE does not support the object deletion mechanism, applet deletion, or package deletion.

Object Deletion Demo2

The Object Deletion Demo 2, odDemo2, demonstrates package deletion and checks that persistent memory has been returned to the memory manager. This demo has one script: odDemo2.scr. You do not have to run odDemo1 to run odDemo2.

  Running odDemo2

odDemo2 runs only in the C-language Java Card RE. This is because the Java Card WDE does not support the object deletion mechanism, applet deletion, or package deletion.

Logical Channels Demo

The Logical Channels Demo, lcdemo, demonstrates the behavior of Java Card technology-based logical channels by showing how two applets, which interact with each other, can each be selected for use at the same time.

The logical channels demo mimics the behavior of a wireless device connected to a network service. A connection manager tracks whether the device is connected to the service and whether the connection is local or remote. While it is connected, the user’s account is debited on a unit of time basis; the debit rate is based on whether the connection is local or remote. The demo employs two applets to simulate this situation: the ConnectionManager applet manages the connection while the AccountAccessor applet manages the account.

When the user turns on the device, the ConnectionManager applet is selected. Every unit of time, the terminal sends a message containing the area code to the card. When the user wants to use the service, the AccountAccessor applet is selected on another logical channel so that the terminal can query the balance. The AccountAccessor can return the balance only if the ConnectionManager is active. The ConnectionManager applet sets the connection and tracks the connection status. Based on the value of an area code variable, the ConnectionManager determines whether the connection is local or remote. AccountAccessor uses this information to debit the account at the appropriate rate. The connection is disabled when the user completes the call or when the account is depleted.

  Running the Logical Channels Demo

The logical channels demo runs only in the C-language Java Card RE. No sample scripts or demos are provided to demonstrate this functionality on Java Card WDE.

Demo 2 Cryptography Demo

The Demo 2 Cryptography Demo, demo2crypto, is similar to demo2, except that it employs a version of JavaPurse that uses a DES MAC algorithm. This version of JavaPurse is called JavaPurseCrypto. All other applets are exactly the same as were used in demo2.

A DES MAC is a cryptographic signature that uses DES encryption on all or part of a message (APDU). JavaPurseCrypto uses the DES MAC to verify several of the APDUs; that is, instead of zeros in the signature currently in JavaPurse, there will be a real signature that can be programmatically signed and verified. Other programs that interact with JavaPurseCrypto (such as JavaLoyalty and Wallet) are not affected since all signing/verifying of the signature will occur only within JavaPurseCrypto.

  Running the demo2crypto Demo

demo2crypto runs in the C-language Java Card RE because the Java Card WDE is not able to support the downloading of CAP files.

Photo Card Demo

The Photo Card Demo, photocard, illustrates how you can use the large address space available in the 32-bit version of the Java Card platform reference implementation, version 2.2.1. The demo uses the large address space of the smart card’s EEPROM memory to store up to four GIF images. The images are included with the demo.

Running the Photo Card Demo

The Photo Card demo can be run only after demo2 has successfully completed. This is because the Photo Card applet is downloaded with demo2.scr.

Development Kit User's Guide for the Binary Release with Cryptography Extensions Java Card Platform, Version 2.2.1

Copyright © 2003 Sun Microsystems, Inc. All rights reserved.