Loading and Managing Applications
Description: This document describes how to use the development kit for the Java Card 3 Platform, Connected Edition, Version 3.0.2, to develop applet applications, web applications, servlets, and extended applets
Date: December 2009

C H A P T E R 8

Loading and Managing Applications

This chapter describes the use of the card installer in loading, creating, unloading, and deleting applications on a card. The card installer consists of two components, an on-card installer and an off-card Installer tool (Installer tool) provided by the development kit. The two installers work in conjunction to provide card application management functions.

See Chapter 3 to better understand the role and relationship between the Installer tool and the other development kit tools used in developing and deploying applications for the Java Card 3 platform.

This chapter consists of the following sections:

- Description of the On-Card Installer

- Description of the Installer Tool

- Card Installer Use Case

##

Description of the On-Card Installer

The on-card installer is a ROMized servlet responsible for handling requests received from the off-card installer, extracting the command and data, forwarding them to the card manager. Upon the return of the card manager, the installer forms the response to send back to the off-card installer.

### On-card Installer Operation

The on-card installer provides the interface between the Installer tool and the card manager and provides a request handling function for the card manager to perform card management tasks. The on-card installer assumes the `/cardmanager` context to represent the on-card card manager. All `/cardmanager/`command URIs (in which command represents load, create, delete, unload, or list) are mapped to one context `/cardmanager` assigned to the on-card installer.

The on-card installer parses and extracts the command, name, and data information in the multi-part POST requests. The information is passed on by calling the appropriate card manager’s API. The on-card installer and the filter are registered and started with the web container at card initialization.

### On-card Installer Functionality

The on-card installer provides the following functionality:

1. Handles requests received from the off-card installer.

These requests include the command for card application management and the data (application module JAR file).

2. Extracts data (JAR file) contained in the HTTP request and saves it to an on-card file.

3. Passes the `load`, `create`, `delete`, `unload`, or `list` command, parameters and the location of the saved JAR file to the Card Manager.

4. Handles the return from the Card Manager.

5. Builds the response content and sending the response back to the off-card installer.

6. Can be configured to require PIN authentication of the off-card installer via basic HTTP authentication:

- `load`, `create`, `delete`, or `unload` are protected with session-scoped authentication.

- `list` is protected with global card holder authentication.

- `load`, `create`, `delete`, or `unload` require card holder authorization.

##

Description of the Installer Tool

The Installer tool (off-card Installer) works on behalf of the on-card installer to perform various card management tasks, such as deploying an application and listing all applications. The communication between the Installer tool and on-card installer is proprietary. For the RI, HTTP POST is used as the communication protocol.

The following functions are performed by the Installer tool:

- Loads an application module onto the card.

- Creates an instance of an application.

- Deletes (deactivates) an instance of an application.

- Completely removes a module or application from the card.

- Displays information about loaded applications and instances.

### Running the Installer Tool From the Command Line

The Installer tool is a command-line tool, implemented using Java SE. The command line interface for the Installer tool has the following syntax:

    installer.bat subcommand [options] [arguments]

In the command line, the subcommand must be the first argument after the `installer.bat` command. Options and arguments can be in any order.

In the command line, subcommands and options can be specified in either a short form or a long form. The short form is a single character preceded by a hyphen (-). The long form uses a meaningful name preceded by two hyphens (--). Each subcommand can take one or more options or arguments that must follow the subcommand but can be in any order. For example, `-i` instance-name or
`--instance` instance-name.

Arguments are command line arguments that are not bound to an option. For example, an application or module file name used in the `load` command is an argument.

The following subcommands are available for the `installer.bat` command:

- `load Subcommand`

- `create Subcommand`

- `delete Subcommand`

- `unload Subcommand`

- `list Subcommand`

- `help Subcommand`

#### `load` Subcommand

Causes the Installer tool to load a specified application module or library file. The `load` subcommand can have one or more options and arguments.

##### `load` Subcommand Options

TABLE 8-1 lists and describes the available `load` subcommand options.

TABLE 8-1 `load` Options
Option | Description
--- | ---
`-c` oncardinstaller-url or `--cardmanager` oncardinstaller-url | Specifies the location of the on-card installer where oncardinstaller-url represents the complete URL of the on-card installer.
`-`C command-options-file or `--`commandoptionsfile command-options-file | Optional. Specifies a file containing command line options.
`-n` module-or-library-name or `--name` module-or-library-name | Specifies the name of the module or library on the card, where module-or-library-name represents the module or library name.
`-p` password or `--password` password | Optional. Used when authentication is required. Specifies the password for the user set by the `--user` or `-u` subcommand, where password represents the required user password.
`-s` signature-file or `--signature` signature-file | Specifies the name of the properties file that contains the BASE64 encoded certificate and signature, where signature-file represents the file name. This file is a simple properties file with properties: `signature=`base64-encoded-signature `certificate=`certificate-to-validate-the module-and-digest
`-t` file-type or `--type` file-type | Specifies the type of file being loaded, where file-type represents one of the following values: `web` `classic-applet` `extended-applet` `classic-lib` `extension-lib`
`-u` user-id or `--use`r user-id | Optional. Used when authentication is required to access the card manager. Specifies the user name, where user-id represents the user name.

