OpenCard Framework 1.2 Programmer's Guide

Document Number BOEB-OCFP-00

OpenCard Framework 1.2 -- Programmer's Guide

Fourth Edition

December, 1999

Copyright OpenCard Consortium.

This book provides information about the OpenCard Framework.

Order publications through your IBM representative or the IBM branch office serving your locality. Publications are not stocked at the address below.

IBM welcomes your comments. A form for readers' comments may be provided at the back of this publication, or you may address your comments or questions to the following address:

IBM Deutschland Entwicklung GmbH

Information Development, Dept. 3248

Schoenaicher Strasse 220

71032 Boeblingen

Germany

 

FAX (Germany): 07031 16 3456

FAX (Other Countries): (+49) 7031 16 3456

 

IBM Mail Exchange: DEIBMBM9 at IBMMAIL

Internet e-mail: idepubs@vnet.ibm.com

World Wide Web: www.opencard.org

Make sure to include the following in your comment or note:

• Title and order number of this book
• Page number or topic related to your comment

Trademarks and service marks

• IBM
• CT

Java and all Java-based trademarks and logos are trademarks or registered trademarks of Sun Microsystems, Incorporated, in the United States and/or other countries.

Windows, Windows NT, and Windows 95 are registered trademarks of Microsoft Corporation in the United States and/or other countries.

Other company, product, and service names may be trademarks or service marks of others.

Table of Contents

Figures

Preface

Bibliography

Figures

1. Main parts of the OpenCard Framework architecture
2. Classes of the CardTerminal package
3. The CardTerminal layer

Preface

About this manual

The OpenCard Framework sits between a smart card-aware application or applet written in Java and the card reader (also known as Card Acceptance Device (CAD) or Interface Device (IFD)). The framework enables programmers to write smart card applications against a high-level programming interface that hides the complexities of interacting with cards and card readers from different vendors. Thus, applications developed on top of the OpenCard Framework are readily usable on all platforms supporting the Java environment and provide the interoperability across card and reader vendors that is required to deploy applications written as applets in an Internet environment.

How to use this manual

The manual is also intended for OpenCard component developers who implement pluggable framework components for card terminals or cards.

Throughout this manual, we've provided sample code to illustrate programming with the OpenCard Framework reference implementation. Notice that the code is incomplete and thus would not compile. For the sake of brevity, we've shown only those code snippets relevant to illustrate some point and haven't always shown how some instance variables were initialized. However, we have tried to include sufficient comments and variable declarations to make the code illustrations self-explanatory.

Assumptions

However, the reader may need some help in familiarizing himself with smart card technology and the terminology used in this field in order to better understand the concepts presented in this document.

Where you can get OpenCard Framework

You can access sample code for the Java Developer at http://www.javaworld.com/jw-10-1998/javadev/javadev.zip.

Font conventions used in this manual

• new terms, when they are defined;
• the titles of documents, papers, and books appearing in references.

• anything (in particular source code) that would be typed verbatim.

• names (such as company names, product names, registered trademarks, etc.).

Related documents

• OpenCard Framework 1.0 - White Paper. This paper provides a gentle introduction to the OpenCard Framework, describing its objectives, the architecture, and the reference implementation.

Feedback

Send any corrections, amendments, suggestions, or comments to this e-mail address:

opencard-info@opencard.org

Introduction

Developing smart card applications

Let's take a closer look at what's involved when the application interacts with the smart card. Don't be worried by the technical details presented here, because the OpenCard Framework will hide most of the complexity from you. The intent here is to provide some background and understanding of what is happening so that the need for and the usefulness of OCF can be appreciated.

Interactions with the smart card occur by exchanging pairs of APDUs (application protocol data units) and are initiated by the external application. Communication with the smart card is accomplished via the card reader, an I/O device attached to the computing platform into which the smart card is inserted. The application sends a CommandAPDU to the smart card by handing it to the card reader's device driver, which forwards it to the smart card. In return, the card sends back a ResponseAPDU, which the device driver hands back to the application.

A smart card's functions are determined by the set of CommandAPDUs that it understands. Although standards for smart cards do exist, the functionality may vary significantly. In other words, depending on the card vendor and/or the type of card, different functionalities are offered and the exact definition of the set of Command- and ResponseAPDUs may differ.

Similarly, there is a broad range of card readers on the market with widely differing functionalities. Very simple readers merely provide basic reader functionality offering a single slot to insert the card. More sophisticated readers offer multiple slots or include a PIN³ pad and a display that can be used to perform cardholder verification. Card readers can attach to different I/O ports including serial port and PC Card slot. There are even versions available that can be inserted into the floppy drive. They come with proper driver software for a selection of operating systems. There is no single API to access the card reader driver.

Given these technicalities, development of smart card applications has been much of an art in the past and was confined to a relatively small number of specialized programmers. In addition, the dependencies on the make of the card and the card reader have usually prevented application developers from deploying their applications across a wide range of cards or card readers. As a consequence, smart card applications have been primarily "vertical" applications mostly implemented with a single type of card and maybe a small number of card readers.

The emergence of multi-application cards, made possible by advances in the underlying chip-card technology and the need to deploy smart card applications and applets in an Internet setting, where it is virtually impossible to know in advance what type of card or card reader the application will have to interact with, make it imperative that alternate ways of developing smart card applications be made available.

Developing applications using OpenCard Framework

In order to adapt itself to a particular situation, OCF relies on the availability of adequate Java components that can be plugged into the framework to address a particular card reader and card inserted. But don't worry, these components are typically developed by card reader manufacturers and card-chip manufacturers and are not something which application programmer have to implement. All they have to do is to make sure that the card reader and card type they choose to deploy the application are supported by OCF-compliant components. An up-to-date list of the devices supported can be found at the OCF web site.

OCF will not provide support in developing the card-resident part of the application. Normally, smart card vendors offer their cards together with a development toolkit that supports the development of the card-resident application component.

For conventional smart cards, the toolkit may contain tools supporting all or a subset of the following tasks:

Layout definition

This is the process of generating an EEPROM image from a high-level definition of the EEPROM layout. Most smart card applications maintain information in the smart card. This information is typically kept in EEPROM-based files on the card's file system. Layout definition is about identifying the information items that should go in the card and defining an appropriate file structure in the card. The latter includes specifying the type of file (transparent, record-oriented, cyclic), file names and/or identifiers, access conditions, initial data, etc.

Card initialization

This is the process of writing initialization data to the smart card EEPROM (it could be compared to formatting a disk). The EEPROM image generated during the layout definition is transferred to the smart card. Depending on volume, this can be supported by special types of card readers that achieve a high throughput.

Card personalization

This is the process of writing cardholder-specific data to the smart card. After initialization, the smart card EEPROM reflects the basic file system structure as defined in the layout definition and may contain some initial data that is constant across all cards, such as meta-information about the file system structure, cryptographic key information, etc. During personalization, the information peculiar to an individual cardholder is written to the card prior to issuing it.

Getting started

Preparing the system

