The APDU I/O API

The APDU I/O library is used to develop Java Card client applications and Java Card platform simulators. It provides the means to exchange APDUs by using the T=0 or T=1 protocols.

The library is located in the file JC_HOME_TOOLS\lib\tools.jar.

All publicly available APDU I/O client classes are located in the package com.sun.javacard.apduio.

APDU I/O Classes and Interfaces

The APDU I/O classes and interfaces are described in this section.

• class Apdu

  Represents a pair of APDUs (both C-APDU and R-APDU). Contains various helper methods to access APDU contents and constants providing standard offsets within the APDU.

• interface CadClientInterface

  Represents an interface from the client to the card reader or a simulator. Includes methods for powering up, powering down and exchanging APDUs.

  • void exchangeApdu(Apdu apdu)

    Exchanges a single APDU with the card. Note that the APDU object contains both incoming and outgoing APDUs.

  • public byte[] powerUp()

    Powers up the card and returns ATR (Answer-To-Reset) bytes.

  • void powerDown(boolean disconnect)

    Powers down the card. The parameter, applicable only to communications with a simulator, means "close the socket". Normally, it is true for contacted connection, false for contactless. See Two-interface Card Simulation for more details.

  • void powerDown()

    Equivalent to powerDown(true).

• abstract class CadDevice

  Factory and a base class for all CadClientInterface implementations included with the APDU I/O library. Includes constants for the T=0 and T=1 clients.

  The factory method static CadClientInterface getCadClientInstance(byte protocolType, InputStream in, OutputStream out) returns a new instance of CadClientInterface. The in and out streams correspond to a socket connection to a simulator. Protocol type can be one of:

  • CadDevice.PROTOCOL_T0

  • CadDevice.PROTOCOL_T1

Exceptions

The following exceptions may be thrown in case of system malfunction or protocol violations:

• CadTransportException extends Exception

• T1Exception extends CadTransportException

• TLP224Exception extends CadTransportException

In all cases, their toString() method returns the cause of failure. In addition, java.io.IOException may be thrown at any time if the underlying socket connection is terminated or could not be established.