iButtons: The first ready-to-buy 2.0 Java Card API devices

Develop, build, and test Java Card applications

Previous articles in this Java Developer series on smart cards have described communicating with smart cards using industry-standard protocols like ISO7816, and explored layered implementations of interfaces with OpenCard or PC/SC. Last month we concentrated on the Java Card. This month we'll take an introductory look at an implementation of 2.0 Java Card and show you how to write, download, and test applications for this exciting technology.

A word on this article and its companion pieces

This month's Java Developer column, called "An introduction to the Java Ring," describes the history of Dallas Semiconductor's Java Ring devices and provides a background on the theory behind them. This iButtons article (along with a forthcoming article on serial device support using javax.comm) provides the information you need to develop application solutions using Java Card. The javax.comm API is used by the host software to communicate with the reader, which in turn communicates with the card or ring. For more information on readers and terminals, see the first article in this smart card series.

Java Ring

This article will get you started on the road to understanding how to develop applications for Java Card. You should be able to get a Java iButton ring and a reader -- smart cards need something to plug into -- for 0.00. Take a look at the Resources section for more information on what you need and how and where to order rings and readers. The software is available over the Internet.

Defining the problem to be solved

We're finally ready to solve a real-world problem with Java Card.

Using the information in this article, as well as that material gleaned from the other articles in this smart card series, you will be able to interface a device to a browser and have the data bounce off of the ring or smart card instead of the hard disk. Why would you want to do this?

How many times a day do you have to give someone your business card information verbally? Worse yet, how much time do you spend collecting business cards to scan into your computer for access later? I provide business card/personal information so often that I will happily pay for any technology that provides a solution. It's rather odd that phone companies don't provide a simple, automatic option for transmitting this kind of information -- commonly referred to as profiling information -- over the phone.

There are some standards in motion to provide this service from any Web browser. Recently, browsers have started to add sections that contain common business card information. At the current time, however, no browsers support a business card that is also "smart."

The standard being proposed for personal information is OPS (Open Profiling Standard), and a proposed standard for EDI (electronic data interchange) on extranets is called "ICE." The standards themselves are quite large and we can't possibly cover them in this short article. We can, however, show you some of the core components that could be used to build such a profiling information delivery system.

Developing applets for Java iButtons

This article assumes you have read the previous article on javax.smartcard, "Understanding Java Card 2.0," by Zhiqun Chen. The following diagram provides the big picture for application development.

The diagram depicts the process of creating the Java bytecodes, converting the bytecodes into a format that can be understood by the card, and loading the bytecodes.

Following is a description of the minimum software and hardware needed to develop an application.

Software architecture communication

Software architecture communication with Java iButton devices requires both software and hardware. Communication with the rings is achieved via APDUs transmitted over a serial or parallel connection. The software for sending APDUs to a ring reader on a serial port is provided in this article's Resources. This software uses an experimental API called Java.smartcard and the recently-released javax.comm to communicate with serial and parallel devices.

Communication interface to Java Cards inserted in readers via APDUs/PDUs

Java

Application

Card

Agent

Java

Application

Java

Application

Java

Application

Open

Card

javacard.framework
javax.smartcard
PC/SC Adapter

Native

Code

Driver

Pure Java

Driver

Pure Java

Driver

PC/SC

Driver

PC/SC

Driver

javax.comm
Serial ReaderPCCard ReaderIR readerRing Readers

The software listed in the Resources section supports the above architecture. The above diagram provides many paths, some of which are optional while others are not. Please note that javax.smartcard is an experimental API used for sending and receiving APDUs. Although it has the name "javax.smartcard," it is not an official JavaSoft API to be included in future JDK cores or extensions.

The Java Card 2.0 Programming Concepts (see Resources) clearly defines API usage for javacard.framework. You must always use javacard.framework to be Java Card 2.0-compliant, because this is an important API to write to. You may also use additional APIs from the device manufacturers as well as other APIs, like the standard extensions defined in the Java Card 2.0 API. Last month's column goes over this information in great detail.

Hardware requirements

A ring and a reader are required for this application. Java iButtons can be connected via a serial reader or a parallel reader; both are available from Dallas Semiconductor. See the Resources for information on obtaining the hardware. I think you'll like the prices.

Serial port reader

