A Java Card Primer: Part 2—A Java Card Example

Date: Jan 25, 2002

Article is provided courtesy of Sams.

Return to the article

In this second of two articles on the Java Card platform, Mauro Marinilli shows you a simple yet complete example of a Java
Card applet development.

In order to run the code in this example, it is necessary to have installed the Java Card Development Kit Version 2.1.2 or higher from Sun. The kit is
available for downloads at http://www.javasoft.com/products/javacard/.

As for the scripts, you will use simple Windows scripting that can be adapted easily to any Unix-like command-line environment.

A Demonstrative Applet
Listing 1 shows an example of a Java Card applet. It is very simple, but will serve the purpose of illustrating the deployment of Java Card applets from
the Java source code to the final data transfer into the chip card.

To deploy your applet, follow these steps:

1. Write the Java source code, and compile it successfully.

2. Run the converter tool provided with the development kit, which obtains a CAP file.

3. Convert the CAP file in a sequence of low-level APDU commands to install the applet onto the card.

Listing 1 shows the CardTest applet. It is only a demonstrative applet— it does not perform any useful task or use any standard APDU type in the
processing. Nevertheless, it helps you follow all the main steps from the source development to a basic, on-card applet installation.

Listing 1. The CardTest Applet Class

package com.marinilli;
import javacard.framework.*;
/**
* An example Java Card Applet
* This applet writes back dummy byte sequences.
* It shows the Java Card applet development process only.
*
* @author Mauro Marinilli
*/

