The SATSA-JCRMI Optional Package

Chapter 4 The SATSA-JCRMI Optional Package

The SATSA-JCRMI Optional Package enables you to communicate with a smart card using the Java Card Remote Method Invocation (JCRMI) protocol.

JCRMI is a distributed computing protocol, which means it allows applications that are not located on the card to use objects that exist on the card. Applications use a remote interface to work with an object on the card. When the application calls a method on the remote interface, the method call is transferred to the card using the JCRMI protocol. The method is run on the card and the results are returned to the application.

JCRMI is a subset of the J2SE platform’s Remote Method Invocation (RMI) that is tailored for the constraints of a Java Card environment. JCRMI places restrictions on the allowed parameter types and return types for remote objects. See the SATSA specification for more details.

SATSA-JCRMI comprises classes and interfaces in several different packages:

The Remote interface and RemoteException class from the J2SE platform RMI implementation are both included in the java.rmi package.

JavaCardRMIConnection, in the javax.microedition.jcrmi package, serves as a bridge between the Generic Connection Framework (GCF) and SATSA-JCRMI.

Exception classes from the Java Card API are also included because these exceptions might be thrown when calling methods on a card object. These exceptions are defined in javacard.framework, javacard.framework.service, and javacard.security.

This chapter describes basic use of SATSA-JCRMI and includes example code that illustrates the concepts. A complete example is included in Appendix B.

A Brief Introduction to SATSA-JCRMI

The fundamental concept of SATSA-JCRMI is that your application has the ability to call methods on an object that lives on the smart card. The card object is a remote object, and your application, the client, interacts with the remote object using a remote interface. The actual communication is accomplished using a stub object that you must generate at development time. The stub implements the remote interface and contains the actual details of communicating with the remote object.

At development time, your responsibilities are as follows:

Create a remote interface that includes the methods you wish to call on the remote object.

Create a stub class that implements the remote interface. You can do this using the JCRMI stub compiler.

Create client code in your application that opens a connection and calls methods on the remote object.

Creating a Remote Interface

Creating a remote interface is relatively straightforward. The remote interface contains all the methods you wish to call on the remote object. It must extend java.rmi.Remote, and every method must throw RemoteException. RemoteException is thrown if a communication failure occurs between your application and the remote object.

The following example shows a remote interface for a Purse class that includes definitions for five methods.

public interface Purse extends Remote { 
  public short getBalance() throws RemoteException; 
  public void debit(short m) throws RemoteException, UserException; 
  public void credit(short m) throws RemoteException, UserException; 
 
  public void setAccountNumber(byte[] number) 
      throws RemoteException, UserException; 
  public byte[] getAccountNumber() throws RemoteException; 
}

Creating a Stub Class

A stub class implements the remote interface and provides the code that actually calls methods on the remote object. The stub class lives in the same package as the remote interface. Its name is the remote interface name with _Stub appended. For example, if the remote interface in the preceding example is Purse, the stub class name is Purse_Stub.

The SATSA reference implementation includes a stub compiler utility, jcrmic, that generates a stub class for a given remote interface. All you really need to do is tell jcrmic where to find your remote interface. The command line syntax is as follows:

jcrmic <options> <interface names>

The jcrmic utility recognizes these options:

-classpath <path> - Specifies the location of the input class files.

-d <directory> - Specifies where the compiler will place the generated files.

-nocompile - Specifies that generated source files will not be compiled.

-keep - Specifies that generated source files will not be deleted after compilation.

By default, jcrmic calls the compiler specified by the JAVAC_PATH environment variable. The generated source files are deleted after they are compiled and the stub classes are stored in the directory specified by the -d option.

For example, you could create a stub class for the Purse remote interface like this:

jcrmic -d . Purse

Connecting to a Remote Object

SATSA-JCRMI is implemented through the Generic Connection Framework (GCF). The basic tenet of the GCF is that you supply a connection string and receive an object that allows you to communicate. In the case of SATSA-JCRMI, you supply a connection string and receive an interface that allows you to call methods on a remote object, an object that resides on a smart card.

The connection string specifies a slot number and a card application identifier (AID). The following example connects to an application with identifier a0.0.0.0.62.3.1.c.8.1 on a card in slot 0.

String url = "jcrmi:0;AID=a0.0.0.0.62.3.1.c.8.1"; 
JavaCardRMIConnection connection = null; 
connection = (JavaCardRMIConnection)Connector.open(url);

Various kinds of exceptions might be thrown from Connector’s open() method if any kind of communication failure occurs. Be sure your application catches and handles exceptions properly. A complete example is included in Appendix B.

To retrieve a reference to the remote object, use the getInitialReference() method in JavaCardRMIConnection. This method returns an instance of java.rmi.Remote that you cast to the appropriate remote interface type, as shown here:

Purse purse = (Purse)connection.getInitialReference();

Calling Methods on a Remote Object

Once you establish a reference to a remote object, you can treat it almost like a local object. When you call methods on your instance of the remote interface, the same methods are called on the remote object, and return values are transferred from the remote object to your application.

The only tricky part is that if a communication failure occurs, you must be prepared to handle RemoteException properly. Remember, every method in the remote interface can throw RemoteException, because every remote method call has the possibility of communication failure.

Closing a Connection to a Remote Object

When you are finished calling methods on a JCRMI remote object, be sure to close the corresponding JavaCardRMIConnection, as shown in the following example.

connection.close();

SATSA Developer's Guide
SATSA Reference Implementation 1.0