Writing VirtualCurrency JavaCard Applet
Armed with the knowledge gained so far, we can write the VirtualCurrency applet. VirtualCurrency is a JavaCard applet that provides access to multiple services that accept a virtual score or virtual currency earned by contributing to these services. Services belong to several groups.

Service provider groups use group memberships as well as group privilege (role) data to estimate the service or data "price" for the consumer. Services and requested data change their values dynamically in the distributed knowledge or service system, based on their usage by consumers.

Knowledge or service contribution can change a contributor's group ranking or his or her privileges. In this case, the Java- or .NET-based terminal system sends a command to the applet to set group roles for a specified group.

VirtualCurrency Data Structures

We will begin programming the applet with the VirtualCurrency class definition and introduce its properties. We define the static VirtualCurrency_CLA value: a byte with a hexadecimal value that represents this applet class and ensures that APDUs are sent to the proper applet and can be handled by the applet.

Then we define static byte values to represent operations requested by a terminal application via APDUs and performed by the applet.

We define the digital command values for the applet operations: the checkPin(), getAllGroupPrivileges(), getGroupRoles(), and setGroupRoles() operations that will manage group role values; the getVirtualScore() operation that returns a current score; and the addScore() and subtractScore() operations.

Then we define our persistent object�s virtualScore and the array of groupRoles. We also define the byte array to store identity values. We define the virtualScore as the short type value, which can vary from �32,768 to 32,767, or from 0 to 65,535.

We want to define group role values as objects that consist of a groupID and related RoleIDs. One person can play more than one role in the group. Taking into account JavaCard constraints, we simplify this presentation on the JavaCard side and shift more work to the terminal application that can enjoy the full power of J2EE.
We now use the AID class (consisting of two parts: RID and PIX) to represent groupRoles. Group role objects also consist of two parts: the groupID and the RoleID(s).

We place the groupID in the first 5 bytes of the AID object, which usually serves to hold the RID. We place the roleID(s) in the second (flexible-length) part of the AID object, which usually serves to hold the PIX.

The illustration below represents the AID structure and the groupRoles object structure.

javaCard-APDU-3

We define the groupID with the first 5 bytes in the groupRole object. Then, the first byte in the second part of the object shows the number of roles, and the following bytes represent the role IDs. If the number of roles is more than 10, additional AID object(s) should be used to represent additional roles for the same group, since in this example we assume that the number of roles for one person in any group is limited to 10.

At the bottom of the APDU illustration, we transform AID objects into a byte array for APDU exchange. The transformation is straightforward. The first 2 bytes in the sequence represent the total number of AID objects. Every AID object starts with the byte that holds the length of the object, followed by the AID object bytes.

Note that the first 5 bytes of the APDU have a fixed meaning for all commands. The CLA byte identifies the applet. The INS byte carries a current instruction (command). The P1 and P2 bytes are reserved for some parameters related to the command. Finally, the LC byte tells us about the following number of bytes of data. This number indicates the number of bytes the system sends to the applet or expects to receive from the applet in response to the current command.

The source below introduces the VirtualCurrency applet as a public class with its properties, and the private constructor.


// VirtualCurrency



package com.its.javacard;



import javacard.framework.*;



/**

 * The VirtualCurrency is a javacard applet that provides access 

 * to multiple services that accept virtual score or virtual currency 

 * earned by contributing to these services. 

 * Services belong to multiple groups. 

 * Service provider groups use group memberships as well as group privilege (Role) 

 * data to estimate the service or data "price" for the consumer. 

 * Services and requested data change their values dynamically in 

 * the distributed knowledge/service system based on their usage by consumers.

 * Knowledge or service contribution can change contributor's ranking or

 * her/his privileges (roles). 

 * In this case the (Java or .Net based) terminal system would send a command 

 * to the applet to set (reset) group roles (for a specified group).

 * @author Jeff.Zhuk@JavaSchool.com

 */

public class VirtualCurrency extends Applet {

    final static byte VirtualCurrency_CLA = (byte) 0x18; // code is up to you

    final static byte CHECK_PIN = (byte) 0x17;

    final static byte GET_GROUP_PRIVILEGES = (byte) 0x16;

    final static byte SET_GROUP_PRIVILEGES = (byte) 0x15;

    final static byte GET_VIRTUAL_SCORE = (byte) 0x14;

    final static byte ADD_SCORE = (byte) 0x13;

    final static byte SUBTRACT_SCORE = (byte) 0x12;

    final static byte GET_IDENTITY = (byte) 0x11;



    final static byte SELECT_APDU_COMMAND = (byte) (0xA4); // standard code

    final static short SW_PIN_VERIFICATION_REQUIRED = 0x6301;

    final static short SW_PIN_VERIFICATION_FAILED = 0x6300;



    final static byte MAXIMUM_BYTES_FOR_PIN = (byte) 0x8;

    final static byte NUMBER_OF_TRIES_IF_PIN_BLOCKED = (byte) 0x5;



    // ownerPin object that keeps PIN value

    OwnerPin ownerPin;

    // total virtual score

    private short virtualScore;

    // array of group privileges (roles)

    private AID[] groupRoles;  // each consists of the groupID and one or more roleID

    private byte[] identity;   // identity bytes (set by another applet)



    /**

     * private constructor is called by the install() method

     * with the installation parameters passed by the JCRE

     */

    private VirtualCurrency (byte [] byteArray, short byteOffset, byte byteLength) {

        // create and init the PIN

        ownerPin = new OwnerPin(NUMBER_OF_TRIES_IF_PIN_BLOCKED, MAXIMUM_BYTES_FOR_PIN);

        // register

        ownerPin.update(byteArray, byteOffset, byteLength);

    }

Was it clear so far?