1. Development Kit User Guide
  2. Setup, Samples and Tools
  3. Packaging and Deploying Your Application
  4. Downloading CAP Files and Creating Applets

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

Description of Figure 8-2 follows
Description of "Figure 8-2 On-card Installer APDU Transmission Sequence"

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 APDU Command

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

Command Lc Installer Le

0x0x, 0xa4, 0x04, 0x00

Lc field

Installer AID

Le field
Response APDU Command

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

Data Response

[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

Command Lc data Le

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

Command Lc data Le

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, and so on. 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

Command Lc data Le

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

Command Lc data Le

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

Command Lc data Le

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

Command Lc AID length AID Parameter length Parameter Le

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

Command Lc data Le

0x8x, 0xbe, 0x00, 0x00

Lc field

[optional data]

Le field

APDU Responses to Installation Requests

If a command completes successfully, the installer sends a response code of 0x9000. A number of codes can be sent in response to unsuccessful installation requests, as shown in Table 8-14.

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 Sending and Receiving APDUs 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 Sending and Receiving APDUs 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 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;