The SATSA-APDU Optional Package

The SATSA-APDU Optional Package enables MIDP applications to communicate with a smart card using a protocol based on Application Protocol Data Units (APDUs). This protocol is defined by ISO 7816-4 and described in the Java Card Development Kit documentation. See Chapter 1 for a pointer to the Java Card Development Kit.

An APDU is a short message represented by bytes. SATSA-APDU enables your application to exchange APDU messages with a card application. The SATSA-JCRMI Optional Package, which is described in the next chapter, allows applications to interact with card applications at a higher level. SATSA-JCRMI allows your application to use objects on a smart card directly. Which API you use depends on the requirements of your application.

In SATSA-APDU, messages are either commands or responses. Your application can use SATSA-APDU to send commands to a card application and receive responses. An application could send a command message to query an account balance and receive the answer in the response message.

SATSA-APDU is a single interface, javax.microedition.apdu.APDUConnection, which contains seven methods.

This chapter describes basic use of SATSA-APDU and includes small pieces of example code that illustrates the concepts. Appendix A includes complete example MIDlets that you can compile and run.

Opening an APDU Connection

SATSA-APDU is implemented as an extension of the Generic Connection Framework (GCF). The GCF provides a uniform API for many different types of data connections. In typical use of the GCF, your application requests a connection from a factory class, javax.microedition.io.Connector. If the connection is established, Connector hands your application an object that is capable of exchanging data on the connection. To make an HTTP connection to a server, for example, your application would call Connector.open("http://myserver.com/"). The GCF returns a connection object that makes it possible for your application to send an HTTP request and receive the response.

In SATSA-APDU, your application passes a locator string representing a card application to Connector’s open() method, which returns an APDUConnection that can be used to communicate with the card application.

The locator string begins with apdu and specifies the slot number and the card application identifier. In following example, the application attempts to open a connection with a card application with identifier a0.00.00.00.62.03.01.0c.02.01 running on a smart card in slot 0.

String purseURL = "apdu:0;target=a0.00.00.00.62.03.01.0c.02.01"; 
APDUConnection purseConnection; 
purseConnection = (APDUConnection)Connector.open(purseURL);

Connector’s open() method throws a ConnectionNotFoundException if there is no such slot, no card in the given slot or if the specified card application is not present. Other types of exceptions are thrown if other types of failures occur. Check the documentation for APDUConnection for full details.

You can discover a device’s available card slots at runtime by retrieving the value of the microedition.smartcardslots system property. Use the getProperty() method in the java.lang.System class.

The property string contains a comma-separated list of slot numbers. Each slot number is accompanied by a character that indicates if the slot is cold-swappable (C) or hot-swappable (H). See the package description for javax.microedition.io in the Security and Trust Services APIs Specification for more details.

Exchanging APDU Messages

Use the exchangeAPDU() method to send a command to a card application and receive a response. Pass a byte array containing a command APDU to exchangeAPDU(). The command is sent to the card. When the card sends its response APDU, this method returns the response as another byte array. A variety of exceptions might be thrown if communications failures or other disasters occur.

In the following example, the APDU commands to be sent to the card are contained in a separate class file called APDUList. The array firstSessionApdus[] are specified in that file and called in the following example.

byte[] apdu = { 
  (byte)0x00, (byte)0x20, (byte)0x00, (byte)0x82, (byte)0x04, 
  (byte)0x01, (byte)0x02, (byte)0x03, (byte)0x04, (byte)0x00 
}; 
byte[] response = purseConnection.exchangeAPDU(apdu);

The exchangeAPDU() method blocks until a response is received from the card application.

Closing an APDU Connection

To close an APDUConnection, simply call its close() method as shown in the following example.

purseConnection.close();

If you close a connection that is being used by other threads to exchange APDUs, the connection is closed immediately and the exchangeAPDU() methods in other threads throw InterruptedException.

Supporting the (U)SIM Application Toolkit

If your application is running in a SATSA implementation that supports the (U)SIM Application Toolkit (U)SAT, you can communicate with SAT applications by using APDUConnection.

There are various constraints on this type of usage, which are definitively detailed in the Security and Trust Services API Specification.

Opening a connection using (U)SAT is straightforward. The following example attempts a (U)SAT connection on slot 0.

APDUConnection sat; 
sat = (APDUConnection)Connector.open("apdu:0;target=SAT");

Once the connection is established, the application can send ENVELOPE APDU commands to the smart card using the exchangeAPDU() method. An envelope contains an array of APDU bytes in hexidecimal format corresponding to an APDU status word.

byte[] envelope = { 
  (byte)0xA0, (byte)0xC2, (byte)0x00, (byte)0x00, (byte)0x2f, 
  (byte)0xD1, (byte)0x2d, (byte)0x82, (byte)0x02, (byte)0x83, 
  (byte)0x81, (byte)0x06, (byte)0x05, (byte)0x80, (byte)0x11, 
  (byte)0x22, (byte)0x33, (byte)0x44, (byte)0x8B, (byte)0x20, 
  (byte)0x10, (byte)0x02, (byte)0x81, (byte)0x55, (byte)0x7F, 
  (byte)0xF6, (byte)0x00, (byte)0x11, (byte)0x29, (byte)0x12, 
  (byte)0x00, (byte)0x00, (byte)0x04, (byte)0x14, (byte)0x10, 
  (byte)0x11, (byte)0x12, (byte)0x13, (byte)0x14, (byte)0x15, 
  (byte)0x16, (byte)0x17, (byte)0x18, (byte)0x19, (byte)0x1a, 
  (byte)0x1b, (byte)0x1c, (byte)0x1d, (byte)0x41, (byte)0xAB, 
  (byte)0xCD, (byte)0xEF 
}; 
byte[] response = sat.exchangeAPDU(envelope);

Chapter 3