How to write a Java Card applet: A developer's guide

Learn the programming concepts and major steps of creating Java Card applets

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

Java Card

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

ISO 7816


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:

  1. Specify the functions of the applet
  2. Request and assign AIDs to both the applet and the package containing the applet class
  3. Design the class structure of the applet programs
  4. 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 short and 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.

Specifying AIDs

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)

5 bytes

0 to 11 bytes

Table 1. AID format

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.

Package AID
RID0xF2, 0x34, 0x12, 0x34, 0x565 bytes
PIX0x10, 0x00, 0x003 bytes
Applet AID
RID0xF2, 0x34, 0x12, 0x34, 0x565 bytes
PIX0x10, 0x00, 0x013 bytes
Table 2. Fictitious AIDs for the wallet applet and the applet package

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 javacard.framework.Applet:

Method summary

deselect ()

Called by the JCRE to inform the currently selected applet that another (or the same) applet will be selected.
public Shareable

getShareableInterfaceObject (AID client AID, byte parameter)

Called by the JCRE to obtain a sharable interface object from this server applet on behalf of a request from a client applet.
public static void

install (byte[] bArray, short bOffset, byte bLength)

The JCRE calls this static method to create an instance of the Applet subclass.
public abstract void

process (APDU apdu)

Called by the JCRE to process an incoming APDU command.

protected final void

register ()

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.

protected final void

register (byte[] bArray, short bOffset, byte bLength)

This method is used by the applet to register this applet instance with the JCRE and to assign the specified AID in the array bArray to the applet instance.
public boolean

select ()

Called by the JCRE to inform this applet that it has been selected.

protected final boolean

selectingApplet ()

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.

Table 3. Public and protected methods defined in the class javacard.framework.Applet

The class 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 select() and 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.

The 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.

Since the 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.

Command APDU

Mandatory headerOptional body
CLAINSP1P2LcData fieldLe
  • CLA (1 byte): Class of instruction --- indicates the structure and format for a category of command and response APDUs
  • INS (1 byte): Instruction code: specifies the instruction of the command
  • P1 (1 byte) and P2 (1 byte): Instruction parameters -- further provide qualifications to the instruction
  • Lc (1 byte): Number of bytes present in the data field of the command
  • Data field (bytes equal to the value of Lc): A sequence of bytes in the data field of the command
  • Le (1 byte): Maximum of bytes expected in the data field of the response to the command

Response APDU

Optional bodyMandatory trailer
Data fieldSW1SW2
  • Data field (variable length): A sequence of bytes received in the data field of the response
  • SW1 (1 byte) and SW2 (1 byte): Status words -- denote the processing state in the card
Table 4. Command and response APDU formats

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.

  • The SELECT command 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.

Structurally, the 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.

1 2 3 Page 1
Page 1 of 3