JavaA Java Card Primer, Part 1

A Java Card Primer, Part 1 content and product recommendations are editorially independent. We may make money when you click on links to our partners. Learn More.

To begin, I would like to offer some background on smart cards, for which Sun Microsystems introduced its Java Card technology. This advance has made it easier for high-level programmers to start writing code even for smart cards that were restricted to a machine-level specific language. And with this convenience and ease, I am sure there will be more ideas and applications to come to market to really take us into the Twenty-first century.

Overview of Smart Cards

Smart cards are also called chip cards or integrated circuit cards. The integrated circuit is incorporated in the credit-card-size plastic substrate. The integrated circuit performs the logic of manipulating or processing the data.

Basic Card Types

  • Memory cards: They are embedded with a memory chip to store small amounts of data. They do not have a processor to provide intelligence. The simple data processing is done by burned programmed logic and circuitry logic, which has obviously restricted functionalities.
  • Microprocessor cards: They come with a processor.
  • Contact cards: Card must be inserted in some device to communicate.
  • Contactless cards: These types of cards don’t need a CAD. They communicate using electromagnetic fields.

Smart Card Communication Model

Smart Cards are inserted into a CAD (Card Acceptance Device). The CAD is connected to some computer, where the applications that reside are known as host applications. These communicate with the applet downloaded or masked in cards. The host application sends commands to the applets in the smart cards. These commands are known as Command APDUs (Application Protocol Data Unit). The applet in the smart card responds by sending response APDUs.

Command APDU Structure

Mandatory Header

Optional Body






Data field


Response APDU Structure

Optional Body

Mandatory Trailer

Data Field



Java Card Technology

Java Card technology provides the smallest Java platform for memory-constrained devices such as smart cards.

Basics of the Java Card

A Java Card means a smart card that is enabled to work with Java Card Technology.

Courtesy of Sun Microsystems

What is Java Card Technology? Java Card Technology allows applets written in Java language to be executed on smart cards. In whole Java Card Technology provides JCRE (Java Card Runtime Environment) together with other classes and APIs for developers to create applets to be executed on smart cards.

Java Card and Card Application Device

  • CAD accepts Java Card.
  • Selects an applet and sends it a series of commands to execute.
  • Each Applet is identified and selected by its AID (Application Identifier).
  • Commands are formatted and transmitted in the form of APDU (Application Protocol Data Units).
  • Status Words: Applets reply to each APDU commands as status words (SW). Applets can optionally reply to an APDU command with other data.

Applet Designing

  1. Specify the working functionality of the applet.
  2. Requesting and assigning AIDs to both the applet and the packages containing the applet class.
  3. Design the class structure of the applet program.
  4. Define the interface between the applet and the terminal application.

I’ll use the example of wallet applet and try to explain everything using this single example.

Specifying the Functions of the Applet

Since here my intention is to give you a quick start I will keep things as simple as possible.

The intent of e-wallet example is to provide the means of having electronic money. The wallet would also have functionalities to credit, debit and check the balance. The wallet is secured with a PIN. To provide simplicity, I would use a short and byte data type since for large data types we have to employ other techniques that I don’t want to discuss here. So we assume that our e-wallet can store a maximum of $32.767 and can debit/credit the maximum of $127.

API Specification

Usually the applications and packages are identified by names but in Java Card technology the packages and the applets are identified with their ID known as Application Identifier or AID. This is because when the package, masked in ROM of smart cards, is linked with other packages already loaded in ROM with their own AID.

An AID is a sequence of bytes between 5 and 16 bytes in length. Its format is:

Application Identifier (AID)

National Registered application provider (RID)

Proprietary application identifier extension (PIX)

5 bytes

0 to 11 bytes

Companies obtain RID from ISO (the International Organization for Standardization). The companies themselves manage PIX AID.

Wallet Package and Applet AID

Package AID





0xF2, 0x34, 0x12, 0x34, 0x56

5 bytes


0x10, 0x00, 0x00

3 bytes


Applet ID





0xF2, 0x34, 0x12, 0x34, 0x56

5 bytes


0x10, 0x00, 0x01

3 byes

Functionalities of Methods

An applet class that you’ll develop must extend a javacard.framework.Applet class.

Your code should look like this:

import  javacard.framework.*; public class Wallet extends Applet {}

Methods and Functionalities of the javacard.framework.Applet Class



public void 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 paramter )


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.

public boolean select( )

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



Architecture of the Class

Applet verified by the off-card VM and then loaded on the Java card.

The Applet is linked with other packages already existing on the Java Card.

The actual working of an applet starts after it is instantiated and registered with the JCRE’s registry table.

Instantiation and Registration

The applet is instantiated by implementing:

install( ) method. You can pass an array of byte to the install( ) method as a parameter for customized initialization. This array contains the installation parameter for initializing.

The install( ) method is called by the JCRE:

The registration of the instance with the JCRE is done by invoking one of the two register( ) methods.

The register( ) method is called by the applet itself to get itself registered with the JCRE. The register( ) method is defined in the javacard.framework.Applet class.

The Code

