C H A P T E R  12

Sending and Receiving APDU Commands

The apdutool reads a script file containing Application Protocol Data Unit commands (APDUs) and sends them to the C-language Java Card RE (or other Java Card RE) or the Java Card WDE. Each APDU is processed and returned to apdutool, which displays both the command and response APDUs on the console. Optionally, apdutool can write this information to a log file.


Running apdutool

The file to invoke apdutool is a shell script (apdutool) on the Solaris or Linux platform, and a batch file (apdutool.bat) on the Microsoft Windows platform.

apdutool starts listening to APDUs in T=1 as the default format, unless otherwise specified, on the TCP/IP port specified by the -p portNumber parameter for contacted and portNumber+1 for contactless. The default port is 9025.

The command line usage for apdutool is:

apdutool [-h hostname] [-nobanner] [-noatr] [-o <outputFile>] 	[-p portNumber] [-s serialPort] [-t0|-pcsc] 	[-version] <inputFile> [<inputFile> ...]

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


TABLE 12-1 apdutool Command Line Options

Option

Description

-h hostname

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

-help

Displays online documentation for this command. To get help for apdutool, run bin/apdutool -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 flag, output defaults to standard output.

-p portNumber

Specifies a TCP/IP socket port other than the default port (which is 9025).

-s serialPort

Specifies the serial port to use for communication, rather than a TCP/IP socket port. For example, serialPort can be COM1 on a Microsoft Windows system and /dev/term/a on a Solaris system.

 

Currently, this option is not supported on the Linux platform.

 

To use this option, the javax.comm package must be installed on your system. For more information on installing this package, see Prerequisites for Installing the Binary Release.

 

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

-t0

Runs T=0 single interface.

-pcsc

Sends commands to a PC/SC-compatible card reader. Use of PC/SC is optional and unsupported.

-version

Outputs the version information.

<inputFile>

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


apdutool Examples

The following examples show how to use apdutool.

Directing Output to the Console

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

apdutool example.scr

Directing Output to a File

This command runs apdutool with the file example.scr as input. Output is written to the file example.scr.out.

apdutool -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-APDUs. Script file commands and C-APDUs are terminated with a semicolon (;). Comments can be of any of the three Java-language style comment formats (//, /*, or /**).

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

C-APDU syntax for apdutool 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 12-2 are supported:


TABLE 12-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.


These packages provide a convenient API for writing client-side applications that communicate with Java Card technology enabled smart cards and are used by all RMI demos included with this development kit.