Sending and Receiving APDUs
The apdutool
reads a script file containing APDUs and sends them to the RI or another Java Card RE. 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. If you have a source release, you can localize messages from apdutool
. For more information, see Localizing With The Development Kit.
This section includes the following topics:
Running apdutool
The file to invoke apdutool
is a batch file (apdutool.bat
) that must be run from a working directory of JC_CLASSIC_HOME\bin
in order for the code to execute properly.
To run the apdutool
:
- Enter the following command (see Table 9-2 for a description of the options):
apdutool.bat [-t0] [-verbose] [-nobanner] [-noatr] \ [-d | --descriptiveoutput] [-k] [-o output-file] [-h host-name] [-p port-number] \ [-version] [-mi] [input-file-name]
The 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.
Table 9-2 apdutool Command Line Options
Option | Description |
---|---|
|
Displays online help for the command. |
|
Specifies the host name on which the TCP/IP socket port is found. (See the flag |
or
|
Formats the output in more user-readable form. |
|
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. |
|
Suppresses outputting an ATR (answer to reset). |
|
Suppresses all banner messages. |
|
Specifies an output file. If an output file is not specified with the |
|
Specifies a TCP/IP socket port other than the default port (which is 9025). |
|
Runs T=0 single interface. |
|
If enabled, enables verbose apdutool output. |
|
Outputs the version information. |
|
Required if the APDU script is using contacted and contactless commands multiple times in the same script file and the script switches between contacted and contactless interfaces many times. |
input-file-name |
Specifies an input script file. |
apdutool Examples
The following examples show how to use apdutool
in:
Directing Output to the Console
This command example runs the apdutool
with the file example.scr
as input. Output in this example is sent to the console. The default TCP port (9025) is used.
To direct output to the console:
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 programming 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.
Table 9-3 describes each supported script file command in detail noting that they are not case sensitive.
Table 9-3 Supported APDU Script File Commands
Command | Description |
---|---|
|
Redirects APDU activity to the contacted or primary interface. |
|
Redirects output to the contactless or secondary interface. |
|
Pauses execution of the script for the number of milliseconds specified by |
|
Echoes the quoted string to the output file. The leading and trailing quote characters are removed. |
|
Turns extended APDU input mode on. |
|
Turns extended APDU input mode off. |
|
Suppresses printing of the output. |
|
Restores printing of the output. |
|
Sends a |
|
Sends a |
|
Selects the applet with the specified AID, where AID identifies the applet to be selected in the form of |
|
Opens the channel with the channel number specified by channel-no on the origin channel specified by origin-channel, where channel-no is an integer. The default value for the origin channel is basic channel number 0. channel-no and origin-channel are both optional. origin-channel must be an integer from 0-19. |
|
Closes the channel having the channel number specified by channel-no on origin channel origin-channel, where channel-no is an integer. |
|
Sends the APDU specified by APDU after selecting the applet specified by AID on the specified origin channel, where the APDU format uses the C-APDU syntax of the |
APDUScript Preprocessor Commands
APDUScript 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 0x080 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;
Setting Default Applets
The RI supports setting distinct default applets on distinct logical channels and distinct interfaces. You can use this request to set the default applet for a particular logical channel in the specified interface. The applet being set as default must be properly registered with the RI prior to issuing this command.
Table 9-4 Set Default Applets on Different Logical Channels
Applet AID | Lc Field | Data | Le Field |
---|---|---|---|
|
Lc: AID length |
Data: Default applet AID |
Le: ignored |
NOTATION:
XX is the channel number where the specified applet is configured as default.
YY is the interface ID where the applet is configured as the default.
0
is primary contacted or only interface.1
is secondary contactless on dual interface.AID is the AID of the applet being set as the default.