##### `load` Subcommand Arguments

Command line arguments available for the `load` subcommand are the module or application group file name.

##### `load` Subcommand Format

The following is an example of the `load` subcommand format:

    installer.bat load -c oncardinstaller-url -s signature-file -t file-type \
    	-n module-or-library-name [-u user-id -p password] \
    	application-module (or library-file)

##### `load` Subcommand Example

In the following example, the Installer loads the file `Calculator.war` with the name `calc`.

    installer.bat load -c http://localhost:8019/cardmanager \
    	-s mysig.properties -n calc -t web Calculator.war

#### `create` Subcommand

Causes the Installer to create an instance of an application from a specified group with a specified context. The `create` subcommand can have one or more options but has no arguments.

##### `create` Subcommand Options

TABLE 8-2 lists and describes the available `create` subcommand options.

TABLE 8-2 `create` Options
Option | Description
--- | ---
`-a` applet-name-or-id (or) `--applet` applet-name-or-id | Specifies the name of the applet loaded by `load` command, where applet-name-or-id represents the applet name.
`-c` oncardinstaller-url or `--cardmanager` oncardinstaller-url | Specifies the location of the on-card installer, where oncardinstaller-url represents the complete URL.
`-`C command-options-file or `--`commandoptionsfile command-options-file | Optional. Specifies a file containing command line options.
`-d` install-parameters or `--data` install-parameters | Optional. Install parameters (printable hex string) that will be passed to the install method of a classic or extended applet.
`-i` name or `--instance` name | Specifies the name or ID of the instance, where name represents the name or ID. For web applications, a context name used to create the web application. If none is specified, then the default Web-Context-Path from JCRD is used.
`-n` module-or-library-name or `--name` module-or-library-name | Specifies the name of the module or library loaded by `load` command, where module-or-library-name represents the module or library name.
`-p` password or `--password` password | Optional. Used when authentication is required. Sets the password for the user specified by the `--user` or `-u` subcommand.
`-u` user-id or `--user` user-id | Optional. If authentication is required to access the card manager, specifies the authorized user, where user-id represents the required user name.

##### `create` Subcommand Arguments

There are no command line arguments for the `create` subcommand.

##### `create` Subcommand Format

The following is an example of the `create` subcommand format:

    installer.bat create -c oncardinstaller-url -n module-or-library-name \
    	[-a applet-name-or-id] [-d install-parameters] [-i name] \
    	[-u user-id -p password]

##### `create` Command Example 1

The following example assumes that a module was previously loaded and named `calc`. See load Subcommand Example. The Web-Context-Path in RD is `/Calculator`.

This example of the `create` command registers the web application with a web container using `/Calculator` as the context. Users access this web application by using `http://cardip:cardport/Calculator`.

    installer.bat create -c http://localhost:8019/cardmanager -n calc

##### `create` Command Example 2

Similar to Command Example 1, the following example assumes that a module was previously loaded and named `calc`, with the exception that instead of using the default `/Calculator`, the application is registered with a web-container using the context `/Mycalc`.

    installer.bat create -c http://localhost:8019/cardmanager -n calc \
    	-i /MyCalc

##### `create` Command Example 3

Similar to Command Example 2, the following example assumes that a module was previously loaded and named `calc`, with the exception that the application is registered as an applet instead of a web-container and has an instance ID of `/01`.

    installer.bat create -c http://localhost:8019/cardmanager -n calc \
    	-a //aid/A000000062/03010C0201 -d a000f0

#### `delete` Subcommand

Causes the installer to delete an instance that was created by the `create` subcommand. The `delete` subcommand can have one or more options but no arguments.

##### `delete` Subcommand Options

TABLE 8-3 lists and describes the available `delete` subcommand options.

TABLE 8-3 `delete` Options
Option | Description
--- | ---
`-c` oncardinstaller-url or `--cardmanager` oncardinstaller-url | Specifies the location of the on-card installer, where oncardinstaller-url represents the complete URL.
`-`C command-options-file or `--`commandoptionsfile command-options-file | Optional. Specifies a file containing command line options.
`-i` name or `--instance` name or `-i` name;name1;name2; ... or `--instance` name;name1;name2; ... | Specifies the instance of the application or multiple instances of applications to be deleted, where name represents the instance name of the application.
`-p` password or `--password` password | Optional. Used when authentication is required. Sets the password for the user specified by the `--user` or `-u` subcommand.
`-u` user-id or `--user` user-id | Optional. If authentication is required to access the card manager, specifies the authorized user, where user-id represents the required user name.

##### `delete` Subcommand Arguments

There are no command line arguments for the `delete` subcommand.

