Chapter   11

Applet Installation and Deletion

Applet installation and deletion on smart cards using Java Card technology is a complex topic. The design of the Application Programming Interface for the Java Card™ Platform, Version 2.2.1 is intended to give Java Card RE implementers as much freedom as possible in their implementations. However, some basic common specifications are required in order to allow Java Card applets to be installed and deleted without knowing the implementation details of a particular installer or deletion manager.

This specification defines the concepts of an Installer and an Applet Deletion Manager, and specifies minimal requirements in order to achieve interoperability across a wide range of possible Installer implementations.

The Applet Installer is an optional part of the Runtime Environment Specification for the Java Card™ Platform, Version 2.2.1. That is, an implementation of the Java Card RE does not necessarily need to include a post-issuance Installer. However, if implemented, the installer is required to support the behavior specified in this chapter.

If the implementation of the Java Card RE includes a post-issuance Installer, then an Applet Deletion Manager which supports the behavior specified in this chapter is also required.

The sections - Section 11.1 "The Installer” and Section 11.2 "The Newly Installed Applet” describe CAP file1 loading and linking, and applet installation respectively. Even though the loading, and linking operations are described together with the installation operations, there is no requirement that they be performed together during the same card session:

Applet packages in ROM are pre-loaded and pre-linked at card issuance, but instances of applets from these packages may be installed by the Installer during during a card session.
Applet packages may be downloaded and linked by the Installer during one card session, but applet instances from these packages may be installed by the Installer during a different card session.
Library packages may be pre-loaded in ROM or downloaded and linked by the Installer during a card session. There are no applets to install within a library package.

11.1 The Installer

The mechanisms necessary to install an applet on smart cards using Java Card technology are embodied in an on-card component called the Installer.

To the CAD the Installer appears to be an applet. It has an AID, and it becomes the currently selected applet when this AID is successfully processed by a SELECT FILE command. Once selected on a logical channel, the Installer behaves in much the same way as any other applet:

It receives all APDUs dispatched to this logical channel just like any other active applet.
Its design specification prescribes the various kinds and formats of APDUs that it expects to receive along with the semantics of those commands under various preconditions.
It processes and responds to all APDUs that it receives. Incorrect APDUs are responded to with an error condition of some kind.
When another applet is selected on this logical channel(or when the card is reset or when power is removed from the card), the Installer becomes deselected and remains suspended until the next time that it is selected.

11.1.1 Installer Implementation

The Installer need not be implemented as an applet on the card. The requirement is only that the Installer functionality be SELECTable. The corollary to this requirement is that Installer component shall not be able to be invoked on a logical channel on which a non-Installer applet is an active applet instance nor when no applet is active.

Obviously, a Java Card RE implementer could choose to implement the Installer as an applet. If so, then the Installer might be coded to extend the Applet class and respond to invocations of the select, process, and deselect methods; and, if necessary, the methods of the javacard.framework.MultiSelectable interface.

But a Java Card RE implementer could also implement the Installer in other ways, as long as it provides the SELECTable behavior to the outside world. In this case, the Java Card RE implementer has the freedom to provide some other mechanism by which APDUs are delivered to the Installer code module.

11.1.2 Installer AID

Because the Installer is SELECTable, it shall have an AID. Java Card RE implementers are free to choose their own AIDs by which their Installer is selected. Multiple installers may be implemented.

11.1.3 Installer APDUs

The Java Card specification does not specify any APDUs for the Installer. Java Card RE implementers are entirely free to choose their own APDU commands to direct their Installer in its work.

The model is that the Installer on the card is initiated by an installation program running on the CAD. In order for installation to succeed, this CAD installation program shall be able to:

Recognize the card.
SELECT FILE the Installer on the card.
Coordinate the installation process by sending the appropriate APDUs to the card Installer. These APDUs will include:

Authentication information, to ensure that the installation is authorized.
The applet code to be loaded into the card’s memory.
Linkage information to link the applet code with code already on the card.
Instance initialization parameter data to be sent to the applet’s install method.

The Application Programming Interface for the Java Card™ Platform, Version 2.2.1 does not specify the details of the CAD installation program nor the APDUs passed between it and the Installer.