1. Get and install Jdk (Java Developer's Kit) - preferably version 1.1.6 or later, if you have not already done so. You can find versions of the Jdk for a number of operating systems at Java Soft's Jdk WWW site⁴ . Alternatively, you can get the Jdk with one of the commercially available Integrated Development Environments (IDE) for Java.
2. Likewise, download and install the OpenCard Framework reference implementation available at the OCF WWW site⁵ and follow the installation instructions.
3. Obtain an OCF-compliant smart card reader device. Check the list at http://www.opencard.org/ for devices that are presently supported via OCF-compliant CardTerminal components. Check this list frequently as new components supporting different devices will become available.
4. Obtain OCF-compliant smart cards and the corresponding developers toolkit. Check the list at http://www.opencard.org/ for cards that are presently supported via OCF-compliant CardService components. Check this list frequently as new components supporting different devices become available.

Writing your first sample application

If you do not own such a card, you can use any other smart card for which a FileAccessCardService is available. Use the tools provided with your smart card to create a transparent file in the master file (MF) of your smart card. The file must have the ID 0xc009 and should have access condition ALWAYS or CHV for read and write access. To initialize your card, you may prefer to start with the second sample application (see Writing your second sample application), which allows you to write data to that file.

First, we create a skeleton of the new application. The skeleton consists of import statements, a class definition, and a main method where the actual application code will be filled in:

import opencard.core.service.SmartCard;
import opencard.core.service.CardRequest;
import opencard.opt.iso.fs.FileAccessCardService;
import opencard.opt.iso.fs.CardFile;
public class ReadFile {
  public static void main(String[] args)
  {
    System.out.println("reading smartcard file...");
    // here, the application code will be filled in
    System.exit(0);
  }
}

Before we can work with OCF, we have to initialize it. Afterwards, OCF has to be shut down to release system resources. Since errors may occur (for example because the user removes the smart card while it is accessed), we also have to implement some error handling. The code to do all that may look like this:

    try {
      SmartCard.start();
 
      // here, OCF can be used
 
    } catch OpenCard Exceptions {
      e.printStackTrace(System.err);
 
    } finally { // even in case of an error...
      try {
        SmartCard.shutdown();
      } catch OpenCard Exceptions {
      e.printStackTrace(System.err);
      }
    }

To make sure that OCF is shut down even in case of an error, the corresponding statement is located in the finally part of the try statement. At first glance, it may seem strange that shutting down OCF may cause another exception. However, the shutdown may cause dynamic libraries to be unloaded. An error in such an operation indicates serious problems of the operating system and should therefore not be ignored.

Now, we have dealt with the wrap-around code and can use OCF. The first thing we have to do is to wait for a smart card from which we can read. This is done by creating a CardRequest and waiting until it is satisfied:

    // wait for a smartcard with file access support
    CardRequest cr =
      new CardRequest(CardRequest.NEWCARD, null, FileAccessCardService.class);
    SmartCard   sc = SmartCard.waitForCard(cr);
 
    // here, we will read from the smart card
 
    sc.close();
    // printing the data can be done here

After having obtained a SmartCard object, we have to create the card service we are going to use. We can then specify which file we want to access, and finally read its contents:

    FileAccessCardService facs = (FileAccessCardService)
      sc.getCardService(FileAccessCardService.class, true);
    CardFile root = new CardFile(facs);
    CardFile file = new CardFile(root, ":c009");
 
    byte[] data = facs.read(file.getPath(), 0,
                           file.getLength() );

Now, the file contents are stored in a byte array named data. Since our application will no longer access the smart card, the SmartCard object can be closed as described above. We can then convert the byte array into a string, which will be printed to the standard output:

    String entry = new String(data);
    entry = entry.trim();
    System.out.println(entry);

Here is the complete listing of the first sample application. Although the detailed explanations may have confused you, it's not so long after all:

import opencard.core.service.SmartCard;
import opencard.core.service.CardRequest;
import opencard.opt.iso.fs.FileAccessCardService;
import opencard.opt.iso.fs.CardFile;
 
public class ReadFile {
 
  public static void main(String[] args)
  {
    System.out.println("reading smartcard file...");
 
    try {
      SmartCard.start();
 
      // wait for a smartcard with file access support
      CardRequest cr =
        new CardRequest(CardRequest.NEWCARD, null, FileAccessCardService.class);
      SmartCard   sc = SmartCard.waitForCard(cr);
 
      FileAccessCardService facs = (FileAccessCardService)
        sc.getCardService(FileAccessCardService.class, true);
      CardFile root = new CardFile(facs);
      CardFile file = new CardFile(root, ":c009");
 
      byte[] data = facs.read(file.getPath(), 0,
                             file.getLength() );
      sc.close();
 
      String entry = new String(data);
      entry = entry.trim();
      System.out.println(entry);
 
    } catch OpenCard Exceptions {
      e.printStackTrace(System.err);
 
    } finally { // even in case of an error...
      try {
        SmartCard.shutdown();
      } catch OpenCard Exceptions {
        e.printStackTrace(System.err);
      }
    }
 
    System.exit(0);
  }
}

Writing your second sample application

import opencard.core.service.SmartCard;
import opencard.core.service.CardRequest;
import opencard.opt.iso.fs.FileAccessCardService;
import opencard.opt.iso.fs.CardFile;
 
public class InitFile {
 
  public static void main(String[] args)
  {
    System.out.println("initializing file...");
 
    try {
      SmartCard.start();
 
      // wait for a smartcard with file access support
      CardRequest cr =
        new CardRequest(CardRequest.NEWCARD, null, FileAccessCardService.class);
      SmartCard   sc = SmartCard.waitForCard(cr);
 
      FileAccessCardService facs = (FileAccessCardService)
        sc.getCardService(FileAccessCardService.class, true);
      CardFile root = new CardFile(facs);
      CardFile file = new CardFile(root, ":c009");
 
      // here, we will write data to the smart card
 
    } catch OpenCard Exceptions {
      e.printStackTrace(System.err);
    } finally { // even in case of an error...
      try {
        SmartCard.shutdown();
      } catch OpenCard Exceptions {
        e.printStackTrace(System.err);
      }
    }
 
    System.exit(0);
  }
}

java InitFile "Klaus Mustermann:klaus@banana.com"

    String entry = args[0].replace(':', '\n');
    byte[] bytes = entry.getBytes();
    int   length = bytes.length;

    int   length = bytes.length;
 
    byte[] data  = new byte [file.getLength()];
    if (data.length < length)
      length = data.length;
    System.arraycopy(bytes, 0, data, 0, length);

    // write the data to the file
    facs.write(file.getPath(), 0, data);
 
    System.out.println(entry);

import opencard.core.service.SmartCard;
import opencard.core.service.CardRequest;
import opencard.opt.iso.fs.FileAccessCardService;
import opencard.opt.iso.fs.CardFile;
 
public class InitFile {
 
  public static void main(String[] args)
  {
    System.out.println("initializing file...");
 
    try {
      SmartCard.start();
 
      // wait for a smartcard with file access support
      CardRequest cr =
        new CardRequest(CardRequest.NEWCARD, null, FileAccessCardService.class);
      SmartCard   sc = SmartCard.waitForCard(cr);
 
      FileAccessCardService facs = (FileAccessCardService)
        sc.getCardService(FileAccessCardService.class, true);
      CardFile root = new CardFile(facs);
      CardFile file = new CardFile(root, ":c009");
 
      String entry = args[0].replace(':', '\n');
      byte[] bytes = entry.getBytes();
      int   length = bytes.length;
 
      byte[] data  = new byte [file.getLength()];
      if (data.length < length)
        length = data.length;
      System.arraycopy(bytes, 0, data, 0, length);
 
      // write the data to the file
      facs.write(file.getPath(), 0, data);
 
      System.out.println(entry);
 
    } catch OpenCard Exceptions {
      e.printStackTrace(System.err);
 
    } finally { // even in case of an error...
      try {
        SmartCard.shutdown();
      } catch OpenCard Exceptions {
        e.printStackTrace(System.err);
      }
    }
 
    System.exit(0);
  }
}

OCF architectural concepts

Architecture overview

Figure 1. Main parts of the OpenCard Framework architecture

The CardTerminal layer contains classes and interfaces that allow you, the application developer, to access card terminals and their slots. Using these classes you can, for example, find out whether a smart card is inserted in a card terminal.

The CardService layer defines the abstract CardService class: OCF represents smart card functions through card services. Each card service defines a particular (high-level) API that you can use to access some particular smart card function; for example, the file access card service gives you access to the file system of a smart card.

Both of OCF's layers -- CardTerminal and CardService -- are designed using the abstract factory pattern and the singleton pattern (as described in Design Patterns -- Elements of Reusable Object-Oriented Software). The objects dealing with the manufacturer specific details are produced by a factory object which is supplied by the respective manufacturer. To determine which factory to use, OCF deploys a singleton called registry. A registry contains the configuration of an OCF component and creates the corresponding factory objects as needed.

We'll take a closer look at both layers, the CardTerminal layer and the CardService layer, in the next two sections.

The CardTerminal layer

The classes of the CardTerminal layer serve a dual purpose: the most prominent function is to provide access to physical card terminals and inserted smart cards. This function is encapsulated in the CardTerminal class with its slots, and the CardID class.

In OCF, a physical card terminal is represented through the instances of the CardTerminal class. The answer-to-reset (ATR)⁷ is represented in OCF through the CardID class. OCF allows for both static and dynamic configuration. In the case of static configuration, the configuration of card terminals is known a priori at system startup time. In the case of dynamic configuration, on the other hand, additional card terminals (e.g. PC Card-based terminals) can be added at run-time.

The CardTerminal class is an abstract superclass from which concrete implementations for particular card terminal types are derived. Each CardTerminal object contains one or more slots that represent the physical card slots of that card terminal. Access to a smart card that is inserted in a slot occurs through an exclusive gate object, the SlotChannel object: The CardTerminal class ensures that, at any given point in time, a maximum of one SlotChannel object per slot is instantiated. Thus, once an object has obtained a SlotChannel object, no other object can gain access to the associated smart card until that SlotChannel object has been released.

The CardTerminal class provides methods for checking card presence, obtaining a SlotChannel object, and sending and receiving APDUs. For card terminals offering additional functions -- such as a display, a PIN pad, a finger print reader, or other input-output facilities -- OCF provides additional interfaces that a CardTerminal can implement.

The CardTerminal layer also offers a mechanism to add and remove card terminals. The CardTerminalFactory class and the CardTerminalRegistry object implement this function. Each card reader manufacturer supporting OCF provides a CardTerminalFactory which "knows" about a particular family of card readers, and the respective CardTerminal classes. The system-wide unique CardTerminalRegistry object keeps track of the installed card readers -- as illustrated in Figure 2.

Figure 2. Classes of the CardTerminal package. OCF represents a real card terminal through the instances of the CardTerminal class with its slots. With OCF, both static and dynamic configurations are possible.

Furthermore, the CardTerminalRegistry object offers methods to register and unregister CardTerminal objects, and to enumerate all installed card terminals.

The CardTerminal classes generate events and notify the rest of the framework when a smart card is inserted into or removed from a card terminal (CardTerminal). These events are passed on to the EventGenerator by the CardTerminalRegistry (see Figure 3).

Figure 3. The CardTerminal layer. The CardTerminalRegistry keeps track of the available instances of CardTerminalFactory and CardTerminal. Each CardTerminalFactory keeps track of the CardTerminal it instantiated. Each CardTerminal manages its slots into which smart cards can be inserted. Insertion or removal of a smart card will trigger an event at the corresponding CardTerminal, which is passed on to the event package's EventGenerator by the CardTerminalRegistry. The dynamic installation of a CardTerminal does not trigger a special event. The events generated by the new terminal will be automatically passed to all listeners registered at the EventGenerator.

The CardService layer

At the present time, the OpenCard Framework reference implementation defines only a few card service interfaces: FileAccessCardService and SignatureCardService are the most important ones. However, the number of standard card services will increase quickly, as it is the intention of the OpenCard Consortium to define card services for virtually all smart card functions.

FileAccessCardService

FileAccessCardService is OpenCard's abstraction for dealing with smart card based files. It offers a high-level interface modelled after Java's java.io package, making it virtually unnecessary for you to understand the nitty-gritty details of those standards.

SignatureCardService

SignatureCardService is a simple abstraction for the import, verification, and export of key information as well as for the generation and verification of digital signatures generated using a public key algorithm like RSA.

AppletAccessCardService and AppletManagerCardService

In order to address these requirements, card issuers who decide what applications are deployed or planned to be deployed with their cards put additional meta-information in the card that card-external applications can access to find out about - and, if necessary, change - the situation in any particular card.

These functions are handled by two card services: AppletAccessCardService and AppletManagerCardService. AppletAccessCardService is capable of listing applications, while AppletManagerCardService defines a high-level API through which applications can install and remove, card-resident applets in an issuer independent manner.

Programming with OCF

Configuring the OpenCard Framework

Configuring the registries

You can configure CardTerminalRegistry via the OpenCard.terminals property and CardServiceRegistry via the OpenCard.services property.

The syntax of the property string for either property is as follows:

<record-0> <record-1> ... <record-N>

class-name|param-1|param-2| ... |param-N

Property name:

OpenCard.services

Property string:

com.ibm.opencard.factory.MFCCardServiceFactory

Property name:

OpenCard.terminals

Property string:

com.ibm.opencard.terminal.ibm5948.IBMCardTerminalFactory|IBM5948-1|IBM5948-B02|1\
com.ibm.opencard.terminal.pcsc10.Pcsc10CardTerminalFactory

Configuring tracing output

The utility class opencard.core.util.Tracer distinguishes between the following trace levels:

The syntax of the property string is as follows:

<package-prefix:trace-level> <package-prefix:trace-level> ... <package-prefix:trace-level>

The following example illustrates how the property strings might look:

Property name:

OpenCard.trace

Property string:

opencard.core:6 opencard.opt:0 com.ibm.opencard:3 \
com.ibm.opencard.terminal.ibm5948.IBM5948CardTerminal:8

OpenCardPropertyFileLoader

Now let's take a look at how the default properties loader works. OpenCardPropertyFileLoader looks in the following places for property files (in the order given):

1. [java.home]/lib/opencard.properties
2. [user.home]/.opencard.properties
3. [user.dir]/opencard.properties
4. [user.dir]/.opencard.properties

In case you wish to override a property that is already defined in the properties set, you can do this by defining the property name name anew and adding an additional property with the name name.override that has the value true to your property file.

The following example will set the property OpenCard.property to the value new_value no matter what its value was before:

# Overriding a possibly already defined OpenCard property
# with a new value
    OpenCard.property = new_value
    OpenCard.property.override = true

# Configuring the CardServiceRegistry
OpenCard.services = com.ibm.opencard.service.MFCCardServiceFactory
 
# Configuring the CardTerminalRegistry
# The parameters after the class name are:
#        name, type, and address of the card terminal
OpenCard.terminals = \
  com.ibm.opencard.terminal.ibm5948.IBMCardTerminalFactory|IBM5948-1|IBM5948-B02|1 \
  com.ibm.opencard.terminal.pcsc10.Pcsc10CardTerminalFactory
 
# Configuring Tracing
OpenCard.trace = opencard.core:6 opencard.opt:0 com.ibm.opencard:3 \
                 com.ibm.opencard.terminal.ibm5948.IBM5948CardTerminal:8
 
# Overriding OpenCard.property
OpenCard.property = new_value
OpenCard.property.override = true

Loading properties with your own mechanism

You can implement a different property loading that fits your purpose or platform better and have it replace the default mechanism. In order for your property loader to integrate with the framework, it must implement the opencard.core.util.OpenCardConfigurationProvider interface.

You must tell the framework to use your class instead of the default loader. You do that via the following system property:

Property name:

OpenCard.loaderClassName

Property string:

fully-qualified/class/name

Initializing the OpenCard Framework

try {
  SmartCard.start();
 
  // use OCF...
 
} catch OpenCard Exceptions {
  // handle error...
 
} finally {
  try {
    SmartCard.shutdown();
  } catch OpenCard Exceptions {
    // handle error...
  }
}

Waiting for a smart card

The waitForCard method takes as an argument a CardRequest object that lets you further specify the details regarding what card you are looking for and how long you intend to wait. In particular, you can specify that

• any smart card is acceptable, including a card that has already been inserted
• only a newly inserted smart card is acceptable
• the smart card's Answer-to-Reset response must satisfy an arbitrary condition, specified by an instance of CardIDFilter
• the smart card must support a given CardService class or interface
• the smart card must be inserted into a particular card terminal
• the call should return after a given time-out value

Let's assume that we're interested in a smart card supporting FileAccessCardService. We could then write the following code:

SmartCard card = SmartCard.waitForCard(
  new CardRequest(CardRequest.NEWCARD, null, opencard.opt.iso.fs.FileAccessCardService.class));

Obtaining a card service

The actions you have to take depend on the nature of the application. We distinguish between two types of applications: (1) the ones that are prepared to work with only one particular card-resident application, and (2) the ones that can interact with a variety of different (at least two) card-resident applications.

In the first situation, you have probably specified the CardService class that you already required at the time you issued the waitForCard call. The code fragment to obtain e.g. FileAccessCardService looks like this:

FileAccessCardService facs = null;
try {
  facs = (FileAccessCardService)
    card.getCardService(FileAccessCardService, true);
} catch OpenCard Exceptions {
  // handle error...
}

In the situation where your application can interact with several different card-resident applications, you will have to find out what card-resident applications are present. For that purpose, you must obtain AppletAccessCardService, which has a list method that lets you obtain the list of applications on the card. In this case, the code looks something like this:

AppletAccessCardService aacs = null;
try {
  aacs = (AppletAccessCardService)
    card.getCardService(AppletAccessCardService, true);
} catch OpenCard Exceptions {
  // handle error...
}

Handling exceptions

At the root of OCF's exception hierarchy are two classes: opencard.core.OpenCardException and opencard.core.OpenCardRuntimeException. The first is a subclass of Java's IOException and is therefore checked, while the second is a subclass of RuntimeException and is thus unchecked. The distinction is that the latter need not be caught or declared to be thrown (i.e. the compiler does not force you to handle these exceptions - hence the term 'unchecked exception'). The rationale behind this concept is that exceptions of this kind disrupt the normal program flow so severely that continuing would not make much sense. Further, from a pragmatic point of view, it would often be impractical to check for these conditions (an example of this is OutOfMemoryError, which can be thrown practically anywhere in code where objects are created dynamically). Nevertheless, all other exceptions should be dealt with in order to ensure program robustness.

The OCF exception hierarchy branches into two major trunks in the terminal and service sub-packages. The exception classes in the terminal package all extend CardTerminalException, which is itself a subclass of OpenCardException (and therefore checked). In the service package, we have two base exception classes: the CardServiceException class and the CardServiceRuntimeException class. The CardServiceException class extends OpenCardException, while the CardServiceRuntimeException class extends OpenCardRuntimeException. The latter has only two subclasses, which means that the application developer must handle the vast majority of OpenCard's exceptions.

Throughout this guide, for the sake of brevity, a 'catch-all' exception handler has been used in the code samples. However, this is not a style to be recommended in real-world code. So if specific exceptions are thrown in your code, catch them using a specific handler. The most general OCF sample in this guide looks like this:

try {
  SmartCard.start ();      // get OpenCard up and running
                           // here comes your client code
  SmartCard.shutdown ()    // cleanup OpenCard
}
catch (Exception e) {
// catch-all handler
// ...
}

• OpenCardPropertyLoadingException
• ClassNotFoundException
• CardServiceException
• CardTerminalException

try {
  SmartCard.start ();      // get OpenCard up and running
                           // here comes your client code
  SmartCard.shutdown ();
  // cleanup OpenCard
}
catch (OpenCardPropertyLoadingException plfe) {
  // ...
}
catch (ClassNotFoundException cnfe) {
  // ...
}
catch (CardServiceException cse) {
  // ...
}
catch (CardTerminalException cte) {
  // ...
}

Listing applications

The term "applet" as we use it in this documentation can be either a program, which is executed on the card itself (like a typical Java Card applet). Or it can be an application specific set of files and directory structures (as we will find on ISO compliant file system oriented cards). In both cases the AppletID is used to identify the applet in a world-wide unique way. There are standards which define how each smart card should hold a directory of AppletIDs, allowing any card-external application to decide, if it supports a particular card or not

You can obtain the AppletInfos from your SmartCard object using AppletAccessCardService's list method.

AppletInfo [] templates = null;
try {
  AppletAccessCardService aacs = null;
  aacs = (AppletAccessCardService)
       card.getCardService(AppletAccessCardService, true);
  templates = aacs.list();
  // evaluate templates, e.g., present the user a list
  // of applet names from which to select
  // ...
 
} catch OpenCard Exceptions {
  // handle exception
  ...
}

Using the AppletInfo retrieved by the the AppletAccessCardService the correct Applet can now be selected. For example an ISO compliant card can use the AppletID within the select-by-AID command to select the directory which corresponds to a particular application. A Java Card can use the AppletID to select a appropriate Java Applet, which can be executed on the card.

So your code might look something like this:

try {
  // ...
  AppletID aid = template[0].getAid());
  CardFilePath filePath = new CardFilePath(aid.toString());
  // ...
} catch OpenCard Exceptions {
  // handle exception
  ...
}