public class CardTest extends Applet {

//standard APDU input offset values

public final static byte THIS_CLA = (byte)0x90;
public final static byte INITIALIZE_TRANSACTION = (byte)0x20;
public final static byte COMPLETE_TRANSACTION= (byte)0x22;
public final static byte INITIALIZE_UPDATE= (byte)0x24;
public final static byte COMPLETE_UPDATE= (byte)0x26;

// dummy byte sequences returned by this applet

private final static byte[] INIT_SEQUENCE = { (byte)0x1, (byte)0x2 };
private final static byte[] COMPLETE_SEQUENCE = { (byte)0x1, (byte)0x3 };
private final static byte[] INIT_UPDATE_SEQUENCE = { (byte)0x1, (byte)0x2, (byte)0x3 };
private final static byte[] COMPLETE_UPDATE_SEQUENCE = { (byte)0x1, (byte)0x1 };

/**
* Constructor.
* Only this class's install method can create the applet object.
*/
private CardTest() {
//perform some initialization here
// ...
register();//register this instance
}

/**
* Installs this applet.
* @param byteArray the array containing installation parameters
 * @param offset the starting offset in byteArray
* @param length the length in bytes of the parameter data in byteArray
*/
public static void install(byte[] byteArray, short offset, byte length) {
new CardTest();
}

/**
* Implementation of the standard method for processing an incoming APDU.
* @param apdu the incoming APDU
* @exception ISOException with ISO 7816-4 response bytes
*/
public void process(APDU apdu) {
byte buffer[] = apdu.getBuffer();

if (buffer[ISO7816.OFFSET_CLA] == THIS_CLA) {
switch (buffer[ISO7816.OFFSET_INS]) {
case INITIALIZE_TRANSACTION:
writeBack(apdu, INIT_SEQUENCE);
break;
case COMPLETE_TRANSACTION:
writeBack(apdu, COMPLETE_SEQUENCE);
break;
case INITIALIZE_UPDATE:
writeBack(apdu, INIT_UPDATE_SEQUENCE);
break;
case COMPLETE_UPDATE:
writeBack(apdu, COMPLETE_UPDATE_SEQUENCE);
break;
default:
ISOException.throwIt(ISO7816.SW_INS_NOT_SUPPORTED);
}
}
}

/**
* An example method that writes back a given byte array through the apdu.
*/
protected void writeBack(APDU apdu, byte[] bytes) {
byte buffer[] = apdu.getBuffer();

// set apdu for data output

apdu.setOutgoing();

apdu.setOutgoingLength( (short) (3) );

// output header
apdu.sendBytes( (short)0, (short) 3);
// writes data
apdu.sendBytesLong( bytes, (short) 0, (short) 0 );
}

Because we are interested in providing the overall picture, not in the details of Java Card programming, the proposed code in Listing 1 is not
discussed.

Development Steps
Listing 2 shows the commands to compile the example. Note the use of the -g option, which is needed because the converter tool determines the
local variable types by checking the LocalVariableTable attribute within the .class file. Such an attribute is generated only if the -g option is used.

Listing 2. Compiling the CardTest Applet

set JC_HOME=...
javac -g -classpath % JC_HOME%\lib\api21.jar CardTest.java

Then, when the CardTest.class file is produced, you need to transform it into a CAP file by using the converter utility, together with an optional input
file (called in the example CardTest.opt) that declares all input options for the conversion process. Such a file is shown in Listing 3.

Listing 3. Compiling the CardTest Applet

01 set _CLASSES=%JC_HOME%\lib\apduio.jar; . . .;%JC_HOME%\lib\api21.jar;%JC_HOME%\lib\capdump.jar;

02 xcopy /s %JC_HOME%\api21_export_files\*.* exp
03 java -classpath %_CLASSES% com.sun.javacard.converter.Converter -config CardTest.opt

Line 1 of Listing 3, for brevity, omitted to mention all the JAR libraries found in the /lib directory of the installed Java Card Development Kit. In line 2,
the export files for the standard libraries are copied into a temporary directory, from which you will access them from the -exportpath option in
Listing 4. EXP files are much like C header files—needed for linking and other utility purposes.
Listing 4. The Converter Input Options File Cardtest.opt

-out EXP JCA CAP

-exportpath exp
-applet 0x1:0x0:0x0:0x0:0x1:0x3:0x1:0x0:0x1:0x1 com.marinilli.CardTest
com.marinilli
0x1:0x0:0x0:0x0:0x1:0x3:0x1:0x0:0x1 1.0

The options file (listed in Listing 4) instructs the converter tool to produce EXP, JCA, and CAP files as output of the conversion. JCA files are pseudo-
assembly text files from which CAP files can be created (they are not used here). The -exportpath command-line switch defines where the required
EXP files (needed for linking libraries) are located. The -applet option defines the applet's AID and its java class. In this example, the AID is totally
invented. Finally, the package name, package AID, and major version, followed by a minor version (separated by a dot) are provided to the converter.

Sun also supplies a tool for viewing the contents of an EXP file. When invoking it, as in the following, it produces the text representation of the EXP
file created by the converter from the applet class file:

java -classpath %_CLASSES% com.sun.javacard.converter.Exp2Text -classdir com/marinilli

Such a file is reported in Listing 5.

Listing 5. The Human-Readable Representation of the CardApplet EXP File

export file { // com/marinilli

magic 00FACADE // in hex
minor_version 1
major_version 2
constant_pool_count 2
constant_pool {
Constant_Utf8_info {
tag 1
length 19
bytes com/marinilli
}
CONSTANT_Package_info {
tag 13
flags 0
name_index 0 // com/marinilli
minor_version 0
major_version 1
aid_length 9
aid 0x1:0x0:0x0:0x0:0x1:0x3:0x1:0x0:0x1
}
}
this_package 1
export_class_count 0
export_classes {
}
}

You still have to physically transfer the CAP file onto your smart card. Sun's development kit provides a utility for sending APDUs to the smart card.
The last step is to create the APDUs to be sent to the smart card. The installer itself has been implemented as an applet.

Using the follow command, you launch the script generator (the -nobeginend option avoids including the standard CAP Begin and CAP End APDU
commands that you have to customize later).

java -classpath %_CLASSES% com.sun.javacard.scriptgen.Main com\marinilli\javacard\test.cap -nobeginend

As output, you obtain the list of APDU commands (a sequence of bytes) that define your CAP file.

Modify this latter file by cutting the text header and footer, leaving only the APDU commands and other commands, as specified in Sun's
documentation.

Then, you obtain another generated file, given in input at a suitable CAD via the APDUtool, which installs your applet on the card in a three-step
sequence:

1. The standard installer applet (already resident on the card) is instructed to download the applet using an APDU sequence.

2. Data is transferred via APDUs to the installer applet that writes it in memory.

3. Finally, always using the installer applet, you create an instance of your newly downloaded class that is ready for execution.

There are also deployment options for Java Card applets, such as ROM applets.

Conclusion
This article discussed the Java Card platform in some detail. The interested reader can compile the class source code here, or visit the Sun Java Card
Web site for more information.
Any feedback on the topics discussed here is warmly welcome. Please contact me through my Web site at http://www.marinilli.com/.

© 2022 Pearson Education, Informit. All rights reserved.

800 East 96th Street, Indianapolis, Indiana 46240