C H A P T E R 11 |
Using the Installer |
The development kit installer can be used to:
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.
FIGURE 11-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 that are described in this chapter.
The off-card installer is called scriptgen. The on-card installer is simply called "installer" in this document.
For more information about the installer, see the Runtime Environment Specification for the Java Card Platform, Version 2.2.2.
FIGURE 11-1 Installer ComponentsThe data flow of the installation process is as follows:
1. An off-card installer takes a version 2.1, 2.2, 2.2.1, or 2.2.2 CAP file, produced by the Java Card technology-based converter ("Java Card Converter"), as the input, 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.
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.2.
Enter the scriptgen command on the command line in this format:
scriptgen [options] <capFilePath>
The scriptgen command line options are described in TABLE 11-1.
Suppresses the output of the CAP Begin" and CAP End" APDU commands. |
|
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.2, 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. |
|
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. |
The on-card installer applet AID is: 0xa0,0x00,0x00,0x00,0x62,0x03,0x01,0x08,0x01.
The C-language Java Card RE 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 C-language Java Card RE prior to issuing this command.
The installer is invoked by using the apdutool. (See Chapter 12.)
Procedures for CAP file download and applet instance creation are described in the following sections:
These scenarios are described in the following sections.
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:
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.
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:
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.
The installer APDU protocol follows a specific time sequence of events in the transmission of Applet Protocol Data Units as shown in FIGURE 11-2.
FIGURE 11-2 Installer APDU Transmission SequenceThere 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. |
TABLE 11-3 specifies the field sequence in the Select APDU, which is used to invoke the on-card installer.
TABLE 11-4 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 11-5 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 11-6 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 11-7 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 11-8 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 11-9 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 11-10 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 11-11 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.
The installer sends a response code of 0x9000 to indicate that a command completed successfully. Version 2.2.2 of the Java Card platform reference implementation provides a number of codes that can be sent in response to unsuccessful installation requests. TABLE 11-12 describes these codes.
Install APDU command out of order.
|
|
|
|
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;
The installer in version 2.2.2 of the Java Card platform 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.2.
1. Select the 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:
For information on the responses that the ADPU requests can return, see APDU Responses to Deletion Requests.
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. |
In this request, the Data field contains the size of the package AID and the AID of the package to be deleted. TABLE 11-13 shows the format of the Delete Package request and the expected response.
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.
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 11-14 shows the format of the Delete Packages and Applets request and the expected response.
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.
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 11-15 shows the format of the Delete Applet request and the expected response.
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.
When the installer receives the request from the terminal, it can return any of the responses shown in TABLE 11-16.
The response has the format shown in TABLE 11-17.
The limits for the installer are as follows.
Copyright © 2005, Sun Microsystems, Inc. All Rights Reserved.