Working with files

FileAccessCardService

try {
  CardFilePath rootpath = facs.getRoot()
  CardFilePath filepath = new CardFilePath(rootpath);
  filepath.append(new CardFilePath(":c009"));
 
  CardFileInfo rootinfo = facs.getFileInfo(rootpath);
  CardFileInfo fileinfo = facs.getFileInfo(filepath);
} catch OpenCard Exceptions {
  // handle error...
}

The CardFilePath class

try {
  CardFile root = new CardFile(facs);
  CardFile file = new CardFile(root, ":c009");
} catch OpenCard Exceptions {
  // handle error...
}

The second CardFile object is created by passing a parent directory in form of another CardFile object, and a string that contains a relative path from the parent directory to the file to represent with the new CardFile object. The constructor will copy the path of the parent directory, append a relative path created from the string, and invoke getFileInfo to obtain the information about this file. FileAccessCardService used is the one that is stored in the parent CardFile.

Having created a CardFile object, the path to the represented file can be obtained using getPath. Since CardFile implements the CardFileInfo interface, the methods defined there can be invoked directly at the CardFile object. If there is a need to have the CardFileInfo object that was returned by FileAccessCardService --for example to downcast it to an implementation specific type --it can be obtained by invoking getFileInfo at the CardFile object.

The CardFileInput/OutputStream classes

In a similar way, the CardFileReader and CardFileWriter classes extend the java.io classes named InputStreamReader and OutputStreamWriter, respectively. These classes provide file access on a character basis instead of on a byte basis.

The CardRandomRecordAccess class

Signature generation and verification

Generating signatures

SignatureCardService offers the signData method to perform this operation. In addition to the message to be signed, the method needs to know which hash algorithm and public key algorithm to use and which key to use for signing. The private key reference for file-oriented cards consists of a directory CardFilePath object and an integer specifying the number of the key relative to the directory.

The code you have to write looks something like this

byte[] message = ...;
byte[] signature = null;
SignatureCardService scs = null;
try {
  // allocate card service
  scs = (SignatureCardService)
    card.getCardService(SignatureCardService, true);
  // create the private key reference
  CardFilePath path = new CardFilePath(":3F00:C200");
  PrivateKeyFile keyRef = new PrivateKeyFile(path,0);
  // generate signature
  signature = scs.signData(keyRef,"SHA1withRSA",message);
  } catch OpenCard Exceptions {
  // handle exception
  ...
}

Verifying signatures

byte[] message = ...;
byte[] signature = ...;
SignatureCardService scs = null;
try {
  // wait for card and obtain the card service
  // ...
  // create the public key reference
  CardFilePath path = new CardFilePath(":3F00:C200");
  PublicKeyFile keyRef = new PublicKeyFile(path,1);
  // verify signature
  boolean result = scs.verifySignedData(keyRef,"SHA1withRSA", message, signature);
  } catch OpenCard Exceptions {
  // handle exception
  ...
}

Importing keys

RSACRTKey rsaPrivate = ...;
byte[] signature = ...;
byte[] keyInfo = ...;
SignatureCardService scs = null;
try {
  // wait for card and obtain the two card services
  // ...
// create the private key reference for the key to be imported
  CardFilePath path1 = new CardFilePath(":3F00:C110");
  PrivateKeyFile targetKey = new PrivateKeyFile(path1,0);
  // create the public key reference for the key to verify the signature
  CardFilePath path2 = new CardFilePath(":3F00:C200");
  PublicKeyFile valKey = new PublicKeyFile(path2,1);
  boolean result = scs.importAndValidatePrivateKey(targetKey,
                   rsaPrivate, keyInfo, signature, valKey);
  // ...
} catch OpenCard Exceptions {
  // handle exception
  ...
}

Generating keys

The method for generating keys is called generateKeyPair. In addition to the storage destinations for the private and public keys, this method takes as parameters the required key strength and key algorithm. A specific card may not support the required strength and algorithm, and the card service representing the card may throw an appropriate exception.

The method for reading the public key is called readPublicKey. In addition to the key reference for the key to be read, this method takes the required key algorithm as a parameter. No method is available for reading the private key since the private key should never leave the card.

The code for generating a RSA key pair and reading the public key might look like this:

RSAPublicKey rsaPublic = null;
KeyGenerationCardService kgs = null;
try {
  // wait for card and obtain the card service
  // ...
  // create the key references for the keys to be generated
  CardFilePath path = new CardFilePath(":3F00:C110");
  PrivateKeyFile privKey = new PrivateKeyFile(path,0);
  PublicKeyFile pubKey = new PublicKeyFile(path,1);
  kgs.generateKeyPair(privKey, pubKey, 512, "RSA");
  // read the public key from the card
  rsaPublic = (RSAPublicKey) kgs.readPublicKey(pubKey, "RSA");
  // ...
  } catch OpenCard Exceptions {
  // handle exception
  ...
}

Advanced programming with OCF

Working with OpenCard events

In the OpenCard Framework reference implementation, there are a number of objects that can be the source of OpenCardEvent objects that other framework components or the application itself might be interested in. The implementation of the event notification is based on EventObject class and EventListener interface of the java.util package.

Objects that are interested in receiving event notifications must implement some extension of the EventListener interface and register with the proper object by adding themselves as listeners.

As an application programmer, you may be interested in the following types of OpenCard Framework events:

• events signalling that a card was inserted or removed into a card terminal,
• events signalling that a tracer issued a tracing message.

CardTerminalEvent

The CTListener interface defines two methods, cardInserted() and cardRemoved(), through which CardTerminalEvents can be communicated to objects interested in these events.

You can register objects that are interested in receiving CardTerminalEvents provided they implement the CTListener interface. You can register your CTListener with the system-wide EventGenerator instance using the addListener() and removeListener() methods. The registered objects will then receive all CardTerminalEvents produced by all currently-registered CardTerminal objects.

Locking a CardTerminal

There are other scenarios like transferring money from one smartcard to another one where you need to maintain a lock on an individual slot or the whole CardTerminal across card insertions and card removals.

To lock a terminal you can use the methods declared in the opencard.opt.terminal.Lockable interface, as demonstrated in the following example:

// lock terminal
Enumeration terminals =CardTerminalRegistry.getRegistry().getCardTerminals();
CardTerminal t = (CardTerminal)terminals.nextElement();
Lockable terminal = null;
Object handle = null;
if (t instanceof Lockable) {
   terminal = (Lockable)t;
   System.out.println("Locking terminal "+terminal);
   handle = terminal.lock();
}
// now request SmartCard objects and communicate with cards

To release a lock on a locked CardTerminal first destroy all SmartCard objects before calling the unlock function as the following example shows

SmartCard sc = ...
// close down the SmartCard object and unlock the terminal
sc.close();
sc = null;
if (handle!=null) {
   terminal.unlock(handle);
}

For more details on CardTerminal Locking see RFC 17-1 OCF Terminal Locking Mechanism on the OpenCard website.

TracerEvents

Using optional CardTerminal functions

CardTerminal objects expose additional features by implementing corresponding interfaces. The OpenCard Framework reference implementation defines a number of these interfaces in the opencard.opt.terminal package. They include:

UserInteraction

This interface comprises the display() method to present a message to the cardholder, the clearDisplay() method to erase the message from the display, the keyboardInput() method to collect a string entered by the cardholder, and the promptUser() convenience method, which combines displaying the message to and collecting input from the cardholder into a single call.

PowerManagementInterface

This interface comprises the powerUpCard() and powerDownCard() methods, both of which take the slot number as a parameter and allow the supply of power to the smart card in the designated slot to be controlled. This function is useful with long lasting applications that only sporadically interact with the smart card in environments where low power consumption matters, e.g. PDAs and hand-held computers.

TerminalCommand

This interface comprises the sendTerminalCommand() method, which takes a byte array and sends it to the card reader. Assuming an application knows the set of commands that a given card reader supports, it can use this interface to control the card reader.

Let's assume that you would like to make use of the UserInteraction function in your application. This is the code you would use:

try {
  // initialize framework
  SmartCard.start();
  // wait for a card to be inserted
  // any new card will do; any reader will do
  SmartCard card = SmartCard.waitForCard(new CardRequest());
 
  // get the card terminal in which the card was inserted
  CardTerminal terminal = card.getCardID().getSlot().getCardTerminal();
 
  String name = null;
 
  // check whether it supports UserInteraction
  if (terminal instanceof UserInteraction.class) {
    // we can prompt user using the terminals I/O capabilities
    // assuming we accept all letters, allLetters might be a string containing
    //     all characters in upper and lower case plus blank
    // assuming a LF or CR terminate the input, terminator might be a
    //     string containing "\n\r"
    name = terminal.promptUser("Please enter your name:",
                    new CardTerminalIOControl(0, 60, allLetters, terminator));
  } else {
    // put code here to prompt user in a different way, e.g. through a GUI
    // ...
}
 
  // do something with the name
  if (name != null) {
  // put your code here
  }
} catch OpenCard Exceptions {
  // exception handling
  // ..
}

Getting a smart card via event-notification

In the event-driven programming model, an application suspends its execution after initialization. The execution resumes when the application receives an event that has to be processed. Events can be received from various sources. For example, there may be timer events that trigger regular actions, like auto-saving in an editor. Other events can originate from network connections, indicating external request. The kind of events we are interested here are the result of user input. The Java Abstract Window Toolkit (AWT) sends events when the user moves the mouse, or presses a key on the keyboard. Likewise, the OpenCard Framework sends events when the user inserts or removes a smart card. The key advantage of the event-driven paradigm is that a single application thread is sufficient to process events from various sources. In the application-driven paradigm, a thread has to block on a single source of input, for example the waitForCard call that is used to wait for insertion of a smart card.

In order to receive events, an application has to register at a source of events. In OCF, the central source for events is EventGenerator. An object implementing the CTListener interface has to be passed to the registry, which will invoke the methods of that object at the appropriate time. The argument to each invocation is a CardTerminalEvent that includes details about what happened where. Take a look at this example:

import opencard.core.event.CTListener;
import opencard.core.event.CardTerminalEvent;
import opencard.core.event.EventGenerator;
import opencard.core.terminal.Slot;
import opencard.core.terminal.CardTerminal;
import opencard.core.service.SmartCard;
 
public class Listener implements CTListener {
  private SmartCard smartcard = null;
  private CardTerminal terminal=null;
  private int slotID = 0;
 
 
  public void register()
  {
    EventGenerator.getGenerator().addCTListener(this);
    try {
      EventGenerator.getGenerator().createEventsForPresentCards(this);
    } catch (Exception e) {
      e.printStackTrace(System.err);
    }
  }
 
  public void unregister()
  {
    EventGenerator.getGenerator().removeCTListener(this);
  }
 
  public void cardInserted(CardTerminalEvent event)
  {
    if (smartcard == null) {
      try {
        smartcard = SmartCard.getSmartCard(event);
        terminal = event.getCardTerminal();
        slotID = event.getSlotID();
      } catch OpenCard Exceptions {
        // handle error...
      }
    }
  }
 
  public void cardRemoved(CardTerminalEvent event)
  {
    if ((event.getSlotID() == slotID) &&(event.getCardTerminal()==terminal)) {
      smartcard = null;
      terminal = null;
      slotID = null;
    }
  }
}

Now that we know what happens when an event occurs, how can we make sure that the events are passed to our Listener object? That's what register does. It registers Listener at CardTerminalRegistry by invoking addCTListener. From then on, every card insertion or removal results in an invocation of the cardInserted and cardRemoved methods. There remains one problem: What about smart cards that have been inserted before our listener was registered? We may want to know about them, too. This is achieved by invoking the createEventsForPresentCards method. This method scans all terminals and slots, and creates events for any cards present in the slots. These events are not sent to just any event listener, but instead only to the one that is passed as an argument. That way, other applications will not receive card insertion events for cards they already know of. Since scanning the slots may result in exceptions being thrown, some error handling has to be done at this point. If a card is inserted between registering and the following invocation of createEventsForPresentCards, the listener may get two events for that card. Double events can be filtered out by checking the slot from which they originate.

The counterpart to the register method is unregister. It removes a listener from the set of objects that will be notified about new events. Some spurious events may still be reported to the removed listener if an event broadcast operation is already in progress.

