JC101-1c: Hello World (for smart card developers)

UPDATED (04/05/07): Fixed some bugs, added reference to source code and CAP file

Java Card is intended for smart cards. The Java language has been adapted to smart cards, keeping only the most important things for smart card applications. Since the char type and the String class have not been deemed useful for smart cards, writing the HelloWorld application is a bit more difficult in Java Card than in many other frameworks.

In addition, a smart card usually does not have a display, and functions like a personal server: all operations are triggered by requests from a client, through a command APDU. A Java Card application mainly consists of an APDU processing engine. It receives a command, with its data if necessary, processes the command, and then sends its response. The classes corresponding to this application model are defined in the javacard.framework package, and the main class is the Applet class. The beginning of an applet declaration often looks like this:

 1 package com.vetilles.helloworld ;
 2 
 3 import javacard.framework.* ;
 4 
 5 public class HelloWorld extends Applet
 6 {

Line 1 is the package declaration. The package is the basic loading unit for Java Card applications; all classes of an application are usually grouped in the same package. Line 3 indicates that the class defines in this file will need to reference the classes defined in the javacard.frameworkHelloWorld, which will be an extension of the Applet class.

Like usual, the next step is to define the data used by the class. In our case, there is a single declaration, containing our message:

 7   private final static byte[] hello =
 8         { 0x48, 0x65, 0x6c, 0x6c, 0x6f } ;

This line declares a variable with the following characteristics:

  • It is a reference to an array of bytes, named hello.
  • It is static, associated to the class and not to the objects.
  • It is initialized with a reference to a 5-element array containing the letters ‘H’, ‘e’, ‘l’, ‘l’, ‘o’.

The next step is to write a method that allocates the objects required for the application, and declares it to the system:

10   public static void install(
11        byte[] buffer, short offset, short length)
12   {
13     (new HelloWorld()).register() ;
14   }

The install method must be present in every applet. It is called when an application needs to be instantiated. It allocates an instance of the applet class (using the new keyword) and then registers it to the system. Naturally, the instantiation process can be more complex, and the method parameters can be used to provide additional information for the installation.

The last method required is the heart of the applet class. It processes all the incoming command APDUs, and prepares the response APDUs. The following is a minimal version, which returns the “Hello” sequence of characters when requested:

16   public void process(APDU apdu)
17   {
18     byte[] buf = apdu.getBuffer() ;
19 
20     switch(buf[ISO7816.OFFSET_INS])
21     {
22       case 0x40:
23         Util.arrayCopy(
24               hello,(byte)0,buf,ISO7816.OFFSET_CDATA,(byte)5);
25         apdu.setOutgoingAndSend(
26               ISO7816.OFFSET_CDATA,(byte)5);
27         break;
28       default:
29         ISOException.throwIt(ISO7816.SW_WRONG_INS) ;
30     }
31   }
32 }

The content of the method defines the following behavior:

  • On line 18, a reference to the APDU buffer is placed in a local variable.
  • On line 20, a switch is made, depending on the value of the INS byte of the command APDU (all other bytes are ignored)
  • On lines 23-24, if INS=40h, the content of the hello array is copied into the APDU buffer, and then sent as response data. The method then finishes normally, and the system uses the status word 9000, indicating a success. Note the cast operations, which are required because 32-bit int values are not acceptable here.
  • In all other cases, on line 29, an exception is thrown, which aborts the execution of the application. the argument to this particular exception, an ISOException indicates the status word to be returned, in that case 6D00.

That’s all. If we select load, install, and select the application on a card, and then send the command APDU:

  00 40 00 00 00

the answer provided by this application will be:

  48 65 6C 6C 6F  90 00

Not very useful, but a first applet, which says “Hello”.

You can download the source code and CAP file for this applet here:

One Comment

  • George Veranis wrote:

    I read your tutorial, it is very helpful for newbies like me! But I want to ask this:
    “ISO7816.SW_WRONG_INS” may be you would write like this “ISO7816.SW_INS_NOT_SUPPORTED” . Because in the first case javac will return this error ”
    No variable SW_W
    RONG_INS defined in interface javacard.framework.ISO7816.
    ISOException.throwIt(ISO7816.SW_WRONG_INS);
    ^
    1 error”

Leave a Reply

Your email is never shared.Required fields are marked *