Packaging and Deploying Your Application

C H A P T E R 8

This chapter describes how to prepare your applet application to be put into module JAR files, and then to a smart card. The off-card installer, the scriptgen tool, resides on your desktop and operates as a packager.

If you have developed your classic application using the Connected Edition of the development kit and are bringing your finished CAP file back into this classic development kit for packaging and deployment, the scriptgen tool described in this chapter is where you need to start.

The output from scriptgen goes to apdutool, which resides on your desktop and acts as a deployment tool. The on-card installer resides in the RE on the card and receives Application Protocol Data Unit commands (APDUs) from apdutool.

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 16). They are also used by all RMI samples included with this development kit (See Chapter 4).

The development kit installer can be used to:

Dynamically download a Java Card technology package to a Java Card technology-compliant smart card. During development, the CAP file can be installed in the Java Card RE rather than on a Java Card technology-compliant smart card. The installer is capable of downloading version 2.1, 2.2, 2.2.1, 2.2.2, 3.0, 3.0.1, 3.0.2, and 3.0.3 Java Card technology-based CAP files.

Perform necessary on-card linking.

Delete applets and packages from a Java Card technology-compliant smart card. Once the installer is selected, requests for deletion can be sent from the terminal to the Java Card technology-compliant smart card in the form of APDU commands. For more information, see Using the On-card Installer for Deletion.

Setting default applets on different logical channels.

The on-card installer is not a multiselectable application. On startup, the on-card installer is the default applet on logical channel 0. The default applet on the other logical channels is set to No applet selected.

Installer Components and Data Flow

FIGURE 8-1 illustrates the components of the installer and how they interact with other parts of Java Card technology. The dotted line encloses the installer components.

The off-card installer is scriptgen. The on-card installer resides on the smart card. apdutool is not considered an installer, but processes the output from scriptgen and sends it to the on-card installer.

For more information about the installer, see the Runtime Environment Specification, Java Card Platform, Version 3.0.1, Classic Edition.

FIGURE 8-1 Installer Components

This figure has already been described in text.

The data flow of the installation process is as follows:

1. The scriptgen off-card installer takes as input a version 2.1, 2.2, 2.2.1, 2.2.2, 3.0, 3.0.1, 3.0.2 or 3.0.3 CAP file produced by the Converter, and produces a text file that contains a sequence of APDU commands.

2. This set of APDUs is then read by apdutool and sent to the on-card installer.

3. The on-card installer processes the CAP file contents contained in the APDU commands as it receives them.

4. The response APDU from the on-card installer contains a status and optional response data.

Running `scriptgen`

The scriptgen tool converts a package contained in a CAP file into a script file. The script file contains a sequence of APDUs in ASCII format suitable for another tool, such as apdutool, to send to the CAD. The CAP file component order in the APDU script is identical to the order recommended by the Virtual Machine Specification, Java Card Platform, Version 3.0.1, Classic Edition.

If you have a source release, you can localize locale-specific data associated with the scriptgen tool. For more information, see Chapter 14.

Enter the scriptgen command on the command line in this format (see TABLE 8-1 for a description of the options):

scriptgen.bat [options] cap-file

Note - The file to invoke scriptgen is a batch file (scriptgen.bat) that must be run from a working directory of JC_CLASSIC_HOME\bin in order for the code to execute properly.

TABLE 8-1 `scriptgen` Command Line Options
Option	Description
`-help`	Prints a help message and exits.
cap-file	File name of the CAP including the full absolute path.
`-nobanner`	Suppresses printing of the version number.
`-nobeginend`	Suppresses the output of the CAP Begin” and CAP End” APDU commands.
`-o` filename	Specifies an output filename (default is `stdout`).
`-package` package-name	Specifies the name of the package contained in the CAP file. According to the Virtual Machine Specification, Java Card Platform, Version 3.0.1, Classic Edition, the CAP file can contain components besides the ones required by the package. This option helps to avoid any possible ambiguity in determining which components should be included.
`-version`	Prints the version number and exits.

Note - If the CAP file contains components of multiple packages, you must use the -package <package_name> option to specify which package to process.

Note - The apdutool commands: powerup; and powerdown; are not included in the output from scriptgen.

Sending and Receiving APDUs

The apdutool reads a script file containing APDUs and sends them to the RI, or to 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 Chapter 14.