11.1.4 CAP File Versions

The Installer shall support the following CAP file versions:

Version 2.1 as specified in the Java Card‘ 2.1.1 Virtual Machine Specification.
Version 2.2 as specified in the Java Card‘ 2.2 Virtual Machine Specification.

11.1.5 Installer Behavior

Java Card RE implementers shall also define other behaviors of their Installer, including:

Whether or not installation can be aborted and how this is done.
What happens if an exception, reset, or power fail occurs during installation.
What happens if another applet is selected before the Installer is finished with its work.

The Java Card RE shall guarantee that an applet will not be deemed successfully installed if:

the applet package as identified by the package AID is already resident on the card.
the applet package contains an applet with the same Java Card platform name as that of another applet already resident on the card. The Java Card platform name of an applet identified by the AID item is described in section 6.5 of the Virtual Machine Specification for the Java Card™ Platform, Version 2.2.1.
the applet package requires more memory than is available on the card.
the applet package references a package that is not resident on the card.
the applet package references another package already resident on the card, but the version of the resident package is not binary compatible with the applet package. For more information on binary compatibility in the Java programming language please see the Java™ Language Specification. Binary compatibility in Java Card technology is discussed in the Virtual Machine Specification for the Java Card™ Platform, Version 2.2.1.
a class in the applet package is found to contain more package visible virtual methods or instance fields than the limitations enumerated in section 2.2.4.3 of the Virtual Machine Specification for the Java Card™ Platform, Version 2.2.1.
a reset or power fail occurs while executing the applet’s install method and before successful return from the Applet.register method (see Section 3.1).
the applet’s install method throws an exception before successful return from the Applet.register method (see Section 3.1).

When applet installation is unsuccessful, the Java Card RE shall guarantee that objects created during the execution of the install method, or by the Java Card RE on its behalf—initialized static arrays—can never be accessed by any applet on the card. In particular, any reference in CLEAR_ON_RESET transient space to an object created during an unsuccessful applet installation must be reset as a null reference.

11.1.6 Installer Privileges

Although an Installer may be implemented as an applet, an Installer will typically require access to features that are not available to “other” applets. For example, depending on the Java Card RE implementer’s implementation, the Installer will need to:

Read and write directly to memory, bypassing the object system and/or standard security.
Access objects owned by other applets or by the Java Card RE.
Invoke non-entry point methods of the Java Card RE.
Be able to invoke the install method of a newly installed applet.

Again, it is up to each Java Card RE implementer to determine the Installer implementation and supply such features in their Java Card RE implementations as necessary to support their Installer. Java Card RE implementers are also responsible for the security of such features, so that they are not available to normal applets.

11.2 The Newly Installed Applet

There is a single interface between the Installer and the applet that is being installed. After the Installer has correctly prepared the applet for execution (performed steps such as loading and linking), the Installer shall invoke the applet’s install method. This method is defined in the Applet class.

The precise mechanism by which an applet’s install(byte[], short, byte) method is invoked from the Installer is a Java Card RE implementer-defined implementation detail. However, there shall be a context switch so that any context-related operations performed by the install method (such as creating new objects) are done in the context of the new applet and not in the context of the Installer. The Installer shall also ensure that array objects created in the class initialization (<clinit>) methods of the applet package are also owned by the context of the new applet.

The Installer shall not invoke the install(byte[], short, byte) method of an applet if another applet from the same package is active on the card. The applet instantiation shall be deemed unsuccessful.

The Installer shall ensure that during the execution of the install() method, the new applet (not the Installer) is the currently selected applet. In addition, any CLEAR_ON_DESELECT objects created during the install() method shall be associated with the selection context of the new applet.

The installation of an applet is deemed complete if all steps are completed without failure or an exception being thrown, up to and including successful return from executing the Applet.register method. At that point, the installed applet will be selectable.

The maximum size of the parameter data is 127 bytes. The bArray parameter is a global array (install(byte[] bArray, short bOffset, byte bLength)), and for security reasons is zeroed after the return from the install method, just as the APDU buffer is zeroed on return from an applet’s process method.

