Loading and Managing Applications

C H A P T E R 8

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, that 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

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 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 is the list of functionalities required 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

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 is a list of the available subcommands for the installer.bat command:

`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.


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.
`-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.


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.
`-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 -i /01

`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.


Option	Description
`-c` oncardinstaller-url or `--cardmanager` oncardinstaller-url	Specifies the location of the on-card installer, where oncardinstaller-url represents the complete URL.
`-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.


Option	Description
`-c` oncardinstaller-url or `--cardmanager` oncardinstaller-url	Specifies the location of the on-card installer, where oncardinstaller-url represents the complete URL.
`-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.


Option	Description
`-c` oncardinstaller-url or `--cardmanager` oncardinstaller-url	Specifies the location of the on-card installer, where oncardinstaller-url represents the complete URL.
`-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 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.

Description of the On-Card Installer

On-card Installer Operation

On-card Installer Functionality

Description of the Installer Tool

Running the Installer Tool

load Subcommand

load Subcommand Options

load Subcommand Arguments

load Subcommand Format

load Subcommand Example

create Subcommand

create Subcommand Options

create Subcommand Arguments

create Subcommand Format

create Command Example 1

create Command Example 2

create Command Example 3

delete Subcommand

delete Subcommand Options

delete Subcommand Arguments

delete Subcommand Format

delete Command Example

unload Subcommand

unload Subcommand Options

unload Subcommand Arguments

unload Subcommand Format

unload Command Example

list Subcommand

list Subcommand Options

list Subcommand Arguments

list Subcommand Format

list Command Example 1

list Command Example 2

help Subcommand

help Subcommand Options

help Subcommand Arguments

help Subcommand Format

help Command Example 1

help Command Example 2