Using the Installer

The installer is not a multiselectable application. On startup, the 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 6 illustrates the components of the installer and how they relate to the rest of Java Card technology. The dotted line encloses the installer components that are described in this chapter.

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 for the Java Card™ Platform, Version 2.2.1 (Sun Microsystems, Inc., 2003).

TABLE 19 – scriptgen Command Line Options
Option	Description
`-help`	Prints a help message and exits.
`-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 for the Java Card™ Platform, Version 2.2.1, 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.

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

Procedures for CAP file download and applet instance creation are described in the following sections:

Downloading the CAP File

In this scenario, the CAP file is downloaded and applet creation (instantiation) is postponed until a later time. (Refer to the Create Only scenario below.) Follow these steps to perform this installation:

Creating an Applet Instance

In this scenario, 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:

Installer APDU Protocol

The Installer APDU protocol follows a specific time sequence of events in the transmission of Applet Protocol Data Units as shown in the following figure.

APDU Types

There are many different APDU types, which are distinguished by their fields, and field values. The following is a general list of APDUs.

Descriptions of each of these APDU data types, including their bit frame formats, field names and field values follows.

Select

The table below specifies the field sequence in the Select APDU, which is used to invoke the on-card installer.

Response

The table below 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.

CAP Begin

The table below 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.

CAP End

The table below 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.

Component ## Begin

The table below 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.

Component ## End

The table below 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.

Component ## Data

The table below 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.

Create Applet

The table below 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.

Abort

The table below 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.

APDU Responses to Installation Requests

TABLE 20 – Select APDU Command

0x0x, 0xa4, 0x04, 0x00	Lc field	Installer AID	Le field

TABLE 21 – Response APDU Command

[optional response data]	SW1SW2

TABLE 22 – CAP Begin APDU Command

0x8x, 0xb0, 0x00, 0x00	[Lc field]	[optional data]	Le field

TABLE 23 – CAP End APDU Command

0x8x, 0xba, 0x00, 0x00	[Lc field]	[optional data]	Le field

TABLE 24 – Component ## Begin APDU Command

0x8x, 0xb2, 0x##, 0x00	[Lc field]	[optional data]	Le field

TABLE 25 – Component ## End APDU Command

0x8x, 0xbc, 0x##, 0x00	[Lc field]	[optional data]	Le field

TABLE 26 – Component ## Data APDU Command

0x8x, 0xb4, 0x##, 0x00	Lc field	Data field	Le field

TABLE 27 – Create Applet APDU Command

0x8x, 0xb8, 0x00, 0x00	Lc field	AID length field	AID field	parameter length field	[parameters]	Le field

TABLE 28 – Abort APDU Command

0x8x, 0xbe, 0x00, 0x00	Lc field	[optional data]	Le field

The installer sends a response code of 0x9000 to indicate that a command completed successfully. Version 2.2.1 of the Java Card reference implementation provides a number of codes that can be sent in response to unsuccessful installation requests. TABLE 29 describes these codes.

TABLE 29 – 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 "Installer APDU Protocol" 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 commands was received. Solution: Check the script file for the offending command. See "Installer APDU Protocol" 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.1of 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 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;

Deleting Packages and Applets

The Installer in version 2.2.1 of the Java Card reference implementation provides the ability to delete package and applet instances from the card’s memory. Once the 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 for the Java Card™ Platform, Version 2.2.1 (Sun Microsystems, Inc., 2003).

How to Send a Deletion Request

APDU Requests to Delete Packages and Applets

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

Delete Package

In this request, the Data field contains the size of the package AID and the AID of the package to be deleted. The following is the format of the Delete Package request and the expected response:

TABLE 30 – Delete Package Command

0x8x, 0xc0, 0xXX, 0xXX	Lc field	Data field	Le field

where 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:

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. The following is the format of the Delete Packages and Applets request and the expected response:

TABLE 31 – Delete Package and Applets Command

0x8x, 0xc2, 0xXX, 0xXX	Lc field	Data field	Le field

where 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:

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. The following is the format of the Delete Applet request and the expected response:

TABLE 32 – Delete Applet Command

0x8x, 0xc4, 0x0#, 0xXX	Lc field	Data field	Le field

where 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:

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 installer receives the request from the terminal, it can return any of the following responses:

TABLE 33 – 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.

Chapter 12