C H A P T E R 3 - Java Card Applet Lifetime

C H A P T E R 3

Java Card Applet Lifetime

For the purposes of this specification, applet refers to an applet written for the Java Card platform. An applet instance's lifetime begins when it is successfully registered with the Java Card RE via the Applet.register method. Applets registered with the Applet.register method exist until deleted by the Applet Deletion Manager (Section 11.3, The Applet Deletion Manager). The Java Card RE initiates interactions with the applet via the applet's public methods install, select, deselect, and process. An applet shall implement the static install(byte[], short, byte) method. If the install(byte[], short, byte) method is not implemented, the applet's objects cannot be created or initialized. A Java Card RE implementation shall call an applet's install, select, deselect, and process methods as described below.

When the applet is installed on the smart card, the static install(byte[], short, byte) method is called once by the Java Card RE for each applet instance created. The Java Card RE shall not call the applet's constructor directly.

3.1 `install` Method

When the install(byte[], short, byte) method is called, the applet instance does not yet exist. The main task of the install method within the applet is to create an instance of the Applet subclass using its constructor, and to register the instance. All other objects that the applet needs during its lifetime can be created as is feasible. Any other preparations necessary for the applet to be selected and accessed by a CAD also can be done as is feasible. The install method obtains initialization parameters from the contents of the incoming byte array parameter.

Typically, an applet creates various objects, initializes them with predefined values, sets some internal state variables, and calls either the Applet.register() method or the Applet.register(byte[], short, byte) method to specify the AID (applet IDentifier as defined in ISO 7816-5) to be used to select it. This installation is considered successful when the call to the Applet.register method completes without an exception. The installation is deemed unsuccessful if the install method does not call the Applet.register method, or if an exception is thrown from within the install method prior to the Applet.register method being called, or if the Applet.register method throws an exception. If the installation is unsuccessful, the Java Card RE shall perform all cleanup when it regains control. That is, all conditional updates to persistent storage shall be returned to the state they had prior to calling the install method. If the installation is successful, the Java Card RE can mark the applet as available for selection.

Only one applet instance can be successfully registered each time the Java Card RE calls the Applet.install method.

3.2 `select` Method

Applets remain in a suspended state until they are explicitly selected. Selection occurs when the Java Card RE receives a SELECT FILE APDU command in which the name data matches the AID of the applet. Applet selection can also occur on a MANAGE CHANNEL OPEN command. Selection causes an applet to become the currently selected applet. For more details, see Section 4.5, Applet Selection.

Prior to calling select, the Java Card RE shall deselect the previously selected applet. The Java Card RE indicates this to the applet by invoking the applet's deselect method or, if concurrently selected on more than one logical channel, its MultiSelectable.deselect method (for more details, see Section 4.2, Multiselectable Applets).

The Java Card RE informs the applet of selection by invoking its select method or, if being concurrently selected on more than one logical channel, its MultiSelectable.select method (for more details, see Section 4.2, Multiselectable Applets).

The applet may decline to be selected by returning false from the call to the select method or by throwing an exception. If the applet returns true, the actual SELECT FILE APDU command is supplied to the applet in the subsequent call to its process method, so that the applet can examine the APDU contents. The applet can process the SELECT FILE APDU command exactly like it processes any other APDU command. It can respond to the SELECT FILE APDU with data (see Section 3.3, process Method for details), or it can flag errors by throwing an ISOException with the appropriate returned status word. The status word and optional response data are returned to the CAD.

The Applet.selectingApplet method shall return true when called during the select method. The Applet.selectingApplet method continues to return true during the subsequent process method, which is called to process the SELECT FILE APDU command.

If the applet declines to be selected, the Java Card RE returns an APDU response status word of ISO7816.SW_APPLET_SELECT_FAILED to the CAD. Upon selection failure, the Java Card RE state is set to indicate that no applet is selected. See Section 4.5, Applet Selection for more details.

After successful selection, all subsequent APDUs directed to the assigned logical channel are delivered to the currently selected applet via the process method.

3.3 `process` Method

All APDUs are received by the Java Card RE and preprocessed. All commands, except for the MANAGE CHANNEL command result in an instance of the APDU class containing the command being passed to the process(APDU) method of the currently selected applet.

