Using the APDU Tool
Description: This document describes how to use the development kit for the Java Card 3 Platform, Connected Edition, Version 3.0.2, to develop applet applications, web applications, servlets, and extended applets
Date: December 2009

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

- Using APDU Script Files

##

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:

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

### 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;

Copyright © 2009 Sun Microsystems, Inc. All rights reserved.