Using the APDU Tool

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.

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] [-o outputFile] [-p portNumber] [-s serialPort] [-t0] 	[-version] [inputFile ...] [-verbose]

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


Option	Description
`-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. To get help for `the` APDU tool, run `bin\apdutool.bat` `-help` on the command line.
-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:

CLA - ISO 7816-4 class byte.
INS - ISO 7816-4 instruction byte.
P1 - ISO 7816-4 P1 parameter byte.
P2 - ISO 7816-4 P2 parameter byte.
LC - ISO 7816-4 input byte count. 1 byte in non-extended mode, 2 bytes in extended mode.
byte 0 ... byte LC-1 - Input data bytes.
LE - ISO 7816- 4 expected output length. 1 byte in non-extended mode, 2 bytes in extended mode.

The script file commands shown in TABLE 10-2 are supported:


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.

These packages provide a convenient API for writing client-side applications that communicate with Java Card technology enabled smart cards.