C H A P T E R  10

Using the APDU Tool

When installing and running applets on a Java Card technology-compliant smart card, the APDU tool reads a script file containing Application Protocol Data Unit (APDU) commands and sends them to the Java Card runtime environment. Each APDU is processed and returned to the APDU tool, which displays both the command and response APDU commands on the console. Optionally, the APDU tool can write this information to a log file.

The APDU I/O packages provide a convenient API for writing client-side applications that communicate with Java Card technology-enabled smart cards, see Chapter 14.

This chapter includes the following sections:


Running the APDU Tool From the Command Line

The file used to invoke the APDU tool is the apdutool.bat batch file.

Unless otherwise specified, the APDU tool starts listening to APDU commands in the default format of T=1 on the TCP/IP port specified by either the -p portNumber parameter (for contacted) or the -p portNumber+1 parameter (for contactless). The default port is 9025.

The command line usage for the APDU tool is:

apdutool.bat [-h hostname] [-nobanner] [-noatr] [-k] [-mi]
[-d | --descriptiveoutput] [-o outputFile] [-p portNumber]
[-s serialPort] [-t0] [-version] [-verbose] [inputFile ...]

The option values and their actions are shown in TABLE 10-1.


TABLE 10-1 apdutool Command Line Options

Option

Description

-d

or

--descriptiveoutput

Formats the output in a more readable format.

-h hostname

Specifies the host name on which the TCP/IP socket port is found. (See the -p option.)

-help

Displays online documentation for this command.

-k

When using preprocessor directives in an APDU script, this option generates a related preprocessed APDU script file in the same directory as the APDU script.

-mi

Optional, however, if the APDU script is switching between contacted and contactless interfaces multiple times in the same script file, this option is required.

-noatr

Suppresses outputting an ATR (answer to reset).

-nobanner

Suppresses all banner messages.

-o outputFile

Specifies an output file. If an output file is not specified with the -o option, output defaults to standard output.

-p portNumber

Specifies a TCP/IP socket port other than the default port of 9025.

-s serialPort

Specifies the serial port to use for communication, rather than a TCP/IP socket port. For example, serialPort can be COM1.

To use this option, the javax.comm package must be installed on your system.

If you enter the name of a serial port that does not exist on your system, the APDU tool will respond by printing the names of available ports.

-t0

Runs T=0 single interface.

-version

Outputs the version information.

inputFile

Allows you to specify the input script (or scripts).

-verbose

Displays descriptive text during operation.


Examples of Using the APDU Tool

The following examples show how to use the APDU tool to direct output to the console or to a file.

Directing Output to the Console

The following command runs the APDU tool with the file example.scr as input. Output is sent to the console. The default TCP port (9025) is used.

apdutool.bat example.scr

Directing Output to a File

The following command runs the APDU tool with the file example.scr as input. Output is written to the file example.scr.out.

apdutool.bat -o example.scr.out example.scr


Using APDU Script Files

An APDU script file is a protocol-independent APDU format containing comments, script file commands, and C-APDU commands. Script file commands and C-APDU commands are terminated with a semicolon (;). Comments can be of any of the three Java programming language style comment formats (//, /*, or /**).

APDU commands are represented by decimal, hex or octal digits, UTF-8 quoted literals or UTF-8 quoted strings. C-APDU commands may extend across multiple lines.

C-APDU syntax for the APDU tool is as follows:

CLA INS P1 P2 LC [byte 0 byte 1 ... byte LC-1] LE;

Where:

APDU Script File Commands

APDU script file commands are not case sensitive. The script file commands shown in TABLE 10-2 are supported:


TABLE 10-2 Supported APDU Script File Commands

Command

Description

contacted;

Redirects APDU activity to the contacted or primary interface.

contactless;

Redirects output to the contactless or secondary interface.

delay Integer;

Pauses execution of the script for the number of milliseconds specified by Integer.

echo "string";

Echoes the quoted string to the output file. The leading and trailing quote characters are removed.

extended on;

Turns extended APDU input mode on.

extended off;

Turns extended APDU input mode off.

output off;

Suppresses printing of the output.

output on;

Restores printing of the output.

powerdown;

Sends a powerdown command to the reader in the active interface.

powerup;

Sends a powerup command to the reader in the active interface. A powerup command must be sent to the reader prior to executing any APDU on the selected interface.


APDU Script Preprocessor Commands

APDU script supports preprocessor directives as depicted in the following script file example, test.scr.


#define walletApplet //aid/A000000062/03010C0101
#define purseApplet //aid/A000000062/03010C0102
#define walletCommand 0x80 0xCA 0x00 0x00 0x02 0xAB 0x08 0x7F
powerup;
SELECT purseApplet;
Send walletCommand to walletApplet on 19;
powerdown;

To check what the preprocessor has done, run the APDUTool with the -k flag to create a file named test.scr.preprocessed in the same directory as test.scr. The test.scr.preprocessed content then looks like this:


powerup;
SELECT //aid/A000000062/03010C0102;
Send 0x80 0xCA 0x00 0x00 0x02 0xAB 0x08 0x7F to //aid/A000000062/03010C0101 on 19;
powerdown;