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:
- 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;
|
Development Kit User’s Guide, Java Card 3 Platform, Version 3.0.2, Connected Edition
|
12-14-09
|
  
|
Copyright © 2009 Sun Microsystems, Inc. All rights reserved.