The DS9097U-9 serial port adapter connects to the host serial port via its DB9-S (female) connector. It connects directly with laptops, Java Stations, and most desktop PCs. A gender changer and a 25-pin-to-9-pin adapter are required for connectivity to most SPARC stations. The DS9097U-9 serial adapter connects to the RJ11 jack on the DS1402D-DR8 Blue Dot receptor. The iButton simply snaps into either of the blue dots.

Parallel port reader

The DB25-P (male) connector of the DS1410E parallel adapter plugs into the parallel port of any PC or laptop. A printer cable may be connected to the DS1410Es DB25-S (female) connector. The DS1410E parallel adapter connects to the empty microcan on the DS1402D-DB8 Blue Dot receptor. The iButton simply snaps into either of the blue dots. Note that communication via the DS1410E parallel adapter is supported on Win32 platforms only.

Applet architecture

Yes, Java Card supports applets! An applet written to run on the Java ring follows a very simple structure. The process is very similar to applet programming in that there are several methods that you may override. These methods are:

  • deselect -- another applet, or possibly this one, is about to be selected
  • install -- installs the applet
  • process -- incoming APDUs arrive here
  • register -- register applet
  • select -- called when a select command is received

Java developers must override at least the install and process methods of the super class, Applet. In simple applets such as BusinessCard, install simply constructs a new instance. It is the job of the constructor to register the applet with the Java Card runtime environment (JCRE).

The following code segment demonstrates how to override the install method. The install method is normally used to set up the applet environment. Simple applets may be ready to run after calling install. More complicated applets may require additional initialization sequences.

class BusinessCard extends Applet { 
   public BusinessCard() { 
      // Register our applet with the JCRE 
      register();
   } 
   public static void install(APDU apdu) { 
      new BusinessCard();
   } 
   public void process(APDU apdu) throws ISOException { 
      . 
      . 
      .
   } 
   . 
   . 
   .
} 

In order to communicate with the host, a.k.a. the card terminal, the applet must implement the process method. This method is invoked on the selected applet whenever a command APDU is received from the host. Following is a segment of BusinessCard's implementation of the process method. Its structure is typical of Java Card applets.

public void process(APDU apdu) throws ISOException { 
   byte[] buffer = apdu.getBuffer(); 
   // process selects separately 
   . 
   . 
   .
   if (buffer[ISO.OFFSET_CLA] != BC_CLA) { 
      // Don't know what to do with this instruction 
      throw new ISOException(ISO.SW_CLA_NOT_SUPPORTED);
   } 
   else { 
      switch (buffer[ISO.OFFSET_INS]) { 
      // Store new business card data 
      case BC_INS_STORE: 
         businessCardStore(apdu); 
         break;
      // Send business card data to the host 
      case BC_INS_RETRIEVE: 
         businessCardRetrieve(apdu); 
         break;
      // Don't know what to do with this instruction 
      default: 
         throw new ISOException(ISO.SW_INS_NOT_SUPPORTED);
      }
   }
} 

The main purpose of the process method is to determine the integrity of the APDU header (the CLA, INS, and so on), and invoke the correct dispatch method. If process has trouble understanding the header, it will throw an instance of ISOException with the appropriate status code. It is the responsibility of the developer to define the specific APDUs that are accepted and what their format is.

Data communication with the ring

Normally, the dispatch method interprets the command APDU, performs any required actions, and returns a response APDU to the host. BusinessCard's dispatch method for information retrieval provides a simple example of returning data to the host.

protected void businessCardRetrieve(APDU apdu) { 
if (bcData != null) { 
apdu.setOutgoing(); 
// Return business card data to host 
apdu.sendBytesLong(bcData, (short) 0, (short) bcData.length);
}
} 

As you might have guessed, sendBytesLong takes an array, an offset, and a byte count as parameters and returns this data to the host in the body of a response APDU. Since we didn't alter the header bytes, the command and response APDUs will have the same header.

Compile post-process load and go

Card manufacturers may supply their own programs for personalization -- the process by which a blank card is personalized to the task at hand. (Applets may be loaded on the card and PINs may be set at this time.) Most cards will require post-processing to convert the bytecodes to the required format. These programs typically allow you to interact with the device from a visual interface. Dallas Semiconductor has supplied a program for this. The source code can be found in the development kit listed in the Resources section. Don't forget to read the README file listed there. This file will provide important information on how to post-process the Java bytecodes into a format suitable for the loader program. The user interface for this personalization program is shown below:

The above program enables you to install an applet on the ring and send APDUs, and receive the response to the APDU that was sent plus additional utility methods provided by the manufacturer. This program and more detailed directions are available in the Resources section, which also lists the APDU commands recognized by the Java iButton.

A sample applet

A Java Card business card must be able to store and retrieve information. This electronic business card must be inserted into a reader that is on a host system that has software capable of understanding it. Once the host software has detected that there is a ring present, the user is given options to change or view the data.

Using a subset of the standard Java language defined in the Java Card 2.0 Specification and making use of the relatively large Java stack and garbage collection features of the Java iButton, it is possible to execute applets with fairly substantial computing requirements. The BusinessCard applet provides an excellent solution to the problem mentioned earlier -- of how to efficiently transmit business card information. The environment that the host and client software works in is shown in the following diagram.

Host ComputerCommunicationJava Ring
Business Card Host Program
  • Load Card
  • Store Card
APDUs Business Card Applet
  • Load Card
  • Store Card

Users carry an iButton that contains their personal information. When this device is inserted into a system that contains the corresponding host software, information can ether be retrieved from the ring or stored on the ring. Many people are nervous about the security threat this kind of information transaction poses. The good news is that it is possible to prevent unauthorized access to personal information. Our example Java Card can easily be modified to require the user to enter his or her PIN whenever it encounters an unauthorized information request.

For example, when you go to a conference, a vendor might ask for your name. Instead of giving him a piece of paper (your business card), you insert the ring into his PDA, which is running PersonalJava. Let's say this vendor also likes to mail things to all interested persons, so the software asks for your home address. If you haven't pre-authorized this particular information transaction, the card will request a PIN.

Assuming you do have a Java Card business card that requires your PIN for everything except your first name, are you safe yet? Not really! It is common knowledge that entering your PIN on any PIN-access device can be very dangerous. Why? Someone can take your PIN off the network in the supermarket, make a few plastic cards, go straight to the bank and take your money. It's actually very easy to do this. The solution? PIN-access devices that you carry on your person. When you enter your PIN, it never leaves the device; instead the PIN-access device uses some other protocol to authenticate.

The demo below includes CoinPurse, an excellent example of PIN usage with the Java Card. The source code for the BusinessCard demonstration is included in the Resources section.

Installing the demo

Once you have installed the compressed file from www.ibutton.com, listed in the Resources section, in your favorite directory, you will notice several files. The most important file is the README file, as this describes everything you need to know about setting up your environment so that you can download applets to the card.

Conclusion

The Java iButtons discussed in this article are based on the 2.0 version of the Java Card API. Users of the Internet and of intranets can benefit from Java Card because it provides the advantages of traditional smart card -- like secure portable storage -- with the flexibility of Java. The greatest benefit to programmers is that instead of writing in a proprietary language, applications can be written in Java and loaded onto the card.

We have shown that programming smart cards using the Java Card specification is possible. With a little bit of effort, there are enough tools and documentation to begin using the technology. We end our smart card series with this article. As promised, we started with some simple memory cards and ended with the Java Card. In the coming months you should see this market become very active. Don't forget to track OpenCard, and very closely. Good luck!

Rinaldo Di Giorgio is a staff engineer in the research department at Sun Microsystems. There he experiments with digital economies.

Learn more about this topic

  • Latest release from Dallas Semiconductor. Download this file and uncompress it. Winzip may be required. You will see several directories. Start by reading the README file. To run the demos you will need to connect a reader to your computer. BusinessCard.java is a listing of the Java Card applet included here for convenience http://www.ibutton.com/devkit
  • JavaSoft's Java Card home page contains all the APIs and additional examples that you should be able to run on the card http://www.javasoft.com/javacard
  • APDU commands specific to Java iButtons, a very terse listing of APDUs recognized by the card http://www.javaworld.com/javaworld/jw-04-1998/ibuttons/cmds.html
  • See JavaWorld's article, "An introduction to Java Card" http://www.javaworld.com/javaworld/jw-02-1998/jw-02-javacard.html
  • Emerging standard for communicating with smart cards http://www.opencard.org/
  • Java Card Programming Concepts (pdf file). Listed here for convenience http://www.javaworld.com/javaworld/jw-04-1998/ibuttons/JC20-Concepts.pdf
  • Java Card 2.0 API (pdf file). Listed here for convenience http://www.javaworld.com/javaworld/jw-04-1998/ibuttons/JC20API-prtrat.pdf