Contents Previous Next Index

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:

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:

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:

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:

11.1.5 Installer Behavior

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

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

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:

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:

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:

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:

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

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:

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:

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


Note – The applet deletion attempt may fail due to security considerations or resource limitations.

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:

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


Note – The applet deletion attempt may fail due to security considerations or resource limitations.

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:

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


Note – The package deletion attempt may fail due to security considerations or resource limitations.

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:

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


Note – The applet and package deletion attempt may fail due to security considerations or resource limitations.

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:

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.

1See Virtual Machine Specification for the Java Card™ Platform, Version 2.2.1.

 


Contents Previous Next Index Runtime Environment Specification for the Java Card Platform
Specification, 2.2.1