##### `delete` Subcommand Format

The following is an example of the `delete` subcommand format:

    installer.bat delete -c oncardinstaller-url -i name [-u user-id -p password]

##### `delete` Command Example

In the following example, the installer deletes the instance`/MyCalc.`

    installer.bat delete -c http://localhost:8019/cardmanager -i /MyCalc

#### `unload` Subcommand

Causes the installer to unload (remove) the specified module or application from the card including all instances created by the `create` command. The `delete` subcommand can have one or more options but no arguments.

##### `unload` Subcommand Options

TABLE 8-4 lists and describes the available `unload` subcommand options.

TABLE 8-4 `unload` Options
Option | Description
--- | ---
`-c` oncardinstaller-url or `--cardmanager` oncardinstaller-url | Specifies the location of the on-card installer, where oncardinstaller-url represents the complete URL.
`-`C command-options-file or `--`commandoptionsfile command-options-file | Optional. Specifies a file containing command line options.
`-n` module-or-library-name or `--name` module-or-library-name | Specifies the name of the module or library loaded by `load` command, where module-name represents the module or library name.
`-f` or `--force` | Optional. Forces an attempt to delete any instances before unloading.
`-p` password or `--password` password | Optional. Used when authentication is required. Sets the password for the user specified by the `--user` or `-u` subcommand.
`-u` user-id or `--user` user-id | Optional. If authentication is required to access the card manager, specifies the authorized user, where user-id represents the required user name.

##### `unload` Subcommand Arguments

There are no command line arguments for the `unload` subcommand.

##### `unload` Subcommand Format

The following is an example of the `unload` subcommand format:

    installer.bat unload -c oncardinstaller-url -n module-or-library-name [-f] \	[-u user-id -p password]

##### `unload` Command Example

In the following example, the installer completely removes the `calc` module and all of its instances.

    installer.bat unload -c http://localhost:8019/cardmanager -n calc

#### `list` Subcommand

Causes the installer to display summary or detailed information about loaded application modules, instances, and libraries.

##### `list` Subcommand Options

TABLE 8-5 lists and describes the available `list` subcommand options.

TABLE 8-5 `list` Options
Option | Description
--- | ---
`-c` oncardinstaller-url or `--cardmanager` oncardinstaller-url | Specifies the location of the on-card installer, where oncardinstaller-url represents the complete URL.
`-`C command-options-file or `--`commandoptionsfile command-options-file | Optional. Specifies a file containing command line options.
`-d` or `--detailed` | Optional. Displays complete details of the application-modules, instances, and libraries.
`-p` password or `--password` password | Optional. Used when authentication is required. Sets the password for the user specified by the `--user` or `-u` subcommand.
`-u` user-id or `--user` user-id | Optional. If authentication is required to access the card manager, specifies the authorized user, where user-id represents the required user name.

##### `list` Subcommand Arguments

There are no command line arguments for the `list` subcommand.

##### `list` Subcommand Format

The following is an example of the `list` subcommand format:

    installer.bat list -c oncardinstaller-url [-d] [-u user-id -p password]

##### `list` Command Example 1

In the following example, the installer displays summary information about modules, applications, and libraries.

    installer.bat list -c http://localhost:8019/cardmanager

##### `list` Command Example 2

In the following example, the installer displays detailed information about modules, applications, and libraries.

    installer.bat list -d -c http://localhost:8019/cardmanager

#### `help` Subcommand

Causes the installer to display summary or detailed information about one or more installer subcommands.

##### `help` Subcommand Options

There are no command line options for the `help` subcommand.

##### `help` Subcommand Arguments

Command line arguments for the `help` command are optional and consist of the name of the subcommand for which detailed help is requested.

##### `help` Subcommand Format

The following is an example of the `list` subcommand format:

    installer.bat help [subcommand]

##### `help` Command Example 1

In the following example, the installer displays summary help about all of its subcommands.

    installer.bat help

##### `help` Command Example 2

In the following example, the installer displays detailed help about the `load` subcommand.

    installer.bat help load

##

Card Installer Use Case

The following use case, Load an Application, illustrates a common use of the card installer.

### Load an Application

This use case loads an application module to the card.

#### Pre-Conditions

The following preconditions must be satisfied for this use case:

- A valid module file available (in this use case, `mymodule.war`).

- A signature details file containing Base64 encoded signature and certificate is available (in this use case, `sig.properties`).

- The on-card installer application must be accessible to the off-card installer client via an http connection (in this use case, `http://localhost:8019/cardmanager`).

#### Post-Conditions

The module is loaded and ready to be created.

#### Sequence of Events

1. The user executes the following command:

    installer.bat load -c http://localhost:8019/cardmanager \
    	-s sig.properties -n app1 -t web mymodule.war

2. The off-card installer connects to the on-card installer servlet and POSTs the required information.

3. A message is displayed on the console with the success information.

Copyright © 2009 Sun Microsystems, Inc. All rights reserved.