Obtaining a smart card from a particular card terminal

Correspondingly, you have to write your application so that it looks for a particular card terminal or slot and gets a SmartCard object once a physical smart card has been inserted. The system-wide CardTerminalRegistry instance offers the getCardTerminals() method, which returns an Enumeration of all CardTerminal objects presently registered. You get a reference to the CardTerminalRegistry instance through the getRegistry() class method. Once you have obtained the Enumeration of CardTerminal objects, you can walk through it and determine the one you are looking for.

Your code to identify the proper terminal might look something like this:

try {
  // initialize framework
  SmartCard.start();
 
  // get the enumeration of presently registered card terminals
  Enumeration terminals = CardTerminalRegistry.getRegistry().getCardTerminals();
 
  // iterate over terminals to get the first instance of proper type
  String wantedType = new String("IBM5948-B02");
  CardTerminal terminal = null;
  while (terminals.hasMoreElements()) {
    terminal = (CardTerminal) terminals.nextElement();
    if (terminal.getType() .equals(wantedType)) {
      wanted = terminal;
      break;
    }
  }
 
  // do something with the wanted terminal
  // ...
} catch OpenCard Exceptions {
  // handle exception
  // ...
}

Gaining exclusive access to the smart card

In your applications, you can acquire a mutex context by calling the beginMutex() method and release it by calling endMutex() on the SmartCard object. For the application to be well-behaved, you should claim the mutex context for as short a period as possible to avoid unnecessarily blocking other applications (or threads) from accessing the card.

Referencing files

Referencing by file identifier:

Files may be referenced by a file identifier coded in two bytes. For uniqueness, EFs (files) and DFs (directories) under a common DF shall have different file identifiers. The MF (root directory) shall have a file ID of hexadecimal value 0x3f00.

Referencing by path:

Files may referenced by a path, i.e. a concatenation of file identifiers. The path begins with the identifier of the MF or of the current DF, the order of the identifiers is parent to child. In case the identifier of the current directory is unknown, a hexadecimal value of 0x3fff can be used instead (reserved value).

Referencing by short EF identifier:

EFs can be referenced by a short EF identifier coded on five bits with values in the range from 1 to 30. The value 0 is used to reference the currently selected EF. Short EF identifiers cannot be used in a path or as a file ID.

Referencing by DF name:

DFs can referenced by a DF name coded in one to sixteen bytes. For uniqueness, DFs within a card shall have different DF names (see also the specification of application identifiers).

String representations of file references have to conform to the following syntax:

• A single file ID starts with a colon (":") followed by four hexadecimal digits¹³ . Example: The master file (MF) of an ISO file system card is represented by the strings ":3f00" or ":3F00".
• A short file ID starts with a colon (":") followed by two hexadecimal digits representing the 5-bit value of the identifier. Example: the short file ID 20 (decimal) is represented by the string: ":14".
• An application identifier (or DF name) starts with a hash ("#") followed by an even number of hexadecimal digits specifying the byte values of the application identifier.
• An application identifier (or DF name) in string notation does not start with a special character. It consists of a sequence of ASCII characters which specify the byte values of the application identifier.

In addition to supporting certain file referencing methods, the OpenCard Framework reference implementation offers referencing files via symbolic file names.
 
 

Smart cards do not commonly support symbolic names directly, i.e. the symbolic names specified in the card-external application must eventually be resolved into one of the ISO-defined file references. Typically, this resolution is done by the CardService layer and is not something the application programmer is concerned with directly. However, since not all implementations will support symbolic names, that the documentation accompanying the particular card services in use be checked.

Apart from simply improving the readability of applications, symbolic path names imply an additional redirection when referencing files in the card. This redirection can be used by card issuers to their advantage by letting them allocate ISO-based file IDs independently of the application logical file structure. The net benefit to application programmers is that the application becomes more portable by being independent of the details of file reference usage.

Working with credentials

1. The card-external application authenticates itself to the card-resident application. In smart card parlance, this is called External Authentication.
2. The card-resident application authenticates itself to the card-external application. In smart card parlance, this is called Internal Authentication.
3. The cardholder authenticates him or herself to the card. In smart card parlance, this is called Cardholder Verification (CHV).

Mutual authentication typically relies on a challenge-response protocol involving the computation of a response to a challenge using some cryptographic keys shared between challenger and responder. Cardholder verification typically relies on the cardholder proving his identity by revealing a shared secret (such as a password or PIN code) or by presenting a biometric characteristic such as a finger print or retina pattern scan. The card-resident application usually occupies a directory (DF) and all the files underneath it.¹⁴

Accordingly, granting access to an application can be equated with granting access to a directory. Access conditions to files in the file system of a smart card are typically defined during layout specification (see also Developing applications using OpenCard Framework.)¹⁵ To abstract from file-system oriented cards, we call this a security domain. The access conditions for internal authentication rely on cryptographic key(s) stored in the card as part of the card-resident application, while the access condition for external authentication relies on cryptographic key(s) provided by the card-external application. For access conditions involving CHV, see Performing cardholder verification.

The cryptographic algorithms used in the computations of access conditions can vary between different types of smart cards. Accordingly, in situations where a card-external application has to interact with card-resident applications protected via different cryptographic mechanisms, the card-external application must be able to provide cryptographic keys for all these mechanisms.

Now what does this all mean to application programmers? It means that they must have a way to make available in their (card-external) application proper credentials (most often cryptographic keys or certificates) that fit the access conditions of the files which the given application is supposed to interact with.

The OpenCard Framework has hooks in the package called opencard.opt.security that allow the application programmer to do just that: Interface SecureService has a method called provideCredentials which allows the application to pass a bag of credentials for a security domain. Sample card services that implement this interface are FileAccessCardService or SignatureCardService.

Within CredentialBag, the credentials are organized as follows: CredentialBag contains a CredentialStore for each type of card that is supported by the application called /SecurityDomain. Each CredentialStore conceptionally is a dictionary of key/value pairs that associate a key with a Credential. A Credential usually represents a key and the associated algorithm needed to perform a cryptographic function.

Since some of these concepts are implemented differently for specific cards, the OpenCard Framework provides only such abstract classes as CredentialStore or (tag) interfaces like SecureService, Credential, SignCredential, SymmetricCredential, and PKACredential where standardization is not yet achieved. The card service implementer for a specific card must implement these interfaces or subclass the abstract classes.

In those cases in which we see enough commonality between different cards, the OpenCard Framework provides concrete implementations of Credentials like RSASignCredential and DSASignCredential used to perform external authentication using public key algorithms. Other concrete credential implementations may be added over time.

As an application programmer using a specific card service, you thus have to instantiate the appropriate subclasses of the Credentials interfaces matching the used card services. You then put the credentials in the CredentialStore subclasses provided by the card service and add them to a CredentialBag. Finally, you make the credentials available by invoking the provideCredentials method of the card service needing the credentials.

In the example pseudo code below, we assume the application has to interact with two types of smart cards with cryptographic algorithms relying on DES 18 and RSA 19, respectively. The corresponding DESSignCredential class and VendorXCredentialStore classes are provided by the respective card vendors (who also provide the FileAccessCardService implementations).

  // instantiate DES keys
  DESSignCredential desCred0 = new DESSignCredential(...);
  DESSignCredential desCred1 = new DESSignCredential(...);
  // instantiate key store for DES type smart cards
  VendorXCredentialStore desStore = new VendorXCredentialStore();
  // add credentials to store under a lookup number
  desStore.storeCredential(new Integer(0), desCred0);
  desStore.storeCredential(new Integer(1), desCred1);
  // instantiate private RSA keys
  RSASignCredential rsaCred0 = new RSASignCredential(...);
  RSASignCredential rsaCred1 = new RSASignCredential(...);
  // instantiate key store for RSA type smart cards
  VendorYCredentialStore rsaStore = new VendorYCredentialStore();
  // add credentials to store under a lookup number
  rsaStore.storeCredential( new Integer(0), rsaCred0);
  rsaStore.storeCredential( new Integer(0), rsaCred1);
  // instantiate credential bag for the application's security domain
  CredentialBag credBag = new CredentialBag()
  // add stores to bag
  credBag.addCredentialStore(desStore);
  credBag.addCredentialStore(rsaStore);
 
  // work with smart card
  try {
 
    // wait for smart card
    SmartCard sc = SmartCard.waitForCard(
    new CardRequest(opencard.opt.iso.fs.FileAccessCardService.class));
    // get file system card service
    FileAccessCardService fscs =
    card.getCardService(opencard.opt.iso.fs.FileAccessCardService.class, false);
    // for file oriented card use a path as security domain
    CardFilePath domain = new CardFilePath(":3F00:C110");
    // add root key bag
    fscs.provideCredentials(domain, credBag);
    // keep going
    // ...
 
  } catch OpenCard Exceptions {
  // ...
}

Performing cardholder verification

The prompting of the cardholder and the acquisition of the CHV data can be performed in one of two ways:

GUI-based

The cardholder is presented with a GUI that prompts for input of the CHV data. The assumption here is that the application is running in a general purpose computing device with display and keyboard or pen input and a smart card reader attached to it.

Terminal-based

The cardholder is prompted for input by the card terminal. The assumption here is that the card terminal has a built-in (simple) display and keyboard or PIN pad.

Provided a card terminal supports terminal-based CHV, which is the case if the corresponding CardTerminal subclass implements the VerifiedAPDUInterface interface, the OpenCard Framework reference implementation will use this terminal capability for increased security. In other words, you as an application programmer cannot enforce the GUI-based approach. At present, the OpenCard Framework has not architected a way for you to specify the prompt statement that gets presented to the user. Check the documentation of your card service implementation for a possibility to specify this string.

In case a card terminal does not support terminal-based CHV, the OpenCard Framework reference implementation will use the GUI-based approach. In this case, you have the option of either accepting the default GUI dialog implemented in the DefaultCHVDialog class or implementing your own GUI dialog and registering it with the CardService object. Your GUI component must implement the CHVDialog interface. You register it via the CardService object's setCHVDialog() method, which takes your GUI instance as the argument.

The fact that the OpenCard Framework reference implementation does not give the programmer the choice between GUI-based and terminal-based CHV acquisition may at first seem arbitrarily restrictive. However, the impact on security in return for freely providing a choice contradicts the design objectives of the OpenCard Framework and, in most cases, would contradict the original intent that motivated the use of smart cards to secure an application in the first place.

Using the trace utility

The OpenCard Framework reference implementation internally makes use of a tracing utility implemented in the Tracer class. You can use this utility for your own purposes when developing your application. The Tracer class distinguishes a total of eight different trace levels and can be configured via the OpenCard.trace system property (see Configuring tracing output). For each trace level, the Tracer class offers two methods to issue a trace message, one taking a String object as a message parameter, the other taking a Throwable object instead.

The code of a class of yours using the Tracer class might look something like this:

public class MyClass {
 
  // instance tracer
  private Tracer itracer = new Tracer(this, MyClass.class);
 
  // class tracer
  private static Tracer ctracer = new Tracer(MyClass.class);
 
  public MyClass() {
    // ...
    ctracer.info("<init>", "initializing");
 
    // ...
}
 
public void someMethod() {
  // ...
  itracer.debug("someMethod", "something's fishy here");
 
  // ...
  try {
    // ...
  } catch OpenCard Exceptions {
    // ...
    itracer.critical("someMethod", e);
 
    // ...
    }
}

Using the OpenCard Framework in applets

The following chapter describes both alternative approaches:

• using the more portable pure java approach of the Java Plug-IN
• using the proprietary security mechanisms of the browsers

Usage scenario

The security model of the Java Platform 1.1

The security model of the Java Platform 1.2

The Java Plug-In

Writing secure applets with OCF and the Java Plug-In

http://www.javasoft.com/products/plugin/

As these HTML documents are all instrumented with the special tags, your browser will note that the Plug-in is not installed yet on your local machine and offer to download it. Well, there's no reason to turn down this offer here;-) so go ahead and get the chunk of about 5 MB. Install the thing and start your browser anew. After that, visit the above mentioned demo site and try one of the samples again. This should now bring up the Plug-in console window, and the demos should work. If this is not the case, check the Plug-in's FAQ (chances are the problems are caused by proxies).

There are basically two ways of getting a certificate: buying one or making one. The latter case is acceptable only for testing purposes because everyone can do that (including some not-so well behaved hacker or criminal). The bottom line is that everyone should be very suspicious of code that may have been signed while the certificate coming with it was not issued by an official Certification Authority. These are companies (e.g. VeriSign, Thawte) that officially confirm that individuals or organizations/companies are who they claim to be. To this end, they'll give the certificate requester a digital certificate signed by them. The certificate can then be used by developers (that means you;-) to digitally sign their code (e.g. applets). The recipient of the code is then able to check whether or not the code was changed during transmission and that it indeed does come from the one who claims he sent/provided it.

The Certification Authorities have digital certificates themselves which are stored by default in the browsers which are thus able to check certificates coming with digital signatures in some code downloaded from the Internet. If you nonetheless want to create a so called "self-signed" certificate for testing purposes, we'll show you how to do that in the sections below which are specific to the Java Platform 1.1 and 1.2.

Once you have a certificate, you can use it to sign your code. To do that, the code must be packaged into a Jar archive. Signing the archive will cause it to increase in size slightly as some data will be added to it. After you have written the HTML document using your applet (and tested it locally with the Appletviewer), you must adapt it to use the special tags required for the Plug-in. Using the HTML converter for this chore is easiest.

Now you are ready to deploy the converted HTML document along with the applet archived in a Jar file. Move it to your web server and test it.

Differences in the procedure between Java Platform 1.1 and 1.2

• creating and storing a self-signed certificate
• signing an archive
• importing a certificate.

Writing secure applets with OCF for Java Platform 1.1

1. Creating and storing a self-signed certificate (if not using an official certificate).
• Create an identity in the identity database:

    javakey -cs <identityName> true
    // e.g. javakey -cs "Mike" true

• Create a certificate directive file, which basically is a simple ASCII text file e.g.

    issuer.name=Mike
    issuer.cert=1
    subject.name=Mike
    subject.real.name=Mike Wendler
    subject.org.unit=SC
    subject.org=IBM
    subject.country=GE
    start.date=18 Jun 1997
    end.date=15 Sep 1998
    serial.number=1001
    out.file=MikesCert4J11.cer

• Generate a certificate:

    javakey -gc <certification_directive_file>
    // e.g. javakey -gc MikesCertDirective

2. Digitally sign an archive.
• Create a signing directive file, which basically is a simple ASCII text file as well, e.g.

    signer=Mike
    cert=1
    chain=0
    signature.file=MIKESIGN
    out.file=SignedApplet.jar

• Sign the archive:

    javakey -gs <sign_directive_file>
    // e.g. javakey -gs MikesSignDirective

Using secure applets with OCF for the Java Platform 1.1

1. Create a new trusted identity in your keystore (which is being created if it does not already exist)

    javakey -cs <identityName> true
    // e.g. javakey -cs "Mike" true

2. Import the certificate of the new trusted identity into the local keystore:

    javakey -ic <identityName> <certificateFile>
    // e.g. javakey -cs "Mike" MikesCert4J11.cer

3. Download the HTML document with the desired applet from the web server.


Steps 4 - 7 are only required if you haven't installed the Java Plug-in before.

4. Download the Plug-in when prompted and install it.
5. After installation, activate the Java Plug-in control panel and select the "Advanced" tab. In the Java Runtime Environment section, select one of the one or more versions of JDK 1.1 that should be listed there.
6. If the only proxy you use is a SOCKS, you'll have to set an alternative http proxy in the "Proxies" section of the Java Plug-in control panel. (The Java Plug-in cannot handle SOCKS servers).
7. Start your browser anew and fetch the corresponding HTML document again (step 3).

Writing secure applets with OCF for the Java Platform 1.2

1. Create and store a self-signed certificate (if not using an official certificate):
• Create a key pair in the identity database:

    keytool -genkey -alias <aliasName> -keystore
    <keystoreName> -keypass <keyPassword>
    -dname <x500Name> -storepass <keystorePassword>
    // e.g. keytool -genkey -alias Mike -keystore .keystore
    // -keypass Mikeskeypass -dname "cn=Mike" -storepass Mikesstorepass

Export the self-signed certificate:

    keytool -export -alias <aliasName> -file <certificateFileName>
    // e.g. keytool -export -alias Mike -file MikesCert4J12.cer

2. Digitally sign an archive:

    jarsigner -storepass <keystorePassword> -keystore <keystoreName>
    -keypass <keyPassword> <JarArchive> <aliasName>
    // e.g. jarsigner -storepass Mikesstorepass -keystore .keystore
    -keypass Mikeskeypass SignedApplet.jar Mike

Using secure applets with OCF for the Java Platform 1.2

1. If you have not already done so, install the latest version of JDK 1.2 and update your environment accordingly.
2. If you do not already have a .java.policy file in your user.home directory, provide one. This file determines what actions foreign applets are allowed to carry out on your local machine. A possible policy file (setting all required privileges for the Internet Broker demo) may look like this:

// this keystore is to store our certificates
keystore ".keystore";
 
// a grant entry suitable for the Internet Broker Demo
// allows ALL applets that were signed by "Mike" to carry out the following actions
grant signedBy "Mike" {
    // read and write arbitrary (including sensitive) system properties
            permission java.util.PropertyPermission "*", "read,write";
 
    // read the 'opencard.properties' file in the standard locations
            permission java.io.FilePermission "${java.home}/lib/opencard.properties", "read";
            permission java.io.FilePermission "${user.home}/.opencard.properties", "read";
            permission java.io.FilePermission "${user.dir}/opencard.properties", "read";
            permission java.io.FilePermission "${user.dir}/.opencard.properties", "read";
 
    // dynamically load native libraries
    permission java.lang.RuntimePermission "loadLibrary.*";
 
    // get access to declared constructors/methods/fields via reflection API
    permission java.lang.RuntimePermission "reflect.declared.*";
};

3. Import the certificate into your keystore (which is being created if it does not already exist):

keytool -import -alias <aliasName> -file <certificateFile>
    -storepass <yourKeyStorePasswordHere>
    // e.g. keytool -import -alias Mike -file MikesCert.cer
    -storepass <yourKeyStorePasswordHere>

4. If you don't already have one, create a Jar archive of OCF on the local machine and sign it with either a self-signed or an "official" certificate.
5. Download the HTML document with the desired applet from the web server.


Steps 6 - 9 are required only if you haven't installed the Java Plug-in before.

6. Download the Plug-in when prompted and install it.
7. After installation, activate the Java Plug-in control panel and select the "Advanced" tab. In the Java Runtime Environment section, select one of the one or more versions of JDK 1.1 that should be listed there.
8. If the only proxy you use is a SOCKS, you'll have to set an alternative http proxy in the 'Proxies' section of the Java Plug-in control panel (e.g. proxy.de.ibm.com/ on port 80). (The Java Plug-in cannot handle SOCKS servers).
9. Start your browser anew and fetch the according HTML document again (step 3).

Native Browser support

• the applet is signed using the vendor specific signing process
• the applet calls proprietary APIs to request the required privileges

The following instructions outline the procedures to get signed applets working under some browsers' proprietary Java virtual machines.

The opencard.core.util.SystemAccess class

To avoid vendor specific calls in the OCF pure java code base this browser specific code has been isolated in the singleton class SystemAccess. By default OCF is configured with classopencard.core.util.SystemAccess which does not contain browser specific code. This works fine when using the Java Plug-In JVM or when using Java applications. When running OCF under a browser's VM a browser specific SystemAccess class should be configured as follows before the SmartCard.start() method is invoked:

public void init() {
...
opencard.core.util.SystemAccess sys =
  new opencard.opt.vendorX.VendorXSystemAccess();
opencard.core.util.SystemAccess.setSystemAccess(sys);
...
SmartCard.start();
...
}

To make sure the browser specific SystemAccess class is considered part of the signed applet the class file must be packaged as part of the signed applet and must not be contained in the system class path of the browser environment.

Writing secure applets with OpenCard and Netscape Communicator

Install the OpenCard base components in a local directory. The CLASSPATH environment variable should point to the OCF class or jar files in the environment where the browser is invoked.

If the configured card terminals need native libraries, the DLLs should be placed in the \program\java\bin directory of the Netscape product tree.

OpenCard searches in java.home, user.home and user.dir directories for its properties file. "java.home" is unset under Netscape, "user.home" is set to \Netscape\Users\<userid>\ and "user.dir" is set to the current directory of the browser. The recommendation is to install a <netscape-product-path>\Netscape\Users\<youruserid>\.opencard.properties file.

Add the following code to the init() method of your applet:

opencard.core.util.SystemAccess sys =
  new opencard.opt.netscape.NetscapeSystemAccess();
opencard.core.util.SystemAccess.setSystemAccess(sys);

Writing secure applets with OpenCard and Microsoft Explorer

Install the OpenCard base components in a local directory. The CLASSPATH environment variable should point to the OCF class or jar files in the environment where the browser is invoked.

If the configured card terminals need native libraries, the DLLs should be placed in a directory contained in the PATH environment variable.

OpenCard searches the following paths under Microsofts JVM:

java.home:
C:\WINNT\Java\lib\opencard.properties,
C:\WINNT\Java\.opencard.properties
user.home:
C:\WINNT\Profiles\<youruserid>\Desktop\opencard.properties,
C:\WINNT\Profiles\<youruserid>\Desktop\.opencard.properties

Add the following code to the init method of your applet:

opencard.core.util.SystemAccess sys =
  new opencard.opt.ms.MicrosoftSystemAccess();
opencard.core.util.SystemAccess.setSystemAccess(sys);

Writing a CardTerminal

Implementing a CardTerminal

It is convenient to divide CardTerminal implementation into three layers. Depending upon the specific circumstances of your case, you may have to implement all three layers or you may be able to improvise using pre-existent parts.

interface layer

This layer is derived from the abstract CardTerminal class. It provides the methods for interfacing with the upper part of the framework.

function layer

This layer encapsulates the detailed knowledge about your reader.

communication layer

This layer provides methods for handling the transfer of the data between the host (your computer) and the card reader.

The interface layer

Important methods

• Constructor
• open() and close()
• isCardPresent()
• getCardID()
• powerUpCard()
• internalFeatures()
• internalReset()
• internalSendAPDU()

The Constructor

The following is a sample Constructor for a card reader possessing a single slot:

protected MyCardTerminal(String name, String type, String device)
    throws CardTerminalException {
 
  super(name, type, device);
  addSlots(1);
}

The open() and close() methods

The isCardPresent() method

The getCardID() method

As a rule, you can't return the ATR without explicitly powering up the card. But you should determine whether you've already powered up the card before. Otherwise, you might cause a repower -- equivalent to resetting the smart card -- which can prove very confusing for your application. Luckily, it's quite easy to check whether the card has been powered up before if you cache the ATR on every power-up and reset this cache (set to null) every time a card is removed.

There are two getCardID methods. One has an additional parameter: int ms. This timeout was used in previous releases and should now be ignored. It is not meant to wait for a card insertion if no card is available in the requested slot. In this case, you should throw a CardTerminalException with a message in plain language (e.g.: "no card inserted").

You should write your implementation code using the getCardID(int slotID) method. The other getCardID(int slotID, int timeout) method with the timeout parameter only invokes the first method without passing on the timeout value (which is to be ignored anyway).

Sample code for a single-slot reader:

private byte[] cachedATR = null;
 
public CardID getCardID(int slotID)
                    throws CardTerminalException {
  CardID cardID = null;
 
  if (isCardPresent(slotID)) {
    // check if ATR was already read
    // (if card is already powered)
    if (cachedATR == null)
      // card must be previously powered
      cardID = new CardID(getSlot(slotID),
                          powerUpCard(slotID));
 
    else
      // card was already powered
      cardID = new CardID(getSlot(slotID), cachedATR);
  } else
    // invalidate the cached ATR
    cachedATR = null;
 
  return cardID;
}
 
public CardID getCardID(int slotID, int timeout)
          throws CardTerminalException {
 
    return getCardID(slotID);
}

The powerUpCard() method

The internalFeatures() method

protected Properties internalFeatures(Properties features) {
  features.put("FEATURE", "VALUE");
  return features;
}

The internalReset() method

The internalSendAPDU() method

The caller of the internalSendAPDU() method wraps the card-specific commands in a CommandAPDU object. The CommandAPDU class incorporates a further method named getBytes(), which provides a means of extracting the whole command as a byte array.

Generally speaking, it is necessary to distinguish between two cases, depending upon whether the card protocol is based on the T0 protocol or on the T1 protocol.

The limitation of the T0 protocol is that it doesn't have the ability to send and receive APDUs with both additional data fields at the same time. In this case (known as the "case four" command -- see ISO 7816-4), you have to initiate a receive command after the send command in order to get all of the information from the card.

If the card protocol is based on T1, you are provided with a reader command that can exchange data in both directions in one step.

The following sample code disregards the issue of card protocol:

protected ResponseAPDU internalSendAPDU(int slotID,
                                        CommandAPDU capdu, int timeout)
       throws CardTerminalException {
 
  ResponseAPDU responseAPDU = null;
  byte[] receiveBuf = null;
 
  try {
    responseBuf = functionLayer.exchange(slotID,
                                         capdu.getBytes(), timeout);
    if (receiveBuf != null)
      responseAPDU = new ResponseAPDU(responseBuf);
 
  } catch (RuntimeException re) {
    throw new CardTerminalException(re.toString());
  } catch OpenCard Exceptions {
    throw new CardTerminalException(e.toString());
  }
 
  return responseAPDU;
}

Polling

Polling using EventGenerator/CardTerminalRegistry

Sample code for a single-slot reader:

private boolean cardIsInserted = false;
 
public void poll() throw CardTerminalException {
  if (!closed) {
    UpdateSlotStatus(0);// update the cache for slot 0
    if (!cardIsInserted) {        // what's the last status of the terminal?
      if (isCardPresent(0)) {
        cardIsInserted = true;
        cardInserted(0);          // distribute the news to all listeners
      }
    } else {
      if (!isCardPresent(0)) {
        cardIsInserted = false;
        cardRemoved(0);           // distribute the news to all listeners
    }
  }
}

Polling using your own thread

Event-driven recognition of reader states

Event-notification

Synchronization

Sample code:

private Object readerMonitor = "reader monitor";
.
.
void exampleReset(int slotID) throws CardTerminalException {
  try {
    synchronized(readerMonitor) {
      functionLayer.reset(slotID);
      functionLayer.powerUp(slotID);
    }
  } catch OpenCard Exceptions {
    throw new CardTerminalException(e.toString());
  } }

The function layer

The Function Layer is needed because the interface layer knows nothing about a concrete command sequence used for powering up a smart card. This command could be a byte sequence like 6Eh 00h 00h 00h (this sequence sent to a GemPlus GCR410 powers a smart card within the first slot).

It's possible to write to code of the function layer into the same CardTerminal class file, but it's logically separated.

Generally speaking, you need at least the following functionalities:

• the open() and close() methods for initializing the function layer,
• a suitable Constructor matching your configuration requirements (with parameters for the device names, address, line speed, and whatever else you might need),
• a method for getting status information from a slot,
• a method for powering up and powering down the smart card,
• a method for ejecting a smart card (if applicable) -- often in combination with the power-down mechanism, and
• a method to initiate a smart card reset.

There are two ways of implementing this layer:

• Pure Java implementation and
• native code via JNI if you want to use an existing native code library (like a DLL) to connect to your reader.

Pure Java implementation of the function layer

Pure Java implementation has one big advantage: the reuseability of code for multiple platforms. One possible drawback: Writing the implementation may prove more complicated because it is also necessary to implement the communication layer. The only thing you have to do is to provide the set of functionalities listed above (see page ***) and to translate the requests into a format your reader understands.

Sample code for exchanging data between your terminal and the reader:

protected byte[] exchange(byte[] sendData, int slotID, int timeout)
                     throw CardTerminalException {
 
  byte[] responseBuf = null;
  byte[] tempBuf = null;
 
  try {
      // assemble exchange command for reader
      byte[] sendCommand = new byte[sendData.length + 1];
 
      // insert the exchange command identifier
      // and append the content of sendData
      // (only valid for T1 cards)
      sendCommand[0] = (byte)0x15;
      System.arraycopy(sendData, 0,
                      sendCommand, 1,
                      sendData.length);
 
      tempBuf = communicationLayer.transmit(sendCommand);
 
      // copy tempBuf to responseBuf
      // without copying the additional status information
      // appended by the reader
      responseBuf = new byte[tempBuf.length - 1];
      System.arraycopy(tmpBuf, 1,
                      responseBuf, 0,
                      responseBuf.length)
 
    // remap all runtime-exceptions to CardTerminalException
    } catch (RuntimeException re) {
      throw new CardTerminalException(e.toString());
    }
    return responseBuf;
  }

Native code implementation of the function layer (via JNI)

http://www.javasoft.com/docs/books/tutorial/index.html

The communication layer

In order to simplify implementation of the Communication Layer, we recommend that you use the javax.comm extension as a basis whenever possible.

Implementing the Lockable interface

To implement this interface the CardTerminal must do some additional security checks when a SlotChannel is requested or other functions on the terminal are invoked. To reduce the task of implementing these security checks the framework comes with a convenience abstract class opencard.opt.terminal.AbstractLockableTerminal. This class does most of the checking for you. If you derive your Lockable CardTerminal from this class you only need to implement some terminal specific methods which actually do the locking/unlocking like

• internalLock()
• internalUnlock()
• internalLockSlot()
• internalUnlockSlot()
• lockabelOpenSlotChannel()

Implementation of a CardTerminalFactory

If you have extended the requirements made of your factory -- for example by requiring the connection to a resource manager with the simultaneous instantiation of multiple terminals -- you'll probably need the open() and close() methods for initialization (see also The open() and close() methods).

Using createCardTerminals(), you're able to simultaneously create multiple terminals, thus enabling you to get a list from an alien resource manager about its registered terminals and instantiate them in one piece.

The following sample code pertains to a terminal with one additional parameter:

public class SiemensCardTerminalFactory
        implements CardTerminalFactory {
 
    public void createCardTerminals(CardTerminalRegistry ctr,
                                    String[] terminalInfo)
        throws CardTerminalException,
               TerminalInitException {
 
      // check for minimal parameter requirements
      if (terminalInfo.length < 2)
        throw new TerminalInitException(
                      "at least 2 parameters necessary"
                      + " to identify the terminal");
 
      // check the given type
      if (terminalInfo[1].equals("MYMODEL")) {
 
        // optional: check for an additional parameters...
        if (terminalInfo.length != 3)
          throw new TerminalInitException(
                        "createCardTerminals: "
                        + "Factory needs 3 parameters "
                        + "for snuggle terminal");
 
        // creates the terminal instance
        // and registers to the CardTerminalRegistry
        ctr.add(new MyCardTerminal(terminalInfo[TERMINAL_NAME_ENTRY],
                                   terminalInfo[TERMINAL_TYPE_ENTRY],
                                   terminalInfo[TERMINAL_ADDRESS_ENTRY]));
                                   // these three TERMINAL variables are
                                      defined in CardTerminalFactory
    } else
        throw new TerminalInitException("Type unknown: "
                                        + terminalInfo[TERMINAL_NAME_ENTRY]);
  }
 
  public void open() throws CardTerminalException {}
  public void close() throws CardTerminalException {}
}

Writing a card service

CardService environment -- overview

Also, an OpenCard CardService implementation must provide functions that are used by the framework itself for administration purposes. Default framework interfaces are provided through inheritance from standard classes.

OCF provides methods and classes for use by the CardService implementation to access the card. The major classes in this category are CardChannel and CardService.

A concept for secure messaging is provided by OpenCard. Although the actual implementation of secure messaging will not be covered here, the OpenCard provisions for secure messaging will be explained in enough detail to allow you to implement secure messaging using your cryptographic code.

Associated with each CardService implementation is a CardServiceFactory that is capable of constructing it. CardServiceFactory must be able to identify the card or cards for which it can construct instances of CardService. When a smart card is inserted into the reader, the OpenCard Framework goes through its list of registered card service factories until it finds one that can handle the card.

Application interfaces

The CardService implementation has the task of mapping the method call to smart card APDU's that are communicated to the card. One method may cause one or many command - response sequences to be carried out with the card.

When a new CardService implementation is defined, any desired functionality may be implemented. Standard OpenCard interfaces may be used, or an application specific interface may be developed. The use of standard interfaces facilitates smart card interoperability, where application specific interfaces can provide more customized functionality.

Using standard CardService interfaces

After OCF has been started, the waitForCard() method can be used to wait for a card to be inserted that implements the desired interface. In the code fragment below, the application instantiates a FileAccessCardService (this service provides access to ISO file system cards) for an inserted card.

...
// Initialize the framework
SmartCard.start ();
 
...
// Assume card has been inserted, 'card' is SmartCard object.
// Instantiate file access card service.
FileAccessCardService fs = (FileAccessCardService)
                            card.getCardService(FileAccessCardService.class);
...

The standard application interfaces can be implemented for any smart card. In order to do this, a class implementing the interface must be written. The declaration statement for this class could appear as in the following code fragment. The accompanying CardServiceFactory (for example com.ibm.opencard.factory.MFCCardServiceFactory), will create an instance of MFCFileAccess when called upon to instantiate a FileAccessCardService object.

public class MFCFileAccess extends MFCCardService implements FileAccessCardService {
... (implementation)
}

Standard application interfaces

• opencard.opt.signature.SignatureCardService provides an interface for digitally signing data and hashes using a public key algorithm and private key stored on a smart card.
• opencard.opt.signature.KeyImportCardService allows new PKA private and public keys to be stored on a smart card.
• opencard.opt.signature.KeyGenerationCardService supports generation of new PKA key pairs.
• opencard.opt.applet.mgmt.AppletAccessCardService allows applets on the card to be listed and to getthe information required to select an applet.
• opencard.opt.iso.fs.FileAccessCardService provides for ISO 7816-4 file access functionality.
• opencard.opt.iso.fs.FileSystemCardService supports file creation, deletion, invalidation, and rehabilitation for file system cards.

Defining your own interface

public class FooBarCardService  extends CardService {
   public FooBar getFooBar() { ... implementation ... }
   ..... (rest of implementation)
}

Interface standardization

Framework interfaces

There are also several methods meant for administrative use by the OpenCard Framework itself. These methods will not be covered here.

CardService methods for implementation use

• allocateCardChannel() makes sure that CardChannel is available for communication with the card. If another thread is already communicating with the card, this function will block until the active thread releases CardChannel. After successful completion of this call, the current thread will have exclusive access to CardChannel.
• getCardChannel() returns a reference to a CardChannel object that can be used for communication with the card.
• releaseCardChannel() - signals that CardService is done using CardChannel. It should be noted that this call does not destroy the CardChannel object, but merely signals to CardServiceScheduler that CardService is finished communicating with the card.

CardService methods for application use

• The getCard() method returns a reference to the smart card object associated with this CardService.
• The setCHVDialog() method allows the application to pass a CHVDialog object that will be used to obtain the password from the user.

CardServiceInterface

Subclassing CardService

This resulted in a somewhat non-intuitive mechanism for instantiating card services. Instantiation is performed by CardServiceFactory in two steps. First, the default constructor runs, and then the initialize(CardServiceScheduler, SmartCard, boolean) method is called.

If a default constructor is provided, it is important that super() be called. Similarly, the initialize() method can be overridden to perform initialization of the implementation, but if this is done, it is required that super.initialize() be called.

Example

These code fragments illustrate the concepts presented in this section.

// declare interface, allowing access to application relevant CardService functions -
public interface FooBarCardService  extends CardServiceInterface {
   public FooBar getFooBar();
}
 
// class implementing the card service interface -
public class BobsFooBarCardService extends CardService implements
            FooBarCardService {
 
      // default constructor - 1st step of two-step construction -
      public void BobsFooBarCardService() {super();}
 
      // 2nd step of two-step construction -
      protected void initialize(CardServiceScheduler    sched,
                               SmartCard                card,
                               booloean         blocking) {
         super.initialize(sched, card, blocking);
         .... (initialize implementation) ....
   }
 
   public FooBar getFooBar() {
         .... perform setup stuff ...
 
         // allocate CardChannel, communicate with card, release channel -
         try {
            allocateCardChannel();
            CardChannel chan = getCardChannel();
            .... do some work with card ... make a FooBar ...
         }
         catch ( ... various exceptions ... ) { ... do appropriate thing ... }
         finally {releaseCardChannel();}
         return foobar;
      }
}

CardChannel

Before use of CardChannel is described, several helper classes and concepts must be covered.

The APDU classes

These classes provide methods for accessing and setting the data to be sent to the card on a byte and byte array basis. In addition, ResponseAPDU contains methods for accessing the status word bytes returned by the card. Both APDU classes are defined so that they can be instantiated once and reused for subsequent calls. This feature can improve performance since it reduces the number of objects created and destroyed. To do this, the APDU is created with the maximum expected buffer size during the initialization phase. Each time the APDU is used, the length is first reset to 0, and then the new data is appended.

... (initialization) ...
CommandAPDU cmd = new CommandAPDU(MAX_SIZE);
...
 
... (before each use) ...
cmd.setLength(0);
cmd.append(NEW_APDU_BYTES);

The CardChannel state

This mechanism is also useful for passing data between related card services. For instance, data about the last selected application or the last security state reached could be stored. Naturally, card services communicating in this manner must agree on a common data representation.

The state is stored using the setState() and read using the getState() methods.

Cardholder verification

Some card terminal devices are equipped with a PIN pad and are capable of accepting CHV input from the user and passing it directly to the card. The OCF card terminal package provides a special interface (opencard.core.terminal.VerifiedAPDUInterface) that allows such a device to be recognized and used in a standard manner.

Since the APDU used for cardholder verification is card specific, the device must be provided with a partial APDU along with information that allows the device to complete the APDU by inserting the CHV, encoded properly, at the correct location. The completed APDU is then sent to the card and the resulting response APDU is returned to the card service implementation.

When the CHV is to be obtained from a GUI running on a workstation, the concept is similar. Again the card service implementation must generate a partial APDU and provide information on how to encode the CHV information and insert it into the partial APDU for transmission to the card.

In either case, the descriptive information for inserting the CHV information into the partial cardholder verification APDU must be placed in the CHVControl class, which is a simple container for such information. Required data is CHV offset within the APDU and the name of the encoding mechanism to be used. Coding mechanism names are described by the CHVEncoder interface. The other fields may be set to null when not needed.

The OpenCard Framework provides a default GUI dialog box for obtaining the cardholder verification when running on a workstation with full AWT (Advanced Windowing Toolkit) capability. It is recognized, however, that some applications will require a password entry dialog that is more closely integrated (from the look-and-feel point of view) into the application.

By implementing the CHVDialog interface and passing the implementation class to the card service using the setCHVDialog() method, the application can override OpenCardDefaultCHVDialog.

The CHVDialog contains only one method - getCHV(int number). This method returns a string representing the CHV indicated by the CHV number. Although this interface will often be implemented by some type of GUI dialog or window class, CHVDialog itself has no dependencies on the AWT package. This means that the class implementing CHVDialog is free to obtain the CHV string from any source - from a command line interface, from a constant string in the source code (Yikes!!), or even from a PIN pad if OpenCard happens to be running on an actual high-function terminal platform.

Communicating with the card

The sendCommandAPDU() method provides the most straightforward possibility for a card service to communicate with the card. The command APDU provided as a parameter is sent to the card, and the card response is returned in a ResponseAPDU.

The sendVerifiedAPDU() method is used when cardholder verification information is to be sent to the card. This method requires a number of parameters:

• a partial command APDU,
• CHVControl parameters,
• a CHVDialog and, last but not least,
• a time-out value.

When executing the sendVerifiedAPDU() method, the CHVControl class will access the card terminal to determine its capabilities. If the terminal device is capable of performing CHV, the CHVControl information and the partial APDU will be sent to the terminal. Otherwise, if a CHVDialog object was set, it will be used. Finally, if all else fails, OpenCardDefaultCHVDialog will be used. The card service implementation is not involved in this decision.

Example

The previous example is enhanced with the main concepts from this section.

// class implementing the card service interface -
public class BobsFooBarCardService extends CardService implements FooBarCardService {
 
   private CommandAPDU cmd = new CommandAPDU(MAX_SIZE);
   private ResponseAPDU rsp;
 
   ... do initialization ....
 
   public FooBar getFooBar() {
      // allocate CardChannel, communicate with card, release channel -
      try {
         allocateCardChannel();
         CardChannel chan = getCardChannel();
 
         // carry out cardholder verification
         cmd.setLength(0);
         cmd.append(CHV_APDU_BYTES);
         CHVControl chvctrl = new CHVControl(   "Enter your password", 1,
                  CHVEncoder.STRING_ENCODING, 0,
                  null);
         CHVDialog chvdlg = getCHVDialog();
         rsp = chan.sendVerifiedAPDU(cmd, chvctrl, chvdlg, -1);
 
         .... check sw1 & sw2, do some work with card ... make a FooBar ...
      }
      catch ( ... various exceptions ... ) { ... do appropriate thing ... }
      finally {releaseCardChannel();}
   }
}

Implementing secure messaging

Credentials

Credential interfaces will be defined (by the card service implementer or perhaps by a third-party provider) to provide appropriate functionality for the card service at hand. Depending on availability, credentials can implement the cryptographic functionality directly or can access a security module.

The CredentialStore class can be used as a container for related credentials. This abstract class must be extended to support a specific card operating system, since the method through which keys are identified and selected vary from card to card. Customization of the CredentialStore class requires work in two areas:

1. The boolean supports(CardID) method of the CredentialStore class must be implemented. This is required for identification of the store since it is card operating system dependent.
2. An identifier object for the keys contained in the credential store must be defined. This identifier is used with the storeCredential() and fetchCredential() methods to specify the desired credential. Typically, this identifier class will be defined by the card service implementer and will abstract the manner in which keys are specified on the card. The only restriction on the identifier definition is that hashCode() and equals() methods be defined appropriately for use in a hash table.

Card interoperability

To help with this, another concept - CredentialBag - was introduced. CredentialBag is simply a container class for CredentialStore objects. The addCredentialStore() and getCredentialStore() methods allow objects to be stored and retrieved.

The CredentialStore objects are retrieved from CredentialBag by CardID. This allows the card service implementation to query the key bag for an appropriate key store object. To achieve card interoperability, the application fills CredentialBag with key stores for all supported cards. After a card has been inserted and the application has obtained a card service that implements secure messaging, the application will pass CredentialBag to the card service. The card service implementation will use CredentialBag's retrieval functions to obtain an appropriate CredentialStore for the inserted card.

Interfaces for CardService

On a smart card, the security domain is specified by some characteristic. The characteristic specifying the security domain will differ depending on card type. For example, it will be different for JavaCard-based smart cards than for ISO file system based smart cards.

This concept of security domain is abstracted in the OpenCard Framework as the SecurityDomain interface. To allow support for varying card types, it is defined as a tag interface only.

The SecureService interface allows applications to pass credential bags to the card service. All card services that provide secure messaging functionality must implement the SecureService interface. This interface provides one new function - provideCredential() - that accepts a CredentialBag and a SecurityDomain object as parameters. The security domain object specifies the object characteristic for which the credential bag is valid.

File system based cards typically use a partial subdirectory in which an object resides to specify the security domain. For this reason, the opencard.opt.iso.fs.CardFilePath class implements the SecurityDomain interface. For such cards, the CardFilePath object would represent the object characteristic for which a credential bag is valid. When performing secure messaging for file access, the card service implementation would select the credential bag to use based on the active card file path.

CardServiceFactory

Registry mechanism overview

When the application requests a card service, CardServiceRegistry goes through its list of registered instances of CardServiceFactory, querying each in turn whether it supports the inserted card. When aCardServiceFactory supporting the card is found, the registry attempts to use that factory to instantiate the requested card service. If successful, the card service is returned to the caller; otherwise the search continues.

Implementing instances of CardServiceFactory

Card service factories implemented with OCF 1.1.1 or later must overwrite two abstract methods that are used by the OpenCard Framework to instantiate services - getCardType() and getClasses(). The constructor of the CardServiceFactory can be empty.

The getCardType() method accepts a CardID object which basically represents the ATR obtained from the card and returns a CardType.

The card type object returned should either be the reserved instance CardType.UNSUPPORTED or another instance of card type that allows the factory's getClasses method to decide which card services can be instantiated. If the card service factory supports a whole family of cards from one card manufacturer the card type could for example contain the information about the card operating system version of the inserted card. If the CardID is not sufficient to determine the card type the CardServiceScheduler can be used to allocate a CardChannel to communicate with the card.

The getClasses() accepts the CardType object determined in the previous step as a parameter and returns an enumeration of card services supported by the factory for the specified card. This method is used by the CardServiceFactory superclass method called by CardServiceRegistry when instantiating a CardService class for CardServiceRegistry.

Example

The following example code shows the implementation of the factory that supports theFooBarCardService:

public class FooBarCardServiceFactory extends CardServiceFactory {
public FooBarFactory () {}
 
// implement abstract method -
protected CardType getCardType(CardID cid,
                               CardServiceScheduler scheduler)
  throws CardTerminalException
{
 
   byte[] historicalBytes = cid.getHistoricals();
   // analyze historicals
   if ((historicalBytes[0] != ...) || (historicalBytes[1] != ...))
     return CardType.UNSUPPORTED;
 
   // find out information about card
   ...
   int cardOSVersion = ...;
 
   return new CardType(cardOSVersion);
}
 
// defines supported services
static {
   foo_classes = new Vector();
   foo_classes.addElement(FooBarCardSvc.class);
}
 
 
protected Enumeration getClasses(CardType type)
{
   switch (type.getType()) {
   case ...:
     return foo_classes.elements();
   case...:
     ...
}

PrimaryCardServiceFactory

Using the SlotChannel object provided by the card service registry, PrimaryCardServiceFactory can communicate with the card in order to carry out any required initialization.

One possible use for this feature would be communication speed selection.

Support for JavaCards and other Multi Application Cards

State Objects

AppletState

CardState

Selection

AppletSelector

ISOAppletSelector

Proxy Base Classes

BasicAppletCardService

AppletProxy

Support for SCQL Database Smart Cards

What we call here "Database smart cards" are smart cards (or applets) that integrates an engine of SCQL (Smart Card Query Language) relational data base. The database concept is based on SQL (ISO 9075).

Such cards allow to store personal data in database structures in a secure way. They include security mechanisms such as PIN code authentication, login/password authentication or internal/external authentication via a DES algorithm enabling the user to secure his/her personal data optimally.

As specified by the [ISO 7816-7] international standard, the dialog with the card is based on exchanges of APDU commands which are structured as byte arrays. The set of commands managed by the card (at database level) is a subset of the SQL-92 command set.

As of today, this subset does not authorize neither join nor multiple predicates in 'where' clauses. In spite of the numerous physical constraints due to the memory size of the database engine and databases themselves, the provided functionalities are nearly similar to those offered by a classical database. Indeed, this type of card can manage users, users profiles, privileges about the different objects of the base(s), transactions (commit and rollback notions) and tables/views/dictionaries.

Please refer to the ISO norm [ISO 7816-7] for more details on database smart cards.

Package features

Layers of abstractions

1. an interface layer, DatabaseCardService, to allow interoperability among competitive implementations for smart cards or applets that all respect compliance with [ISO 7816-7], and
2. a general purpose concrete implementation, BasicDatabase, that can be used out-of-the-box by programmers of applications that wish to use a database card, and that can also be considered as a base class for the implementation of specific CardServices. In both cases, the programming effort will be reduced by the usage of the framework, and also if everybody uses the same basic implementation and propose enhancements for it, the quality of this component will increase.

Miscellaneous

• a set of specialized exceptions, all inheriting from the SCQLException class (the base class for all exceptions related to the use of a SCQL Database Smart Card),
• DataObject, a utility class used by BasicDatabase for parsing parameters according to the standard (e.g., privileges, user profiles, etc.), and
• SecurityAttribute, the base class for security attributes DO (i.e., Data Objects) as specified by the standard. It is currently mostly a wrapper for a byte array, as the ISO7816-7 standard does not specify what information should be provided in a security attribute DO, and in what form. In the case where the chosen semantics is to use the ASCII codes of a "String" password, a constructor is provided in addition to the default one (using a byte array).

Interface Details

• Constants as specified by the 7816-7 norm (i.e., class byte, coding for SCQL, transactions, or user operations, coding for comparison operators, coding for privileges, and error codes),
• Constants as specified by the 7816-6 norm (i.e., TLV tag values for card holder certificate and name) that are used for encoding a PRESENT_USER operation with security attributes, and
• Methods to handle database smart cards, as specified by the 7816-7 norm: createTable, createView, createDictionary, dropTable, dropView, grant, revoke, declareCursor, open, next, fetch, fetchNext, insert, update, delete, begin, commit, rollback, presentUser, createUser, deleteUser. The method names are the ones that are specified by the norm, except that they also follow standard Java naming guidelines. Please refer to the [ISO 7816-7] ISO norm for more details about these commands semantics.

Example of use

Program

import opencard.opt.database.*;
 
public class TestDatabase {
 
    public static void main (String [] args) {
        int i;
        String[] result;
 
        try {
            // Initialize the framework
            SmartCard.start ();
            System.out.println ("Waiting for a 7816-7 SCQL smart card...");
            SmartCard sm
                = SmartCard.waitForCard (new CardRequest(BasicDatabase.class));
 
            // Get a card service and perform SCQL commands
            BasicDatabase cs = (BasicDatabase)
                sm.getCardService(BasicDatabase.class, true);
 
            // Try to send a PRESENT USER to the card
            cs.presentUser("GUEST", new SecurityAttribute("guest"));
 
            // Try to send SCQL commands to the card to read the DIARY table
            cs.declareCursor("DIARY","*","");
            cs.open();
            try {
                while (true) {
                    result = cs.fetch();
                    for (i=0 ; i < result.length ; i++) {
                        System.out.println (" - DIARY("+i+") = "+result[i]);
                    }
                   ; System.out.println ("---");
                    cs.next();
                }
            } catch (EndOfTableReachedException scqle) {
                System.out.println ("");
                System.out.println ("Warning: End of table reached.");
            }
 
            // Try to create a new table 'FOOTABLE'
            try {
                cs.createTable("FOOTABLE", "FOO,BAR,GEE", new SecurityAttribute(""));
            } catch (ObjectAlreadyExistsException scqle) {
                System.out.println ("Warning: Table already exists...");
            }
            cs.insert("FOOTABLE", "foo1,bar1,gee1");
 
            // Shutdown the framework
            SmartCard.shutdown ();
        }
        catch (SCQLException scqle) {
            System.out.println ("SCQL Exception: ");
            scqle.printStackTrace();
            if (scqle.getMessage () != null) {
                System.out.println ("details:");
                System.out.println (scqle.getMessage () );
            }
        }
        catch (CardTerminalException cte) {
            System.out.println ("CardTerminalException: ");
            System.out.println (cte.getMessage () );
        }
    }
}

Description

import opencard.opt.database.*;

            SmartCard.start ();

            SmartCard sm
                = SmartCard.waitForCard (new CardRequest(BasicDatabase.class));

            BasicDatabase cs = (BasicDatabase)
                sm.getCardService(BasicDatabase.class, true);

            cs.presentUser("GUEST", new SecurityAttribute("guest"));

            cs.declareCursor("DIARY","*","");

            try {
                while (true) {
                    result = cs.fetch();
                    for (i=0 ; i < result.length ; i++) {
                        System.out.println (" - DIARY("+i+") = "+result[i]);
                    }
                    System.out.println ("---");
                    cs.next();
                }

            } catch (EndOfTableReachedException scqle) {

            try {
                cs.createTable("FOOTABLE", "FOO,BAR,GEE", new SecurityAttribute(""));

            cs.insert("FOOTABLE", "foo1,bar1,gee1");

            SmartCard.shutdown ();

In addition, an application can request a CardService implementing the opencard.opt.database.DatabaseCardService, thus ensuring interoperability with all database smart cards or applets that are compliant with the ISO 7816-7 standard.

Acknowledgements

Glossary

APDU

An acronym for application protocol data unit. Interactions with smart cards occur by exchanging pairs of APDUs and are initiated by the external application.

API

An acronym for application programming interface.

applet

A Java-based "mini-application" which runs in a browser on the client side.

application

As defined by ISO 7816, the card-resident component (consisting of data and functions) of software interacting with the card-external component.

application developer

A software programmer specializing in the development of applications. One of the chief beneficiaries of the OpenCard Framework.

AppletAccessCardService

A special OCF card service for dealing with the various different applets residing on a smart card.

asymmetric algorithm

A type of cryptographic operation using one key for encrypting data and another key for decrypting the resultant encrypted data. Together, the two keys are referred to as a key pair (also known as public/private keys).

ATR

An acronym for answer-to-reset. The ATR is the initial information emitted by a smart card upon being reset and powered up.

authentication

The process of verifying the identity of the participants in an exchange of electronic data. When the card-external application authenticates itself to the card-resident application, this is called External Authentication. Conversely, when the card-resident application authenticates itself to the card-external application, this is referred to as Internal Authentication. Cardholder Verification (CHV) is when the cardholder authenticates him or herself to the card.

authorization

The security process to decide whether a service can be given or not.

Card Acceptance Device (CAD)

Synonym for card reader or card terminal.

card authentication

The security process for verifying the genuineness of an inserted smart card.

cardholder

The legitimate holder of a smart card.

Cardholder Verification (CHV)

The process of checking whether the person presenting a card to the card system is indeed the legitimate holder. Usually, a secret number or password known only to the cardholder is used.

CardID

An OCF class for the identification of the card type based on the card's ATR.

card initialization

The process of writing initialization data to the smart card's EEPROM. The EEPROM image generated during layout definition is then transferred to the smart card.

card issuer

An institution which issues cards to cardholders.

cardlet

A word formed from two parts: (smart) card and applet.

CardManagementService

A special OCF card service defining a high-level API for installing, removing, blocking, and unblocking the various different applications residing on a card in an issuer-independent fashion.

Card Operating System (COS)

The microcode contained in a smart card's ROM, used for communicating with the smart card, managing security, and managing data in the smart card.

card personalization

The process of writing cardholder-specific data (e.g. serial number, cardholder's name) to the smart card. After card initialization, the smart card's EEPROM reflects the basic data structure as defined in the layout definition and may contain some initial data that is constant across all cards. During personalization, the information peculiar to an individual cardholder is written to the card prior to issuing it.

card reader

An I/O device attached to the computing platform into which the smart card is inserted. Roughly synonymous withCard Acceptance Device (CAD), Interface Device (IFD), or card terminal.

card recognition

The process of checking whether an inserted smart card has the correct physical and electrical characteristics.

CardService

Any one of a variety of OCF components which make smart card functions available to the application programmer.

CardServiceFactory

Associated with each instance of CardService is an instance of CardServiceFactory capable of constructing it.

CardService layer

A layer of OCF which provides the basic infrastructure for accessing card services.

CardServiceRegistry

A system-wide OCF class for keeping track of the various different instances of CardServiceFactory which are available. Application developers can configure CardServiceRegistry using the OpenCard.services property.

CardServiceScheduler

Responsible for managing CardChannel objects.

card system

A body establishing a set of rules governing the issuance and usage of smart cards carrying its mark.

CardTerminal class

A software construct. Instances of the CardTerminal class represent actual physical card terminal devices.

card terminal

(1) A frequently-used synonym for card reader, but in fact more sophisticated. A physical device which performs some interactive function (e.g. reading, writing) with an inserted smart card. The simplest card readers merely provide basic card input-output (I/O) functionality via a single slot to insert the card. Card terminals offer multiple slots or include a PIN pad and a display.

(2) When appearing in monospace (CardTerminal), the OCF abstraction (device driver code) for specific card terminals.

CardTerminal layer

A layer of OCF containing abstractions for card terminals.

CardTerminalFactory

An OCF class of services which are capable of creating individual instances of CardTerminal.

CardTerminalRegistry

A system-wide OCF class of services for keeping track of all available instances of CardTerminal. Application developers can configure CardTerminalRegistry using the OpenCard.terminals property.

CHVDialog

An interface registered via the CardService object's setCHVDialog() method and implemented by a default GUI component to enter the cardholder verification data.

CommandAPDU

An APDU sent to a smart card via the card reader's device driver.

component

The smallest selectable set of elements includable in a package.

communication layer

One of the three layers of CardTerminal implementation. This layer provides methods for handling the transfer of the data between the host and the card reader.

confidentiality

The prevention of the unauthorized disclosure of information.

constructor

A special function used in object-oriented programming to initialize the state of a program object. Generally speaking, a constructor must be called whenever a new object is created.

credential

(1) Typically, cryptographic keys or certificates made available in (card-external) applications which fit the access conditions of the files which the given application is supposed to interact with.

(2) When appearing in monospace (Credential), OCF parlance for an interface typically representing a cryptographic key and the associated algorithm for performing cryptographic functions. OCF's concrete implementations of Credential include RSASignCredential and DSASignCredential.

CredentialBag

A container class for CredentialStore objects. It offers retrieval functions which the card service implementation can use to obtain an appropriate CredentialStore for inserted smart cards.

Credential Store

In OCF, an abstract class containing credentials for a smart card.

cryptographic algorithm

An algorithm for transforming confidential data so as to encrypt or decrypt its information content. Cryptographic algorithms can be either symmetric (the same key is used to both encrypt and decrypt the data) or asymmetric (different keys are employed for encrypting and decrypting).

cryptographic functions

Any of various tools (typically based on cryptographic algorithms) for encrypting and decrypting information, thus making it unintelligible to any but authorized persons (who must undergo authentication). When employed in smart cards for secure messaging, cryptographic functions can be installation and/or application specific.

digital signature

An asymmetric cryptographic operation on data proving the data's origin and integrity to the recipient, and thus protecting against forgery.

EEPROM

An acronym for electrically erasable programmable read-only memory. A non-volatile memory technology in which data can be electrically erased and rewritten.

external application

The program code running on computing platform (personal computers, network computers, automatic-teller machines, etc.) interacting with smart cards.

FileAccessCardService

A particular card service incorporated by OCF for dealing with file-oriented smart cards as per ISO 7816-4.

forgery

The illicit copying and alteration of intercepted information. A form of tampering.

function layer

One of the three layers of CardTerminal implementation. This layer encapsulates the detailed knowledge about your card reader.

hashing

The one-way transformation of data having an arbitrary length into a fixed-length digest.

initialization

A step in the manufacture of smart cards in which the basic data common to a batch of cards is loaded onto their chips.

Interface Device (IFD)

A synonym for card reader.

interface layer

One of the three layers of CardTerminal implementation. This layer is derived from the abstract CardTerminal class and provides methods for interfacing with the upper part of the framework.

key generation

The task of creating a public/private key pair to be used with public key cryptography. In OCF, KeyGenerationCardService's generateKeyPair method can be used to obtain this functionality from an inserted smart card.

KeyGenerationCardService

An extension of OCF's SignatureCardService interface offering methods for generating a key pair for a card-resident public key algorithm and for reading the public key part of the pair for use outside of the card.

key importation

A task performed in OCF by the KeyImportCardService's importPrivateKey and importPublicKey methods (non-validating) or its importAndValidatePrivateKey and importAndValidatePublicKey methods (validating). It allows the public/private keys to be stored in a smart card.

KeyImportCardService

An extension of OCF's SignatureCardService interface offering methods for the importation and subsequent in-card verification of keys for asymmetric key algorithms.

layout definition

The process of generating an EEPROM image from a high-level definition of the EEPROM layout. Most smart card applications maintain information typically kept in EEPROM-based files on the card's file system. Layout definition is about identifying the information items that should go in the card and defining an appropriate file structure in the card. The latter includes specifying the type of file (transparent, record-oriented, cyclic), file names and/or identifiers, access conditions, initial data, etc.

Master File (MF)

A specially dedicated file in a smart card's file system representing the file system's root.

non-volatile

Said of memory storage technologies which are not dependent upon a power supply for storing data.

OpenCard Consortium

A consortium including 3GI, Bull, Dallas Semiconductors, First Access, Gemplus, intellect, International Business Machines Corp., Network Computer Inc., Newcom Technologies, Schlumberger, SCM Microsystems, Siemens, Sun Microsystems, UbiQ, and Visa International.

OpenCard Framework (OCF)

The name of an object-oriented software framework for smart card access. It is implemented in the Java programming language and is located between a smart card-aware application or applet written in Java and the card reader. The terms OpenCard Framework and OCF are protected trademarks.

padding

Appending extra bits to either side of a data string up to a pre-defined length.

Personal Identification Number (PIN)

The secret code used to authenticate a cardholder.

polling

The periodic querying of device status in order to detect status changes. In the case of OpenCard, polling can be used to detect smart card insertion and removal.

polling mechanism

A program construct; typically, a loop that runs periodically and that calls the appropriate status query methods for individual devices.

PowerManagementInterface

An OCF interface comprising the powerUpCard() and powerDownCard() methods, both of which take the slot number as a parameter and allow the supply of power to the smart card in the designated slot to be controlled. This optional CardTerminal function is useful in the case of long-lasting applications that only sporadically interact with smart cards in environments where low power consumption matters.

private key

The privately-held component of an integrated asymmetric key pair.

protocol

The procedures used by two or more computer systems for communicating with each other.

public key

The public component of an integrated asymmetric key pair.

ResponseAPDU

An APDU sent back by a smart card in response to a CommandAPDU it has received.

RSA

An acronym for an asymmetric cryptographic algorithm named after its inventors, Ron Rivest, Adi Shamir, and Len Adleman. It is used in public-key cryptography and is based on the fact that it is easy to multiply two large prime numbers together, but hard to factor them out of their product. RSA is a protected trademark of RSA Security Data, Inc.

SCQL

An acronym for Structured Card Query Language.

secure messaging

The use of cryptographic functions to protect and authenticate data passed to and from a smart card on a per-message basis. The card service implementation, while it generally does not implement its own cryptographic functions, must be aware of secure messaging if supported by the card.

Security Access Module (SAM)

A unit in which cryptographic algorithms and keys may be stored.

SignatureCardService

A card service incorporated by OCF for generation and verification of digital signatures. SignatureCardService's signData and verifySignedData methods perform this operation.

signature generation

The act of creating a special data block known as a digital signature which allows changes in the signed data to be detected and data to be authenticated. In OCF, this is performed by SignatureCardService's signData method, which computes a hash value on the message and then encrypts this hash value using the private key of a key pair. The (time-consuming) computation of the hash value can also be performed outside of the OpenCard Framework.

signature verification

A task performed in OCF by SignatureCardService's verifySignedData method, which computes the decryption on the given signature using the public key, computes a hash value on the plain message, and then compares the hash value with the decrypted signature. The (time-consuming) computation of the hash value can also be performed outside of the OpenCard Framework.

slot

(1) A physical opening in a card terminal into / from which a smart card can be inserted / removed.

(2) When appearing in monospace font (Slot), OCF's representation of such a physical opening and an instance of the Slot class.

smart card

Integrated circuit cards corresponding to the ISO / IEC standards 7816, JavaCards as defined in Sun's JavaCard 2.0 specifications, or any other smart tokens (including smart accessories). Important functions include secure data storage and (optionally) cryptographic functionality.

SmartCard

An OCF class providing an entry point to OCF.

SmartCard object

An object with a pivotal role in interacting with a physical smart card. Can be obtained e.g. by calling the waitForCard method on the SmartCard class, which returns a SmartCard object.

TerminalCommand

An OCF interface comprising the sendTerminalCommand() method, which takes a byte array and sends it to the card terminal. Assuming an application knows the set of commands that a given card reader supports, it can use this optional CardTerminal function to control the card reader.

UserInteraction

An optional CardTerminal function. This OCF interface comprises the display() method to present a message to the cardholder, the clearDisplay() method to erase the message from the display, the keyboardInput() method to collect a string entered by the cardholder, and the promptUser() convenience method, which combines displaying the message to and collecting input from the cardholder into a single call.

Bibliography

Scott B. Guthery & Timothy M. Jurgensen, SmartCard Developer's Kit, ISBN: 1-57870-027-2, Indianapolis, Indiana: Macmillan Technical Publishing, 1998.

Henry Dreifus & J. Thomas Monk, smartcards -- A guide to building and managing smart card applications, ISBN: 0-471-15748-1, New York: John Wiley & Sons, 1998.

Jack M. Kaplan, SmartCards -- The Global Information Passport, ISBN: 1-850-32212-0, Boston, Massachusetts: Thomson Computer Press, 1996.

W. Rankl / W. Effing, Handbuch der Chipkarten, ISBN: 3-446-18893-2, Carl Hanser Verlag Muenchen Wien, 1996.

U. Hansmann, M. S. Nicklous, T. Schäck, F. Seliger Smart Card Application Development Using Java, ISBN: 3-540-65829-7, Springer Verlag Berlin, 1999.

Mike Hendry, Smart Card Security and Applications, ISBN: 0-89006-953-0, Norwood, Massachusetts: ARTECH House, Inc., 1997.

W. Rankl & W. Effing, Smart Card Handbook, ISBN: 0-47196-720-3, New York: John Wiley & Sons, 1997.

¹

The term smart card refers to integrated circuit cards as specified in the ISO / IEC standards 7816, JavaCards as specified in Sun's JavaCard 2.0 specifications, or any other smart tokens (including smart accessories).

²

The card-resident component is referred to as an application in ISO 7816.

³

Personal Identification Number

⁴

http://java.sun.com/products/jdk/

⁵

http://www.opencard.org/

⁶

the card used for the OCF demo called "Internet Broker"

⁷

The ATR is the initial information emitted by a smart card upon being reset.

⁸

relational database mechanisms or object-based persistence mechanisms are alternate abstractions for the storage of information and are considered for smart cards, too (see also the ISO standard ISO 7816-7 Interindustry commands for Structured Card Query Language (SCQL).

⁹

At present, we still lack a standard set of properties to characterize card terminals beyond the pure terminal configuration data. This is needed if an application wants to find out what optional functions a card reader supports.

¹⁰

Performing CHV without exposing the entered PIN code or password outside of the card reader device's security perimeter enhances security.

¹¹

ATM's typically take in the cards for the period of interaction to prevent early removal of the card by the user.

¹²

DIR files are EFs containing a list of applications that a card contains along with optional information (e.g. the path to the DF application).

¹³

A hexadecimal digit is a character from the set 0-9, a-f, A-F.

¹⁴

In the case of JavaCards, the model will be somewhat different, but the essence of what is said here remains valid.

¹⁵

This may be different in the case of emerging multi-function smart cards whose operating system allows for the post-issuance deployment of applications.