Documentation



Java Card 3 Platform Development Kit User Guide, Classic Edition

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:

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

-help

Displays online help for the command.

-h host-name

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

-d

or

-descriptiveoutput

Formats the output in more user-readable form.

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

-noatr

Suppresses outputting an ATR (answer to reset).

-nobanner

Suppresses all banner messages.

-o output-file

Specifies an output file. If an output file is not specified with the -o flag, output defaults to standard output.

-p port-number

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

-t0

Runs T=0 single interface.

-verbose

If enabled, enables verbose apdutool output.

-version

Outputs the version information.

-mi

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:

  1. Enter the following command:
    apdutool example.scr

Directing Output to a File

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

To direct output to a file:

  1. Enter the following command:
    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 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.

Note:

All APDU script file commands are not case-sensitive.


Table 9-3 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.

select AID;

Selects the applet with the specified AID, where AID identifies the applet to be selected in the form of //aid/A005453412/151146712. For example: select //aid/A000000062/03010C0101;

open channel [channel-no] [on origin-channel];

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.

close channel channel-no [on origin-channel];

Closes the channel having the channel number specified by channel-no on origin channel origin-channel, where channel-no is an integer. on origin-channel is optional and the default value for origin-channel is basic channel number 0. origin-channel must be an integer from 0-19.

send APDU [to AID] [on origin-channel];

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 apdutool. on origin-channel is optional and specifies the origin channel to select an applet and send the specified APDU on. The default origin channel is 0 and possible values are 0 - 19. to AID is also optional, and when specified it builds and sends the select command before sending the APDU.


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

0x8x 0xc6 0xXX 0xYY

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.

On-Card Installer Applet AID

The on-card installer applet AID is: 0xa0,0x00,0x00,0x00,0x62,0x03,0x01,0x08,0x01.

Close Window

Table of Contents

Java Card: 3 Platform Development Kit User Guide, Classic Edition

Expand | Collapse