Running `apdutool`

You run apdutool with the following command syntax (see TABLE 8-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] [-s serial-port ] [-version] [-mi] [input-file-name]

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

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 8-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).
-s serial-port	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. For more information on installing this package, see Prerequisites to Installing the Development Kit. 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.
-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.

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 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 8-3 describes each supported script file command in detail noting that they are not case sensitive.

TABLE 8-3 Supported APDU Script File Commands
Command	Description
	Note - All APDU script file commands are not case-sensitive.
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 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;

Setting Default Applets

The RI supports setting distinct default applets on distinct logical channels and distinct interfaces. This request can be used 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 8-4 Set Default Applets on Different Logical Channels
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 will be configured as 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.

Downloading CAP Files and Creating Applets

The procedures for CAP file download and applet instance creation are described in the following sections, as are the on-card installer APDU protocol events and APDU types.

Downloading the CAP File

In this procedure, the CAP file is downloaded but applet creation (instantiation) is postponed until a later time. Follow these steps to perform this installation:

1. Use scriptgen to convert a CAP file to an APDU script file.

2. Prepend these commands to the APDU script file:

	powerup;
	// Select the installer applet
	0x00 0xA4 0x04 0x00 0x09 0xa0 0x00 0x00 0x00 0x62 0x03 0x01 0x08 		0x01 0x7F;

3. Append this command to the APDU script file:

powerdown;

4. Invoke apdutool with this APDU script file path as the argument.

Creating an Applet Instance

In this procedure, the applet from a previously downloaded CAP file or an applet compiled in the mask is created. For example, follow these steps to create the JavaPurse applet:

1. Determine the applet AID.

2. Create an APDU script similar to this:

	powerup;
	// Select the installer applet
	0x00 0xA4 0x04 0x00 0x09 0xa0 0x00 0x00 0x00 0x62 0x03 0x01 0x08 		0x01 0x7F;
	// create JavaPurse
	0x80 0xB8 0x00 0x00 0x0b 0x09 0xa0 0x00 0x00 0x00 0x62 0x03 0x01 			0x04 0x01 0x00
	0x7F;
	powerdown;

3. Invoke apdutool with this APDU script file path as the argument.

On-card Installer APDU Protocol

The on-card installer APDU protocol follows a specific time sequence of events in the transmission of Applet Protocol Data Units as shown in FIGURE 8-2.

FIGURE 8-2 On-card Installer APDU Transmission Sequence

This figure has already been described in text.

APDU Types

There are many different APDU types, which are distinguished by their fields and field values. The following sections describe these APDU types in more detail, including their bit frame formats, field names and field values.

Select

Response

CAP Begin

CAP End

Component ## Begin

Component ## End

Component ## Data

Create Applet

Abort

Note - In the following APDU commands, the x in the second nibble of the class byte indicates that the installer can be invoked on channels 0, 1, or 2. For example, 0x8x.

Select

TABLE 8-5 specifies the field sequence in the Select APDU, which is used to invoke the on-card installer.

TABLE 8-5 `Select` APDU Command
0x0x, 0xa4, 0x04, 0x00	Lc field	Installer AID	Le field

Response

TABLE 8-6 specifies the field sequence in the Response APDU. A Response APDU is sent as a response by the on-card installer after each APDU that it receives. The Response APDU can be either an Acknowledgment (called an ACK), which indicates that the most recent APDU was received successfully, or it can be a Negative Acknowledgement (called a NAK), which indicates that the most recent APDU was not received successfully and must be either resent or the entire installer transmission must be restarted. The first ACK indicates that the on-card installer is ready to receive. The value for an ACK frame SW1SW2 is 9000, and the value for a NAK frame SW1SW2 is 6XXX.

TABLE 8-6 Response APDU Command
[optional response data]	SW1SW2

CAP Begin

TABLE 8-7 specifies the field sequence in the CAP Begin APDU. The CAP Begin APDU is sent to the on-card installer, and indicates that the CAP file components are going to be sent next, in sequentially numbered APDUs.

TABLE 8-7 CAP Begin APDU Command
0x8x, 0xb0, 0x00, 0x00	[Lc field]	[optional data]	Le field

CAP End

TABLE 8-8 specifies the field sequence in the CAP End APDU. The CAP End APDU is sent to the on-card installer, and indicates that all of the CAP file components have been sent.

