Get a jumpstart on the Java Card

How to utilize Java in your wallet or purse

This month's Java Developer column, the third in a series on smart cards, will start by describing the CyberFlex card from Schlumberger. We will then write a program for this card, convert it to "card format," download it, and run it. We will briefly discuss a security application and go on to discuss personalization -- the process of making a card specific to its holder. We will also provide techniques for programming smart cards and ensuring security. Smart card security can be a very large topic as security is one of the key features of smart cards. As a start, we will demonstrate a technique for carrying out what is commonly referred to as card holder verification. The article ends with a frequently-asked-questions (FAQ) section.

Note: For the big picture on the Java Card API, please see the companion piece to this article: "Giving currency to the Java Card API," by Arthur Coleman.

In order to benefit from the concepts in this article, you must have Schlumberger's CyberFlex developer kit. (See the Resources section for information on what to do if you really want to run the demos without changing a line of code.) Some of the examples included here can be modified for other cards that may come to market as time goes on. The resources at the end of the article provide information on other cards coming soon from Bull and GemPlus.

What is the CyberFlex Java Card?

In previous articles in this series (see "Smart cards: A primer" and "Smart cards and the OpenCard Framework," we discussed how to use Java to communicate with a smart card and how to develop a smart card terminal interface. CyberFlex is a smart card from Schlumberger that runs programs written in the Java programming language. The CyberFlex card looks almost exactly like a credit card but is in fact a small computer. The card contains a microprocessor to provide processing capability and memory for storing instructions and data. For more on CyberFlex 2.0 and its relation to Java Cards, see the Frequently asked questions section. The card can be broken down into the following functional areas:

  • CPU
  • RAM
  • ROM

The card can be used to store and update account information, personal data, and even monetary value. The cards are ideal for secure Internet access, purchases, portable digital telephones, and for benefit programs and healthcare applications. Smart cards bring new services, as well as increased security, portability, and convenience, to computer applications. The following diagram depicts an architecture capable of supporting multiple applications.

Some consumers have expressed extreme concern with the idea of having their health information and their banking information in the same place and then interacting with some online service. Smart card manufacturers have been working on this problem for years and have come up with security based on partitioning.

CyberFlex architecture

Simple example

The example we will start with is very simple. As we have discussed in previous articles, the ATR ("answer to reset") is fundamental to ISO 7816 -- the recognized standard for communicating with smart cards. ATRs are the means by which a card provides some identifying information when the card is reset or inserted in a reader. The ATR is well-defined in the ISO standards. The recent OpenCard article published last month in JavaWorld included an excellent ATR-dumping facility that we will use this month.

Our first example is a cardlet (the name of a collection of Java classes that run on a card) that modifies the ATR to respond with some specific information. The application will be downloaded to the card and installed as the start-up program. When the card is reset, the ATR that is sent from the card to the application via the smart card reader is the ATR from our application. The steps we need to perform are:

  1. Write the application
  2. Post process the java .class files for the CyberFlex card
  3. Download the application using the development tools
  4. Test the application

The application "CardHello"

The application we are writing appears below. We are using a generic ATR and setting the string "Hello World" into the ATR field. The ATR is fully described in ISO 7816-3. The code for this program follows, and it is commented for you in great detail. (Notice the different requirements for 2.0 and pre-release cards)

/* * CardHello: Custom ATR */

// Use import for CyberFlex 2.0 only; Comment out for pre-release cards // import javacardx.framework.*;

public class CardHello {

public static void main() {

///////////////////////////////////////// // Without this statement, you could potentially // lock a card out forever. This statement allows the // default system loader to be executed on the // next reset. In other words, without this // statement, the CyberFlex card will run // your downloaded program every time, so if it has // a bug you will be unable to get to it -- // unless, of course, your program has the ability to // unload itself and restore the default loader. ///////////////////////////////////////// _OS.Execute((short)0,(byte)0); // Return control to default loader

byte ATR[] = new byte[4]; ATR[0] = 0x3B; //////////////////////////////////////////// // Send the first byte of the ATR to gain some time. // Welcome to the world of real time. Some readers // require responses within x ms of inserting a card, // so we send one byte to the reader to get it to wait, // and then send the rest of the data. //////////////////////////////////////////// _OS.SendMessage(ATR,(byte)1);

//////////////////////////////////////////// // Fill the last part of the ATR and send it // starting at ATR[4]. The prior bytes are ATR // data and can be decoded using the ISO 7816 // specification. Unfortunately, ISO charges // you for a copy of the specification. //////////////////////////////////////////// ATR[0] = (0x30 | 0x0a); ATR[1] = 0x15; ATR[2] = 0x00; ATR[3] = 0x49; _OS.SendMessage(ATR,(byte)4); ////////////////////////////// // Write the historical data ////////////////////////////// byte atrHistorical[] = new byte[10]; atrHistorical[0] = 'H'; atrHistorical[1] = 'e'; atrHistorical[2] = 'l'; atrHistorical[3] = 'l'; atrHistorical[4] = 'o'; atrHistorical[5] = 'W'; atrHistorical[6] = 'o'; atrHistorical[7] = 'r'; atrHistorical[8] = 'l'; atrHistorical[9] = 'd'; _OS.SendMessage(atrHistorical,(byte) atrHistorical.length); ////////////////////////////// // Wait here forever ////////////////////////////// while (true) ; } }

Post processing: Converting the class bytes to a format understood by the card

The Resources section contains all of the code required for this example. You should be able to compile the above program. Make sure you have the OS.class file in your directory. This file provides some of the card-specific methods for the Card Operating System. This post-processing step is necessary to convert the card bytes to a format understood by the card. It will be awhile before Java Cards can understand .class bytes directly. By running the command mksolo.exe, you should get something like this:

Schlumberger (R) (a registered trademark) MakeSolo (a trademark) Post-processor Version 1.001 Copyright (C) Schlumberger Technologies 1997. All rights reserved.

Solo size statistics: Output: 238 bytes; Max stack: 8 bytes; Max object: 0 bytes Successfully generated cardlet 'CardHello.bin'

Downloading the application

Here is a brief walkthrough of how to get started downloading a Java program to a CyberFlex card using EZ Formatter with a Litronic 210 reader. EZ Formatter is a Windows 95 utility program for loading applications to the Cyberflex card. The Litronic 210 is a smart card reader distributed with the Schlumberger development kit. See the Resources section for more information on these tools.

  1. Test your smart-card reader connection. For the Litronic reader, there is a test program that blinks the green LED 10 times. This will ensure that there is no hardware problem or software conflict. To use this program, run ..\Schlumberger\CyberFlex SDK\Litronic\Config, select the port that the reader is connected to, and press the "Test" button. If everything is okay, the green LED on the reader will blink 10 times. Press "OK" to exit this program.

  2. From the Windows Explorer, select "Ez2us" in the "EZ Formatter" directory, and select "Properties" from the "File" menu. At the time of this writing, the correct created date is 5/13/97 5:35 PM.

  3. Run EZ Formatter ("Ez2us" in the "EZ Formatter" directory).

  4. A "System Configuration" window should come up. (If it doesn't, select the "System Configuration" button on the toolbar, just left of the monitor and "?" icons.)

  5. Select LITR210.RDC for the reader file.

  6. Select CYBERFLX.CDC for the card file.

  7. Select your port (probably Com1, but depends on your reader connection).

  8. Select "OK."

  9. Insert a CyberFlex card into the reader.

  10. Press the "Power On" button on the toolbar (the left-most button). The green LED on your Litronic reader will illuminate. You should see a message at the bottom that the card and reader are ready. At the top, you should see an ATR string, ATR = 3B 32 15 00 49 10.

    Note: If you see an error here, it may be that the selected COM port, that is COM1, is being used by some other system process, such as PC/SC, which defaults to using COM1. If you have multiple COM ports on your machine, you can simply redirect EZ Formatter to use a different COM port. If you have a single COM port, you will have to disable PC/SC (or any other process using that COM port) so that EZ Formatter can use the COM port.

  11. Select the box to the right of the "?" icon on the tool bar. Enter 2222. (This is the File ID of the Java program, as initialized on your CyberFlex card.)

  12. Press the arrow button just to the right of this box. You should see a message at the bottom: File/Directory "22 22" Now Active.

  13. Press the LoadSolo (CyberFlex) tab. It should show File ID 2222.

  14. Press the "Get Java Program" button. Select your .BIN file as generated by MakeSolo. The program will load and display in the larger window. Make sure that the last bytes of your program are "4D 00 00 00". (All CyberFlex programs must end with this sequence.)

  15. Select the "Download" button. Press "YES" on the confirmation dialog.

  16. A "Security Manager" dialog will now appear. Select Key 0 on the list on the left side. Select Hex Values for the Code/Key Format. The box at the lower right side should now be labeled "Present Key 0". Enter "AD 9F 61 FE FA 20 CE 63" in this box, and press the "Present" button.

  17. A message should appear at the bottom: Key/Code approved. If so, press the "Close" button. If not, check your key and re-enter.

  18. After pressing the "Close" button, you should see the download proceeding one line at a time in the lower window. Do not press any key or button until this download completes. The download should end with "4D 00 00 00t". The message at the bottom should say "OK".

  19. Press the "Set To Run" button. This will cause your Java program to execute on the next reset. Your program must contain the statement: _OS.Execute((short)0, (byte)0);. This should preferably be the first line in your program, to make sure that the statement executes regardless of any other bug in your program. If you set a program to run that does not execute this statement, your card will never be able to download or run any other program, ever. This is irreversible!

Running and testing your application

You are now ready to run your Java program. On the next reset, your program will run. You should see the ATR specified in the example above; in EZFormatter ATR displays in the upper righthand corner of the screen. Assuming your program executes the _OS.Execute command as above, the next reset after your program runs will put you back in the default loader program, where you can repeat this process to download changes to your program.

If you just wish to execute the same program a second time, you can select file 2222, select the Security Manager (the Lock icon on toolbar), enter your Key/Code in the Security Manager, and set program 2222 to run again, bypassing the "Get Java Program" and "Download" steps.

After becoming comfortable with these steps, I suggest exploring the EZ Formatter documentation to learn how to better use this program for your needs.

Running this example with OpenCard


1 2 3 Page 1
Page 1 of 3