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:
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:
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 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.
-
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 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 |
---|---|---|---|
|
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 |
---|---|---|---|
|
[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 |
---|---|---|---|
|
[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 |
---|---|---|---|
|
[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 |
---|---|---|---|
|
[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 |
---|---|---|---|
|
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 |
---|---|---|---|---|---|---|
|
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 |
---|---|---|---|
|
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 |
---|---|
|
Invalid CAP file magic number.
|
|
Invalid CAP file minor number.
|
|
Invalid CAP file major number.
|
|
Integer not supported.
|
|
Duplicate package AID found.
|
|
Duplicate Applet AID found.
|
|
Installation aborted.
|
|
Installer in error state.
|
|
CAP file component out of order.
|
|
Exception occurred.
|
|
Install APDU command out of order.
|
|
Invalid component tag number.
|
|
Invalid install instruction.
|
|
On-card package max exceeded.
|
|
Imported package not found.
|
|
On-card applet package max exceeded.
|
|
Maximum allowable package methods exceeded.
|
|
Applet not found for installation.
|
|
Applet creation failed.
|
|
Package name is too long.
|
|
Maximum allowable applet instances exceeded.
|
|
Memory allocation failed.
|
|
Imported class not found.
|
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;