TABLE 8-8 CAP End APDU Command
0x8x, 0xba, 0x00, 0x00	[Lc field]	[optional data]	Le field

Component ## Begin

TABLE 8-9 specifies the field sequence in the Component ## Begin APDU. The double pound sign indicates the component token of the component being sent. The CAP file is divided into many components, based on class, method, etc. The Component ## Begin APDU is sent to the on-card installer, and indicates that component ## of the CAP file is going to be sent next.

TABLE 8-9 Component ## Begin APDU Command
0x8x, 0xb2, 0x##, 0x00	[Lc field]	[optional data]	Le field

Component ## End

TABLE 8-10 specifies the field sequence in the Component ## End APDU. The Component ## End APDU is sent to the on-card installer, and indicates that component ## of the CAP file has been sent.

TABLE 8-10 Component ## End APDU Command
0x8x, 0xbc, 0x##, 0x00	[Lc field]	[optional data]	Le field

Component ## Data

TABLE 8-11 specifies the field sequence in the Component ## Data APDU. The Component ## Data APDU is sent to the on-card installer, and contains the data for component ## of the CAP file.

TABLE 8-11 Component ## Data APDU Command
0x8x, 0xb4, 0x##, 0x00	Lc field	Data field	Le field

Create Applet

TABLE 8-12 specifies the field sequence in the Create Applet APDU. The Create Applet APDU is sent to the on-card installer, and tells the on-card installer to create an applet instance from each of the already sequentially transmitted components of the CAP file.

TABLE 8-12 Create Applet APDU Command
0x8x, 0xb8, 0x00, 0x00	Lc field	AID length field	AID field	parameter length field	[parameters]	Le field

Abort

TABLE 8-13 specifies the data sequence in the Abort APDU. The Abort APDU indicates that the transmission of the CAP file is terminated, and that the transmission is not complete and must be redone from the beginning in order to be successful.

TABLE 8-13 Abort APDU Command
0x8x, 0xbe, 0x00, 0x00	Lc field	[optional data]	Le field

APDU Responses to Installation Requests

The installer sends a response code of 0x9000 to indicate that a command completed successfully. Version 3.0.3 of the RI provides a number of codes that can be sent in response to unsuccessful installation requests. TABLE 8-14 describes these codes.