11.2.1 Installation Parameters

The format of the input data passed to the target applet’s install method in the bArray parameter is as follows:

bArray[offset] = length(Li) of instance AID 
bArray[offset+1..offset+Li] = instance AID bytes (5-16 bytes) 
bArray[offset+Li+1]= length(Lc) of control info 
bArray[offset+Li+2..offset+Li+Lc+1] = control info 
bArray[offset+Li+Lc+2] = length(La) of applet data 
bArray[offset+Li+Lc+2..offset+Li+Lc+La+1] = applet data 

Any of the length items: Li, Lc, La may be zero. If length Li is non-zero, the instance AID bytes item is the proposed AID of the applet instance.

The control info item of the parameter data is implementation dependent and is specified by the Installer.

Other than the need for the entire parameter data to not be greater than 127 bytes, the Java Card API does not specify anything about the contents of the applet data item of the global byte array installation parameter. This is fully defined by the applet designer and can be in any format desired. In addition, the applet data portion is intended to be opaque to the Installer.

Java Card RE implementers should design their Installers so that it is possible for an installation program running in a CAD to specify the applet data delivered to the Installer. The Installer simply forwards this along with the other items in the format defined above to the target applet’s install method in the bArray parameter. A typical implementation might define a Java Card RE implementer-proprietary APDU command that has the semantics “call the applet’s install method passing the contents of the accompanying applet data.”

11.3 The Applet Deletion Manager

The mechanisms necessary to delete an applet on smart cards using Java Card technology are embodied in an on-card component called the Applet Deletion Manager.

To the CAD, the Applet Deletion Manager appears to be an applet, and may be one and the same as the Applet Installer. It has an AID, and it becomes the currently selected applet instance when this AID is successfully processed by a SELECT FILE command. Once selected on a logical channel, the Applet Deletion Manager behaves in much the same way as any other applet:

It receives all APDUs dispatched to this logical channel, just like any other active applet.
Its design specification prescribes the various kinds and formats of APDUs that it expects to receive, along with the semantics of those commands under various preconditions.
It processes and responds to all APDUs that it receives. Incorrect APDUs are responded to with an error condition of some kind.
When another applet is selected on this logical channel (or when the card is reset or when power is removed from the card), the Applet Deletion Manager becomes deselected and remains suspended until the next time that it is selected.

11.3.1 Applet Deletion Manager Implementation

The Applet Deletion Manager need not be implemented as an applet on the card. The requirement is only that the Applet Deletion Manager functionality be SELECTable. The corollary to this requirement is that Applet Deletion Manager component shall not be able to be invoked on a logical channel where a non-Applet Deletion Manager applet is an active applet instance, nor when no applet is active.

Obviously, a Java Card RE implementer could choose to implement the Applet Deletion Manager as an applet. If so, then the Applet Deletion Manager might be coded to extend the Applet class and to respond to invocations of the select, process, and deselect methods, and if necessary the methods of the javacard.framework.MultiSelectable interface.

But a Java Card RE implementer could also implement the Applet Deletion Manager in other ways, as long as it provides the SELECTable behavior to the outside world. In this case, the Java Card RE implementer has the freedom to provide some other mechanism by which APDUs are delivered to the Applet Deletion Manager code module.

11.3.2 Applet Deletion Manager AID

Because the Applet Deletion Manager is SELECTable, it shall have an AID which may be the same as that of the Applet Installer. Java Card RE implementers are free to choose their own AIDs by which their Applet Deletion Manager is selected. Multiple Applet Deletion Managers may be implemented.

11.3.3 Applet Deletion Manager APDUs

The Java Card API does not specify any APDUs for the Applet Deletion Manager. Java Card RE implementers are entirely free to choose their own APDU commands to direct their Applet Deletion Manager in its work.

The model is that the Applet Deletion Manager on the card is initiated by an applet deletion program running on the CAD. In order for applet deletion to succeed, this CAD applet deletion program shall be able to:

Recognize the card.
SELECT FILE the Applet Deletion Manager on the card.
Coordinate the applet deletion process by sending the appropriate APDUs to the card Applet Deletion Manager. These APDUs will include:

Authentication information, to ensure that the applet deletion is authorized.
Identify the applet(s) code or instance to be deleted from the card’s memory.

The Application Programming Interface for the Java Card™ Platform, Version 2.2.1 does not specify the details of the CAD applet deletion program nor the APDUs passed between it and the Applet Deletion Manager.

11.3.4 Applet Deletion Manager Behavior

Java Card RE implementers shall also define other behaviors of their Applet Deletion Manager, including:

Whether or not applet deletion can be aborted and how this is done.
What happens if an exception, reset, or power fail occurs during applet deletion.
What happens if another applet is selected before the Applet Deletion Manager is finished with its work.

There are three categories of applet deletion requirements on the card:

Applet instance deletion involves the removal of the applet object instance and the objects owned by the applet instance and associated Java Card RE structures.
Applet/library package deletion involves the removal of all the card resident components of the CAP file, including code and any associated Java Card RE management structures.
Deletion of the applet package and the contained applet instances involves the removal of the card-resident code and Java Card RE structures associated with the applet package, and all the applet instances and objects in the context of the package and associated Java Card RE structures.

Invocation of the javacard.framework.AppletEvent.uninstall method

Whenever one or more applet instances is being deleted, the Applet Deletion Manager shall inform each of the applets of potential deletion by invoking, if implemented, the applet's uninstall method. When multiple applet instances are being deleted, the order of invocation of the uninstall methods is unspecified. Prior to following the stepwise sequence described in Section 11.3.4.1, Section 11.3.4.2, or Section 11.3.4.3, the Java Card RE shall:

perform any security and authorization checks required for the deletion of each of the applet instances to be deleted. If the checks fail, an error is returned and the applet deletion fails.
otherwise, check if an applet instance, belonging to the contexts of the applet instances being deleted, is active on the card. If so, an error is returned and the applet instance deletion fails.
otherwise, perform the following steps for each of the applet instances to be deleted :

if the applet instance being deleted implements the AppletEvent interface, set the currently selected applet to that of the applet instance and invoke the uninstall method of the applet instance.
A context switch into the context of the applet instance occurs upon invocation.
if an uncaught exception is thrown during the execution of the uninstall method, it is caught and ignored.

11.3.4.1 Applet Instance Deletion

The Java Card RE shall guarantee that applet instance deletion will not be attempted and thereby deemed unsuccessful if:

any object owned by the applet instance is referenced from an object owned by another applet instance on the card, or
any object owned by the applet instance is referenced from a static field on any package on the card, or
an applet instance, belonging to the context of the applet instance being deleted, is active on the card.

Otherwise, the Java Card RE shall delete the applet instance.

The applet instance deletion operation must be atomic. If a reset or power fail occurs during the deletion process, it must result in either an unsuccessful applet instance deletion or a successfully completed applet instance deletion before any applet is selected on the card.

Following an unsuccessful applet instance deletion, the applet instance shall be selectable, and all objects owned by the applet shall remain unchanged. In other words, the functionality of all applet instances on the card remains the same as prior to the unsuccessful attempt.

Following a successful applet instance deletion, it shall not be possible to select that applet, and no object owned by the applet can be accessed by any applet currently on the card or by a new applet created in the future.

The resources used by the applet instance may be recovered for re-use.

The AID of the deleted applet instance may be re-assigned to a new applet instance.

Multiple Applet Instance Deletion

The Java Card RE shall guarantee that multiple applet instance deletion will not be attempted, and thereby deemed unsuccessful if:

an object owned by any of the applet instances being deleted is referenced from an object owned by an applet instance on the card which is not being deleted, or
an object owned by any of the applet instances being deleted is referenced from a static field on any package on the card, or
an applet instance, belonging to the contexts of any of the applet instances being deleted is active on the card.

Otherwise, the Java Card RE shall delete the applet instances.

The multiple applet instance deletion operation must be atomic. If a reset or power fail occurs during the deletion process, it must result in either an unsuccessful multiple applet instance deletion or a successfully completed multiple applet instance deletion before any applet is selected on the card.

