This article walks you through the process of creating a simple electronic wallet applet and provides directions for building an applet and constructing its code. If you need a refresher on the basics of Java Card technology, refer to the March 1998 Java Developer column, "Understanding Java Card 2.0," which provides an overview of smart cards and describes the system architecture, the APIs, and the runtime environment of the Java Card technology. For consistency, this article uses the same wallet applet example as was used in the March 1998 column. However, the wallet applet we'll use in this article has been updated to reflect changes to the APIs in Java Card 2.1. In addition, while the previous article served as an overall introduction to the Java Card technology, this article focuses on writing applets for Java Card 2.1.
Java Card basics
For the purpose of this article, the term
denotes a Java Card technology-enabled smart card. Java Card technology allows applets written in the Java language to be executed on a smart card. It defines a
Java Card Runtime Environment
(JCRE) and provides
classes and methods
to help developers create applets. Applets run within the JCRE. The JCRE and APIs are modeled after the smart card specification
When a Java Card is inserted into a card acceptance device (CAD), the CAD selects an applet on the card and sends it a series of commands to execute. Each applet is identified and selected by its application identifier (AID). Commands such as the selection command are formatted and transmitted in the form of application protocol data units (APDUs). Applets reply to each APDU command with a status word (SW) that indicates the result of the operation. An applet can optionally reply to an APDU command with other data.
Architect the applet
As with any software application development, before sitting down and writing a Java Card applet, you should first go through a design phase. In this phase, you define the architecture of the applet.
Four steps comprise the applet-design phase:
- Specify the functions of the applet
- Request and assign AIDs to both the applet and the package containing the applet class
- Design the class structure of the applet programs
- Define the interface between the applet and the terminal application
In the following sections, we'll use the example of a wallet applet to take a detailed look at each of the steps in the applet-design process.
Specifying the functions of the applet
Our example wallet applet will store electronic money and support credit, debit, and check-balance functions.
To help prevent unauthorized use of the card, it contains a security algorithm. This algorithm requires the user to enter a PIN, a string of eight digits at most. The card user types his or her PIN on a keypad connected to the CAD. The security algorithm causes the card to lock after three unsuccessful attempts to enter the PIN. The PIN is initialized according to the installation parameters when the applet is installed and created.
The PIN must be verified before any credit or debit transaction can be executed.
For simplicity, let's say the card's maximum balance is 2,767, and that no credit or debit transaction can exceed 27. Thus, Java variables of type
byte can represent the wallet balance and the amount of each transaction, respectively.
*A real-world wallet applet would require a much more sophisticated security mechanism to prevent unauthorized access to the wallet.
Most applications with which you are familiar are named and identified by a string name. In Java Card technology, however, each applet is identified and selected by an AID. Also, each Java package is assigned an AID. This is because a package, when loaded on a card, is linked with other packages, which have already been placed on the card via their AIDs. This naming convention is in conformance with the smart card specification as defined in ISO 7816.
An AID is a sequence of bytes between 5 and 16 bytes in length. Its format is depicted in Table 1.
|Application identifier (AID)|
National registered application provider (RID)
Proprietary application identifier extension (PIX)
0 to 11 bytes
ISO controls the assignment of RIDs to companies, with each company obtaining its own unique RID from the ISO. Companies manage assignment of PIXs for AIDs.
The Java classes of the wallet applet are defined in a Java package. The fictitious AIDs for the wallet applet and the applet package are defined as illustrated in Table 2.
|RID||0xF2, 0x34, 0x12, 0x34, 0x56||5 bytes|
|PIX||0x10, 0x00, 0x00||3 bytes|
|RID||0xF2, 0x34, 0x12, 0x34, 0x56||5 bytes|
|PIX||0x10, 0x00, 0x01||3 bytes|
The package AID and the applet AID have the same RID value; their PIX values differ at the last bit.
Defining the class structure and method functions of the applet
A Java Card applet class must extend from the
javacard.framework.Applet class. This class is the superclass for all applets residing on a Java Card. It defines the common methods an applet must support in order to interact with the JCRE during its lifetime.
Table 3 lists the public and protected methods defined in the class
Called by the JCRE to process an incoming APDU command.
This method is used by the applet to register this applet instance with the JCRE and assign the default AID in the CAD file to the applet instance.
Called by the JCRE to inform this applet that it has been selected.
This method is used by the applet
method to distinguish the
command that selected this applet from all other
APDU commands that may relate to file or internal applet state selection.
javacard.framework.Applet provides a framework for applet execution. Methods defined in this class are called by the JCRE when the JCRE receives APDU commands from the CAD.
After the applet code has been properly loaded on a Java Card and linked with other packages on the card, an applet's life starts when an applet instance is created and registered with the JCRE's registry table. An applet must implement the static method
install() to create an applet instance and register the instance with the JCRE by invoking one of the two
register() methods. The
install()method takes a byte array as a parameter. This array contains the installation parameters for initializing or personalizing the applet instance.
An applet on a Java Card is in an inactive stage until it is explicitly selected. When the JCRE receives a
SELECT APDU command, it searches its internal table for the applet whose AID matches the one specified in the command. If a match is found, the JCRE prepares the new applet to be selected. This preparation process consists of two steps: First, if a currently-selected applet is present, the JCRE deselects it by invoking the
deselect() method. The applet performs any clean-up or bookkeeping work in the
deselect() method before it goes into the inactive stage. Then the JCRE invokes the
select() method to inform the new applet that it has been selected. The new applet performs any initialization necessary before it actually becomes selected. The applet returns
true to the
select() method if it is now ready to become active and to process subsequent APDU commands. Otherwise, the applet returns
false to decline its participation, and if so, no applet will be selected. The
javacard.framework.Applet class provides a default implementation for both the
deselect() methods. A subclass of the
Applet class may override these two methods to define the applet's behavior during selection and deselection.
Once an applet is selected, the JCRE forwards all subsequent APDU commands (including the
SELECT command) to the applet's
process() method. In the
process() method, the applet interprets each APDU command and performs the task specified by the command. For each command APDU, the applet responds to the CAD by sending back a response APDU, which informs the CAD of the result of processing the command APDU. The
process() method in class
javacard.framework.Applet is an abstract method: a subclass of the
Applet class must override this method to implement an applet's functions.
This command-and-response dialogue continues until a new applet is selected or the card is removed from the CAD. When deselected, an applet becomes inactive until the next time it is selected.
getShareableInterfaceObject method is intended for interapplet communication. It is invoked by a client applet to request a sharable interface object from the server applet. The default implementation of this method returns null. Unfortunately, a detailed discussion of object sharing and interapplet communication would be beyond the scope of this article.
SELECT APDU command is also forwarded to the
process() method, the
selectingApplet() method is used by the applet's
process() method to distinguish the
SELECT APDU command selecting this applet from all other
SELECT APDU commands that may relate to file or internal applet state selection.
Defining the interface between an applet and its terminal application
An applet running in a smart card communicates with the terminal application at the CAD using application protocol data units. In essence, the interface between an applet and its terminal application is a set of APDU commands that are agreed upon and supported by both the applet and the terminal application.
An APDU primer
This section provides a summary of APDU commands to get you started defining APDU commands for the wallet applet. (The details of the APDU protocol are specified in ISO 7816.)
APDU commands are always sets of pairs. Each pair contains a command APDU, which specifies a command, and a response APDU, which sends back the execution result of the command. In the card world, smart cards are reactive communicators -- that is, they never initiate communications, they only respond to APDUs from the outside world. The terminal application sends a command APDU through the CAD. The JCRE receives the command, and either selects a new applet or passes the command to the currently selected applet. The currently selected applet processes the command and returns a response APDU to the terminal application. Command APDUs and response APDUs are exchanged alternately between a card and a CAD.
Table 4 describes command and response APDU formats.
|Mandatory header||Optional body|
|Optional body||Mandatory trailer|
Defining APDU commands
A Java Card applet should support a set of APDU commands, comprising a
SELECT APDU command and one or more process APDU commands.
SELECTcommand instructs the JCRE to select the applet on the card.
- The set of process commands defines the commands the applet supports. These are defined in accordance with the functions of the applet.
Java Card technology specifies the encoding of the
SELECT APDU command. Applet developers are free to define the encoding of their process commands. However, process commands must comply with the structure outlined above.
SELECT command and process commands are pairs of command and response APDUs.
For each command APDU, the applet should first decode the value of each field in the command. If the optional data fields are included, the applet should also determine their format and the structure. Using these definitions, the applet knows how to interpret each command and read the data. It then can execute the task specified by the command.