TABLE 8-14 APDU Responses to Installation Requests
Response Code	Description
0x6402	Invalid CAP file magic number. Cause: An incorrect magic number was specified in the CAP file. Solution: Refer to the Java Virtual Machine Specification for the correct magic number. Ensure that the CAP file is built correctly, run it through `scriptgen`, and download the resulting script file to the card.
0x6403	Invalid CAP file minor number. Cause: An invalid CAP file minor number was specified in the CAP file. Solution: Refer to the Java Virtual Machine Specification for the correct minor number. Ensure that the CAP file is built correctly, run it through `scriptgen`, and download the resulting script file to the card.
0x6404	Invalid CAP file major number. Cause: An invalid CAP file major number was specified in the CAP file. Solution: Refer to the Java Virtual Machine Specification for the correct major number. Ensure that the CAP file is built correctly, run it through `scriptgen`, and download the resulting script file to the card.
0x640b	Integer not supported. Cause: An attempt was made to download a CAP file that requires integer support into a CREF that does not support integers. Solution: Either change the CAP file so that it does not require integer support or build the version of CREF that supports integers.
0x640c	Duplicate package AID found. Cause: A duplicate package AID was detected in CREF. Solution: Choose a new AID for the package to be installed.
0x640d	Duplicate Applet AID found. Cause: A duplicate Applet AID was detected in CREF. Solution: Choose a new AID for the applet to be installed.
0x640f	Installation aborted. Cause: Installation was aborted by an outside command. Solution: Restart the CAP installation from the beginning and check the `INS` bytes in the installation script for the offending command.
0x6421	Installer in error state. Cause: A non-recoverable error previously occurred. Solution: Scan the `apdutool` output for previous APDU responses indicating an error. Restart the CAP installation.
0x6422	CAP file component out of order. Cause: Installer unable to proceed because it did not receive a component that is a prerequisite to process the current component. Solution: Check the script file contents for the correct component ordering.
0x6424	Exception occurred. Cause: General purpose error in the installer or applet code. Solution: Check your applet code for errors.
0x6425	Install APDU command out of order. Cause: Installer APDU commands were received out of order. Solution: Check the script file for the order of APDU commands. See On-card Installer APDU Transmission Sequence for more information on the ordering of APDU commands.
0x6428	Invalid component tag number. Cause: An incorrect component tag number was detected during download. Solution: Refer to Chapter 6 in the Java Virtual Machine Specification for the correct tag number.
0x6436	Invalid install instruction. Cause: An invalid Installer APDU command was received. Solution: Check the script file for the offending command. See On-card Installer APDU Transmission Sequence” for more information on APDU commands.
0x6437	On-card package max exceeded. Cause: Package installation failed because the number of packages that can be stored on the card has been exceeded. Solution: Remove some packages from the CREF.
0x6438	Imported package not found. Cause: A package that is required by the current package was not found. Solution: Download the required package first.
0x643a	On-card applet package max exceeded. Cause: Installation of an applet package failed because the number of applet packages that can be stored on the card has been exceeded. Solution: Remove some applet packages from the CREF.
0x6442	Maximum allowable package methods exceeded. Cause: The limit of 128 package methods on the card has been exceeded. Solution: Modify the package to support fewer methods.
0x6443	Applet not found for installation. Cause: An attempt was made to create an applet instance, but the applet code was not installed on the card. Solution: Verify that the applet package has been downloaded to the card.
0x6444	Applet creation failed. Cause: A general purpose error to indicate that an unsuccessful attempt was made to create the applet. Solution: Verify availability of resources on the card, check the applet’s `install` method, and so on.
0x644f	Package name is too long. Cause: The package name exceeds the length specified in Section 2.2.4.1 of the Java Virtual Machine Specification. Solution: Replace the name and rebuild.
0x6445	Maximum allowable applet instances exceeded. Cause: Creation of the applet instance failed because the number of applet instances that can be stored on the card has been exceeded. Solution: Remove some applet instances from the CREF.
0x6446	Memory allocation failed. Cause: The amount of memory available on the card has been exceeded. Solution: Verify the amount of memory that is available on the card. Remove packages, applets, and so on, to create enough space. Check the memory requirements of the applet or package being installed or downloaded.
0x6447	Imported class not found. Cause: A class that is required by the current class was not found. Solution: Download the required class first.

A Sample APDU Script

The following is a sample APDU script to download, create, and select the HelloWorld applet.

powerup;
 
// Select the on-card installer applet
0x00 0xA4 0x04 0x00 0x09 0xa0 0x00 0x00 0x00 0x62 0x03 0x01 0x08 0x01 0x7F;
 
// CAP Begin 
0x80 0xB0 0x00 0x00 0x00 0x7F;
 
// com/sun/javacard/samples/HelloWorld/javacard/Header.cap
// component begin
0x80 0xB2 0x01 0x00 0x00 0x7F;
// component data
0x80 0xB4 0x01 0x00 0x16 0x01 0x00 0x13 0xDE 0xCA 0xFF 0xED 0x01 0x02 0x04 0x00 0x01 0x09 0xA0 0x00 0x00 0x00 0x62 0x03 0x01 0x0C 0x01 0x7F;
// component end
0x80 0xBC 0x01 0x00 0x00 0x7F;
 
// com/sun/javacard/samples/HelloWorld/javacard/Directory.cap
0x80 0xB2 0x02 0x00 0x00 0x7F;
0x80 0xB4 0x02 0x00 0x20 0x02 0x00 0x1F 0x00 0x13 0x00 0x1F 0x00 0x0E 0x00 0x0B 0x00 0x36 0x00 0x0C 0x00 0x65 0x00 0x0A 0x00 0x13 0x00 0x00 0x00 0x6C 0x00 0x00 0x00 0x00 0x00 0x00 0x01 0x7F;
0x80 0xB4 0x02 0x00 0x02 0x01 0x00 0x7F;
0x80 0xBC 0x02 0x00 0x00 0x7F;
 
// com/sun/javacard/samples/HelloWorld/javacard/Import.cap
0x80 0xB2 0x04 0x00 0x00 0x7F;
0x80 0xB4 0x04 0x00 0x0E 0x04 0x00 0x0B 0x01 0x00 0x01 0x07 0xA0 0x00 0x00 0x00 0x62 0x01 0x01 0x7F;
0x80 0xBC 0x04 0x00 0x00 0x7F;
 