import  javacard.framework.*; public class Wallet extends Applet {          private Wallet (byte [ ] bArray, short boffset, byte bLength) {     pin  = new OwnerPIN( PIN_TRY_LIMIT, MAX_PIN_SIZE );     // the installation parameters contain the PIN initialization       value  pin.update(bArray, boffset, bLength );     register( );}  // end of the constructor     public static void install(byte [ ] bArray, short boffset, byte bLength)  {               // create a Wallet applet instance               new Wallet (bArray, boffset, bLength);    } // end of the install method }

Applet Selection Procedure: select( ) Method

Until now, an applet on the Java Card is in an inactive stage, until it is explicitly selected. When a JCRE receives a SELECT APDU command, it searches its internal table for the applet whose AID matches the one specified in the command. If the match is found, the JCRE prepares a new applet to be selected. This preparation process consist of two steps:

First, if a currently-selected applet is present, the JCRE deselects it by invoking the deselect( ) method. The applet performs any bookkeeping or clean-up 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.frameword.Applet class provides the default implementation of these two methods, i.e., select( ) and deselect( ); but any subclass can override these methods to define the applet’s behavior during selection and deselection.

Function of process( ) Method

After this SELECTion of an applet, the JCRE forwards all the command APDU to the process( ) method (including the SELECT Command). The process( ) method interprets each APDU command and performs the task specified by the command. This is an abstract method of the javacard.framework.Applet class, and any subclass must override this method to define the functionality.

The applet for each APDU command sends the results back to the CAD by sending response APDU.

This command and response dialogue continues until a new applet is SELECTED or the card is removed from CAD.

The Code

import  javacard.framework.*; public class Wallet extends Applet {     .........     ......... private Wallet (byte [ ] bArray, short boffset, byte bLength) {      pin  = new OwnerPIN( PIN_TRY_LIMIT, MAX_PIN_SIZE );              // the installation parameters contain the PIN initialization                 value  pin.update(bArray, boffset, bLength );                 register( );    }  // end of the constructor      public static void install(byte [ ] bArray, short boffset, byte bLength)  {               // create a Wallet applet instance                  new Wallet (bArray, boffset, bLength);    } // end of the install method       public boolean  select ( )  {                 // the applet declines to be selected if the pin is blocked.                    If ( pin.getTriesRemaining ( ) == 0 )                    return false;                    return true;     } // end of select method       public void deselect ( ) {               // reset the pin value                  pin.reset ( ) ;    }          public void process(APDU apdu) {                // APDU object carries a byte array (buffer) to                // transfer incoming and outgoing APDU header               // and data bytes between card and CAD                // At this point, only the first header bytes              // [CLA, INS, P1, P2, P3] are available in              // the APDU buffer.              // The interface javacard.framework.ISO7816              // declares constants to denote the offset of              // these bytes in the APDU buffer                  byte[] buffer = apdu.getBuffer();              // check SELECT APDU command                 if ((buffer[ISO7816.OFFSET_CLA] == 0) &&                 (buffer[ISO7816.OFFSET_INS] == (byte)(0xA4)) )                 return;              // verify the reset of commands have the              // correct CLA byte, which specifies the             // command structure                if (buffer[ISO7816.OFFSET_CLA] != Wallet_CLA)               ISOException.throwIt               (ISO7816.SW_CLA_NOT_SUPPORTED);               switch (buffer[ISO7816.OFFSET_INS]) {               case GET_BALANCE:   getBalance(apdu);                          return;               case DEBIT:         debit(apdu);                          return;               case CREDIT:        credit(apdu);                          return;               case VERIFY:        verify(apdu);                          return;               default:       ISOException.throwIt                    (ISO7816.SW_INS_NOT_SUPPORTED);         }     }   // end of process method }

The method of select ( ) and deselect ( ) are called by JCRE to indicate that this applet has been selected or deselected. In the select ( ) method, it performs necessary initialization to process the subsequent APDU messages. In the deselect method, the applet performs any clean-up tasks before the applet is deselected.

Interface Between an Applet and Its Terminal Application

All the communication between an applet and the application hosted on the CAD is carried by the APDU. So the APDU is like an interface between an applet and the application hosted on the CAD.

Some Basics About APDU

  • APDU commands are always a set of pairs. Each pair contains a Command APDU, which specifies a command sent by the application through a CAD, and response APDU, which specifies the result executed by the applet.
  • 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, which processes the command and returns a response APDU to the terminal application. Command APDU and response APDU are exchanged alternately between a card and a CAD.



Java Card




Response APDU


Command APDU



APDU Format

Command APDU

Mandatory header

Optional header






Data Field


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

         Lc ( 1 byte ): Number of bytes present in the data field of the command.

         Data field (bytes equal to the value of Lc): Data in the form of sequence of bytes.

         Le (1 byte): Maximum of bytes expected in the data field of response command.

Response APDU

Optional Body

Mandatory trailer

Data field



         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.

In Part 2, we will run an applet in a Java Card.


You can download the Java Card 2.1.2 Development Kit here.

Unzip the Windows .zip file that you have downloaded as a self-created directory, jc212.


The original version of the example comes with Sun JavaCard examples in the Java Card package, courtesy of Sun Microsystems.

About the Author

Arsalan K. Lodhi is working on his second bachelor’s degree in computer science, with emphasis in distributed computing, at Cal State Long Beach. He is a Sun Certified Java Programmer.

Get the Free Newsletter!

Subscribe to Developer Insider for top news, trends & analysis

Latest Posts

Related Stories