Note - A SELECT FILE APDU command might cause a change in the currently selected applet prior to the call to the process method. The actual change occurs before the call to the select method.

On normal return, the Java Card RE automatically appends 0x9000 as the completion response status word to any data already sent by the applet.

At any time during process, the applet may throw an ISOException with an appropriate status word, in which case the Java Card RE catches the exception and returns the status word to the CAD.

If any other exception is thrown during process, the Java Card RE catches the exception and returns the status word ISO7816.SW_UNKNOWN to the CAD.

3.4 `deselect` Method(s)

When the Java Card RE receives a SELECT FILE APDU command in which the name matches the AID of an applet, the Java Card RE calls the Applet.deselect method of the currently selected applet or, if concurrently selected on more than one logical channel, its MultiSelectable.deselect method. For more details see Section 4.2, Multiselectable Applets. Applet deselection may also be requested by the MANAGE CHANNEL CLOSE command. For more details, see Section 4.6, Applet Deselection.

The deselect method allows the applet to perform any cleanup operations that may be required to allow some other applet to execute.

The Applet.selectingApplet method shall return false when called during the deselect method. Exceptions thrown by the deselect method are caught by the Java Card RE, but the applet is deselected.

3.5 `uninstall` Method

This method is defined in the javacard.framework.AppletEvent interface. When the Java Card RE is preparing to delete the applet instance, the Java Card RE calls this method, if implemented by the applet, to inform it of the deletion request. Upon return from this method, the Java Card RE checks for reference dependencies before deleting the applet instance.

This method may be called multiple times, once for each applet deletion attempt.

3.6 Power Loss and Reset

Power loss occurs under one of the following conditions:

The card is withdrawn from the CAD.

When operating in contactless-only mode, the card loses carrier energy from the radio frequency (RF) field and enters the POWER OFF state as defined in the ISO 14443 Specification Parts 1-4.

When operating in contactless-only mode, the card receives a Supervisory block (S-block) DESELECT command and enters the HALT state as defined in the ISO 14443 Specification Parts 1-4.

A mechanical or electrical failure occurs on the card.

When power is reapplied to the card and on card reset (warm or cold) the Java Card RE shall ensure that:

Transient data is reset to the default value.

The transaction in progress, if any, when power was lost (or reset occurred) is aborted.

All applet instances that were active when power was lost (or reset occurred) become implicitly deselected. In this case the deselect method is not called.

If the Java Card RE implements default applet selection (see Section 4.1, Default Applets), the default applet is selected as the active applet instance for the basic logical channel (channel 0), and the default applet's select method is called. Otherwise, the Java Card RE sets its state to indicate that no applet is active on the basic logical channel.

3.6.1 Concurrent Operations Over Multiple Interfaces

A Java Card technology compliant proximity contactless card operates in the ACTIVE state and processes commands defined in the ISO 14443 Specification Parts 1-4.

The Supervisory block (S-block) DESELECT command results in the proximity card entering the HALT state.

A loss of RF field results in the proximity card entering the POWER OFF state.

On a card which is concurrently operating over both the contacted as well as the contactless I/O interfaces, prior to entering the HALT state or POWER OFF state, the Java Card RE must ensure the following:

The transaction in progress in the currently selected applet instance executing on a logical channel on the contactless I/O interface, if any, when the S-block DESELECT command is received, or when the loss of RF field occurs, is aborted.

Each applet instance that was active on a logical channel over the contactless I/O interface when the S-block DESELECT command is received, or when the loss of RF field occurs, becomes implicitly deselected. In this case the deselect method is not called.

All the logical channels open on the contactless I/O interface are implicitly closed.

Transient data associated with each applet instance that was active on a logical channel over the contactless I/O interface and that does not have an applet instance from the same package active on any logical channel over the contacted I/O interface when the S-block DESELECT command is received, or when the loss of RF field occurs, is reset to the default value.

Note - To establish a card session over both contacted and contactless interfaces concurrently, the CAD must initiate the contacted session first. A power loss or card reset on the contacted interface results in a card tear and card reset event even if a contactless session is in progress. An RF signal loss on the contactless interface must not affect an ongoing contacted session.

3.1 install Method

3.2 select Method

3.3 process Method

3.4 deselect Method(s)