// com/sun/javacard/samples/HelloWorld/javacard/Applet.cap
0x80 0xB2 0x03 0x00 0x00 0x7F;
0x80 0xB4 0x03 0x00 0x11 0x03 0x00 0x0E 0x01 0x0A 0xA0 0x00 0x00 0x00 0x62 0x03 0x01 0x0C 0x01 0x01 0x00 0x14 0x7F;
0x80 0xBC 0x03 0x00 0x00 0x7F;
 
// com/sun/javacard/samples/HelloWorld/javacard/Class.cap
0x80 0xB2 0x06 0x00 0x00 0x7F;
0x80 0xB4 0x06 0x00 0x0F 0x06 0x00 0x0C 0x00 0x80 0x03 0x01 0x00 0x01 0x07 0x01 0x00 0x00 0x00 0x1D 0x7F;
0x80 0xBC 0x06 0x00 0x00 0x7F;
 
// com/sun/javacard/samples/HelloWorld/javacard/Method.cap
0x80 0xB2 0x07 0x00 0x00 0x7F;
0x80 0xB4 0x07 0x00 0x20 0x07 0x00 0x65 0x00 0x02 0x10 0x18 0x8C 0x00 0x01 0x18 0x11 0x01 0x00 0x90 0x0B 0x87 0x00 0x18 0x8B 0x00 0x02 0x7A 0x01 0x30 0x8F 0x00 0x03 0x8C 0x00 0x04 0x7A 0x7F;
0x80 0xB4 0x07 0x00 0x20 0x05 0x23 0x19 0x8B 0x00 0x05 0x2D 0x19 0x8B 0x00 0x06 0x32 0x03 0x29 0x04 0x70 0x19 0x1A 0x08 0xAD 0x00 0x16 0x04 0x1F 0x8D 0x00 0x0B 0x3B 0x16 0x04 0x1F 0x41 0x7F;
0x80 0xB4 0x07 0x00 0x20 0x29 0x04 0x19 0x08 0x8B 0x00 0x0C 0x32 0x1F 0x64 0xE8 0x19 0x8B 0x00 0x07 0x3B 0x19 0x16 0x04 0x08 0x41 0x8B 0x00 0x08 0x19 0x03 0x08 0x8B 0x00 0x09 0x19 0xAD 0x7F;
0x80 0xB4 0x07 0x00 0x08 0x00 0x03 0x16 0x04 0x8B 0x00 0x0A 0x7A 0x7F;
0x80 0xBC 0x07 0x00 0x00 0x7F;
 
// com/sun/javacard/samples/HelloWorld/javacard/StaticField.cap
0x80 0xB2 0x08 0x00 0x00 0x7F;
0x80 0xB4 0x08 0x00 0x0D 0x08 0x00 0x0A 0x00 0x00 0x00 0x00 0x00 0x00 0x00 0x00 0x00 0x00 0x7F;
0x80 0xBC 0x08 0x00 0x00 0x7F;
 
// com/sun/javacard/samples/HelloWorld/javacard/ConstantPool.cap
0x80 0xB2 0x05 0x00 0x00 0x7F;
0x80 0xB4 0x05 0x00 0x20 0x05 0x00 0x36 0x00 0x0D 0x02 0x00 0x00 0x00 0x06 0x80 0x03 0x00 0x03 0x80 0x03 0x01 0x01 0x00 0x00 0x00 0x06 0x00 0x00 0x01 0x03 0x80 0x0A 0x01 0x03 0x80 0x0A 0x7F;
0x80 0xB4 0x05 0x00 0x19 0x06 0x03 0x80 0x0A 0x07 0x03 0x80 0x0A 0x09 0x03 0x80 0x0A 0x04 0x03 0x80 0x0A 0x05 0x06 0x80 0x10 0x02 0x03 0x80 0x0A 0x03 0x7F;
0x80 0xBC 0x05 0x00 0x00 0x7F;
 