Following an unsuccessful multiple applet instance deletion, all applet instances shall be selectable, and all objects owned by the applets shall remain unchanged. In other words, the functionality of all applet instances on the card remains the same as prior to the unsuccessful attempt.

Following a successful multiple applet instance deletion, it shall not be possible to select any of the deleted applets, and no object owned by the deleted applets can be accessed by any applet currently on the card or by a new applet created in the future.

The resources used by the applet instances may be recovered for re-use.

The AID of the deleted applet instances may be re-assigned to new applet instances.

11.3.4.2 Applet/Library Package deletion

The Java Card RE shall guarantee that applet/library package deletion will not be attempted and thereby deemed unsuccessful if:

a reachable (non-garbage) instance of a class belonging to the package being deleted exists on the card, or
another package on the card depends on this package (as expressed in the CAP file’s import component).

Otherwise, if the applet/library package is resident in mutable memory, then the Java Card RE shall delete the applet/library package.

The applet/library package deletion operation must be atomic. If a reset or power fail occurs during the deletion process, it must result in either an unsuccessful applet/library package deletion or a successfully completed applet/library package deletion before any applet is selected on the card.

Following an unsuccessful applet/library package deletion, any object or package that depends on the package continues to function unaffected. In other words, the functionality of all applets on the card remains the same as prior to the unsuccessful attempt.

Following a successful applet/library package deletion, it shall not be possible to install another package which depends on the deleted package. Additionally, it shall be possible to re-install the same package (with exactly the same package AID) or an upgraded version of the deleted package onto the card.

The resources used by the applet/library package may be recovered for re-use.

11.3.4.3 Deletion of Applet Package and Contained Instances

The Java Card RE shall guarantee that deletion of the applet package and contained instances will not be attempted and thereby deemed unsuccessful if:

another package on the card depends on this package (as expressed in the CAP file’s import component), or
an object owned by any of the applet instances being deleted is referenced from an object owned by an applet instance on the card which is not being deleted, or
an object owned by any of the applet instances being deleted is referenced from a static field of a package which is not being deleted, or
an applet instance, belonging to the contexts of any of the applet instances being deleted, is active on the card.

Otherwise, if the applet package is resident in mutable memory, then the Java Card RE shall delete the applet package and contained instances.

The deletion of applet package and contained instances operation must be atomic. If a reset or power fail occurs during the deletion process, it must result in either an unsuccessful deletion of the applet package and contained instances or a successfully completed deletion of the applet package and contained instances before any applet is selected on the card.

Following an unsuccessful deletion of the applet package and contained instances, any object or package that depends on the package continues to function unaffected. In other words, the functionality of all applets on the card remains the same as prior to the unsuccessful attempt.

Following a successful deletion of the applet package and contained instances, it shall not be possible to install another package which depends on the deleted package. Additionally, it shall be possible to re-install the same package (with exactly the same package AID) or an upgraded version of the deleted package onto the card.

The resources used by the applet package may be recovered for re-use.

Following a successful deletion of the applet package and contained instances, it shall not be possible to select any of the deleted applets, and no object owned by the deleted applets can be accessed by any applet currently on the card or by a new applet created in the future.

The resources used by the applet instances may be recovered for re-use.

The AID for the deleted applet instances may be re-assigned to new applet instances.

11.3.5 Applet Deletion Manager Privileges

Although an Applet Deletion Manager may be implemented as an applet, an Applet Deletion Manager will typically require access to features that are not available to “other” applets. For example, depending on the Java Card RE implementer’s implementation, the Applet Deletion Manager will need to:

Read and write directly to memory, bypassing the object system and/or standard security.
Access objects owned by other applets or by the Java Card RE.
Invoke non-entry point methods of the Java Card RE.

Again, it is up to each Java Card RE implementer to determine the Applet Deletion Manager implementation and supply such features in their Java Card RE implementations as necessary to support their Applet Deletion Manager. Java Card RE implementers are also responsible for the security of such features, so that they are not available to normal applets.

Runtime Environment Specification for the Java Card Platform Specification, 2.2.1

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