| Java Card 3 Platform Runtime Environment Specification, Classic Edition Version 3.0.4 E18985-01 |
|
 Previous |
 Next |
| Java Card 3 Platform Runtime Environment Specification, Classic Edition Version 3.0.4 E18985-01 |
|
Previous |
Next |
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 3 Platform, Classic Edition is intended to give Java Card RE implementers as much freedom as possible in their implementations. However, some basic common specifications are required 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 to achieve interoperability across a wide range of possible Installer implementations.
The Applet Installer is an optional part of the Runtime Environment Specification, Java Card 3 Platform, Version 3.0.4, Classic Edition. 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, an Applet Deletion Manager that supports the behavior specified in this chapter is also required.
Section 11.1, "The Installer" describes CAP file loading and linking. For more information on CAP files, see the Virtual Machine Specification, Java Card 3 Platform, Version 3.0.4, Classic Edition. Section 11.2, "The Newly Installed Applet" describes applet installation. 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 for the following reasons:
Applet packages in ROM are preloaded and prelinked at card issuance, but instances of applets from these packages may be installed by the Installer 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 preloaded in ROM or downloaded and linked by the Installer during a card session. There are no applets to install within a library package.
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, as follows:
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. Response to incorrect APDUs include 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.
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.
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.
The Java Card specification does not specify any APDUs for the Installer. Java Card RE implementers are 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. For installation to succeed, this CAD installation program shall be able to do the following:
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 the following:
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, Java Card 3 Platform, Version 3.0.4, Classic Edition does not specify the details of the CAD installation program nor the APDUs passed between it and the Installer.
The Installer shall support the following CAP file versions:
Version 2.1 as specified in the Virtual Machine Specification, Java Card Platform, Version 2.1.1.
Version 2.2 as specified in the Virtual Machine Specification, Java Card 3 Platform, Version 3.0.4, Classic Edition.
Java Card RE implementers shall also define other behaviors of their Installer, including for the following:
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 in the following cases:
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 Chapter 6 of the Virtual Machine Specification, Java Card 3 Platform, Version 3.0.4, Classic Edition.
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, see Java Language Specification. Binary compatibility in Java Card technology is discussed in Chapter 2 of the Virtual Machine Specification, Java Card 3 Platform, Version 3.0.4, Classic Edition.
A class in the applet package is found to contain more package visible virtual methods or instance fields than the limitations enumerated in Chapter 2 of the Virtual Machine Specification, Java Card 3 Platform, Version 3.0.4, Classic Edition.
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, "install Method").
The applet's install method throws an exception before successful return from the Applet.register method (see Section 3.1, "install Method").
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.
Although an Installer may be implemented as an applet, an Installer typically requires 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 do the following tasks:
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.
A single interface exists between the Installer and the applet that is being installed. After the Installer correctly prepares 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. Array objects created in the <clinit> methods of the applet package may be owned by a never-to-exist applet instance or a not-yet-created applet instance within the same context.
The Installer shall not invoke the install(byte[], short, byte) method of a non-multiselectable 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 is 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.
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+3..offset+Li+Lc+La+2] = 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."
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, as follows:
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. Response to incorrect APDUs include 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 it is selected.
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.
A Java Card RE implementer could choose to implement the Applet Deletion Manager as an applet. If so, 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.
However, 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.
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.
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 do the following:
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 include the following:
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, Java Card 3 Platform, Version 3.0.4, Classic Edition does not specify the details of the CAD applet deletion program nor the APDUs passed between it and the Applet Deletion Manager.
Java Card RE implementers shall also define other behaviors of their Applet Deletion Manager, including the following:
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
The following three categories of applet deletion are required 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.
javacard.framework.AppletEvent.uninstallWhenever 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.2, "Applet Instance Deletion", Section 11.3.4.3, "Applet/Library Package Deletion", or Section 11.3.4.4, "Applet Package and Contained Instances Deletion", the Java Card RE shall do the following:
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.
The Java Card RE shall guarantee that applet instance deletion is not attempted and thereby deemed unsuccessful in the following cases:
An object owned by the applet instance is referenced from an object owned by another applet instance on the card.
An object owned by the applet instance is referenced from a static field on any package on the card.
The applet instance being deleted is active on the card.
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. 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 reuse.
The AID of the deleted applet instance may be reassigned to a new applet instance.
The Java Card RE shall guarantee that multiple applet instance deletion is not attempted, and thereby deemed unsuccessful in the following cases:
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.
An object owned by any of the applet instances being deleted is referenced from a static field on a package on the card.
Any of the applet instances being deleted is active on the card.
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. 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 reuse.
The AID of the deleted applet instances may be reassigned to new applet instances.
The Java Card RE shall guarantee that applet/library package deletion is not attempted and thereby deemed unsuccessful in the following cases:
A reachable (non-garbage) instance of a class belonging to the package being deleted exists on the card.
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, 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. 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 reinstall 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 reuse.
The Java Card RE shall guarantee that deletion of the applet package and contained instances is not attempted and thereby deemed unsuccessful in the following cases:
Another package on the card depends on this package (as expressed in the CAP file's import component).
An object owned by any of the applet instances being deleted is referenced from an object owned by an applet instance on the card that is not being deleted.
An object owned by any of the applet instances being deleted is referenced from a static field of a package that is not being deleted.
Any of the applet instances being deleted is active on the card.
Otherwise, if the applet package is resident in mutable memory, 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. 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 that depends on the deleted package. Additionally, it shall be possible to reinstall 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 reuse.
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 reuse.
The AID for the deleted applet instances may be reassigned to new applet instances.
Although an Applet Deletion Manager may be implemented as an applet, an Applet Deletion Manager typically requires 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 needs to do the following:
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.
|
 Copyright © 1998, 2011, Oracle and/or its affiliates. All rights reserved. Legal Notices |
|