// com/sun/javacard/samples/HelloWorld/javacard/RefLocation.cap
0x80 0xB2 0x09 0x00 0x00 0x7F;
0x80 0xB4 0x09 0x00 0x16 0x09 0x00 0x13 0x00 0x03 0x0E 0x23 0x2C 0x00 0x0C 0x05 0x0C 0x06 0x03 0x07 0x05 0x10 0x0C 0x08 0x09 0x06 0x09 0x7F;
0x80 0xBC 0x09 0x00 0x00 0x7F;
 
// CAP End
0x80 0xBA 0x00 0x00 0x00 0x7F;
 
// create HelloWorld
0x80 0xB8 0x00 0x00 0x0b 0x09 0xa0 0x00 0x00 0x00 0x62 0x03 0x01 0x03;
0x01 0x00 0x7F;
 
// Select HelloWorld
0x00 0xA4 0x04 0x00 9 0xA0 0x00 0x00 0x00 0x62 0x03 0x01 0x03 0x01 0x7F;
 
powerdown;

Using the On-card Installer for Deletion

The on-card installer in version 3.0.3 of the Java Card 3 Platform, Classic Edition reference implementation provides the ability to delete package and applet instances from the card’s memory. Once the on-card installer is selected, it can receive deletion requests from the terminal in the form of ADPU commands. Requests to delete an applet or package cannot be sent from an applet on the card. For more information on package and applet deletion, see the Runtime Environment Specification, Java Card Platform, Version 3.0.1, Classic Edition.

How to Send a Deletion Request

1. Select the on-card installer applet on the card.

2. Send the ADPU for the appropriate deletion request to the installer. The requests that you can send are described in the following sections:

Delete Package

Delete Package and Applets

Delete Applets

For information on the responses that the ADPU requests can return, see APDU Responses to Deletion Requests.

APDU Requests to Delete Packages and Applets

You can send requests to delete a package, a package and its applets, and individual applets.

Note - In the following APDU commands, the x in the second nibble of the class byte indicates that the installer can be invoked on channels 0, 1, or 2. For example, 0x8x.

Delete Package

In this request, the Data field contains the size of the package AID and the AID of the package to be deleted. TABLE 8-15 shows the format of the Delete Package request and the expected response.

TABLE 8-15 Delete Package Command
0x8x, 0xc0, 0xXX, 0xXX	Lc field	Data field	Le field

The value of 0xXX can be any value for the P1 and P2 parameters. The installer will ignore the 0xXX values. An example of a delete package request on channel 1 would be:

//Delete Package Request:
 0x81 0xC0 0x00 0x00 0x08 0x07 0xa0 0x00 0x00 0x00 0x62 0x12 0x34 0x7F;

In this example, 0x07 is the AID length and 0xa0 0x00 0x00 0x00 0x62 0x12 0x34 is the package AID.

Delete Package and Applets

This request is similar to the Delete Package command. In this case the package and applets are removed simultaneously. The data field will contain the size of the package AID and the AID of the package to be deleted. TABLE 8-16 shows the format of the Delete Packages and Applets request and the expected response.

TABLE 8-16 Delete Package and Applets Command
0x8x, 0xc2, 0xXX, 0xXX	Lc field	Data field	Le field

The value of 0xXX can be any value for the P1 and P2 parameters. The installer will ignore the 0xXX values. An example of a package and applets deletion request on channel 1 would be:

//Delete Package And Applets request
0x81 0xC2 0x00 0x00 0x08 0x07 0xa0 0x00 0x00 0x00 0x62 0x12 0x34 0x7F;

In this example, 0x07 is the AID length and 0xa0 0x00 0x00 0x00 0x62 0x12 0x34 is the package AID.

Delete Applets

In this request, the “#” symbol in the P1 byte indicates the number of applets to be deleted, which can have a maximum value of eight. The Lc field contains the size of the data field. Data field contains a list of AID size and AID pairs. TABLE 8-17 shows the format of the Delete Applet request and the expected response.

TABLE 8-17 Delete Applet Command
0x8x, 0xc4, 0x0#, 0xXX	Lc field	Data field	Le field

The value of 0xXX can be any value for the P2 parameter. The installer will ignore the 0xXX values. An example of a applet deletion request on channel 1 would be:

//Delete the applet’s request for two applets
0x81 0xC4 0x02 0x00 0x12 0x08 0xa0 0x00 0x00 0x00 0x62 0x12 0x34 0x12 0x08 0xa0 0x00 0x00 0x00 0x62 0x12 0x34 0x13 0x7F;

In this example, the “#” symbol is replaced with “2” (0x02) indicating that there are two applets to be deleted. The first applet is 0xa0 0x00 0x00 0x00 0x62 0x12 0x34 0x12 and the second applet is 0xa0 0x00 0x00 0x00 0x62 0x12 0x34 0x13.

APDU Responses to Deletion Requests

When the on-card installer receives the request from the terminal, it can return any of the responses shown in TABLE 8-18.

TABLE 8-18 APDU Responses to Deletion Requests
Response Code	Description
0x6a86	Invalid value for `P1` or `P2` parameter. Cause: Value for `P1` is less than 1 or greater than 8. Solution: Ensure that the value for `P1` is between 1 and 8.
0x6443	Applet not found for deletion. Cause: The applet with the specified AID does not exist. Solution: Check and correct the AID.
0x644b	Package not found. Cause: The package with the specified AID does not exist. Solution: Check and correct the AID.
0x644c	Dependencies on package. Cause: Package has other packages dependent on it, or there are some object instances of classes belonging to this package residing in memory. Solution: Determine which packages are dependent and remove them. If there are object instances of classes belonging to this package residing in memory, try the package and applet deletion combination command to remove the package from card memory.
0x644d	One or more applet instances of this package are present. Cause: One or more applet instances of this package are present Solution: Remove the applets first and then try package deletion, or try the package and applet deletion combination command.
0x644e	Package is ROM package. Cause: An attempt was made to delete a package in ROM. Solution: There is no solution to this problem since packages in ROM cannot be deleted.
0x6448	Dependencies on applet. Cause: Other applets are using objects owned by this applet. Solution: Remove references from other applets to this applet’s objects, or try to delete the dependent applets along with this applet.
0x6449	Internal memory constraints. Cause: There is not enough memory available for the intermediate structures required by applet deletion. Solution: It may not be possible to recover from this error. One possible thing that can be tried in case of multiple applet deletion is to try to delete applets individually.
0x6452	Cannot delete applet; an applet in the same context is currently active on one of the logical channels. Cause: An attempt was made to delete an applet while another applet in the same context is currently active on one of the logical channels. Solution: In the context of the applet that you are attempting to delete, make sure that no applet is selected on any of the logical channels. Then, re-attempt to delete the applet.
0x6700	Invalid value for `Lc` parameter. Cause: In case of package deletion, the value for `Lc` is less than 6 or greater than 17. In case of applet deletion, the value for `Lc` is less than 7 or greater than 136. Solution: Value of `Lc` in both of these cases depends on the AIDs being passed in the APDU. Make sure the AIDs are correct and value for `Lc` is between 6 and 16 in case of package deletion and between 7 and 135 in case of applet deletion.

The response has the format shown in TABLE 8-19.

TABLE 8-19 APDU Response Format
[optional response data]	SW1SW2

On-Card Installer Limits

The limits for the on-card installer are as follows.

The maximum length of the parameter in the applet creation APDU command is 110.

The maximum number of packages to be downloaded is 32, including up to 16 applet packages.

The maximum number of applet instances to be created is 16.

The maximum length of data in the installer APDU commands is 128.

No on-card CAP file verification is supported.

All subsequent APDU commands enclosed in a CAP Begin, CAP End APDU pair will continue to fail after an error occurs.

The maximum number of applets that can be deleted using one command is eight.

Installer Components and Data Flow

Running scriptgen

Sending and Receiving APDUs

Running apdutool

apdutool Examples

Directing Output to the Console

Directing Output to a File

Using APDU Script Files

APDUScript Preprocessor Commands

Setting Default Applets

On-Card Installer Applet AID

Downloading CAP Files and Creating Applets

Downloading the CAP File

Creating an Applet Instance

On-card Installer APDU Protocol

APDU Types

Select

Response

CAP Begin

CAP End

Component ## Begin

Component ## End

Component ## Data

Create Applet

Abort

APDU Responses to Installation Requests

A Sample APDU Script

Using the On-card Installer for Deletion

How to Send a Deletion Request

APDU Requests to Delete Packages and Applets

Delete Package

Delete Package and Applets

Delete Applets

APDU Responses to Deletion Requests

On-Card Installer Limits

Running `scriptgen`

Running `apdutool`

`apdutool` Examples