JavaCardRMIConnection

Creating a Java Card RMI Connection

Java Card RMI connection is created by passing a generic connection URI string with a card application identifier (AID) and optionally the slot in which the card is inserted, to the {@link javax.microedition.io.Connector#open Connector.open} method. For example, the connection string:

jcrmi:0;AID=A0.0.0.67.4.7.1F.3.2C.3

Each Java Card RMI connection has a logical channel reserved exclusively for it. That is, the channel is dedicated to the J2ME application and the selected smart card application until the connection is closed. A smart card supporting logical channels allows the host device to open multiple logical channels to communicate with on-card applications. Logical channel other than the basic channel must be closed when corresponding connection is closed. Basic channel or channel 0 must remain open while the card is powered on.

Since the basic channel or channel 0 cannot be closed, the implementation should maintain its availability status. When a J2ME application asks for a new connection, the implementation would find out if channel 0 is in use by any application (native or J2ME application). If channel 0 is not in use, the implementation would acquire the channel 0 for communicating with the card application by setting the state of channel 0 to "IN USE". It would then select the desired application on channel 0. If the selection is successful, the newly created connection object would be returned to the J2ME application which can then use it to communicate with the card application. If the card application selection fails or the J2ME application calls close on the connection object, the availability state of the basic channel will be set back to "AVAILABLE" meaning that the basic channel is available for use.

When a J2ME application requests a connection to the card and channel 0 is in use by some other application (native or J2ME application), the implementation sends a MANAGE CHANNEL command to the card requesting a logical channel for the new connection. If there is a logical channel available, the card returns with the logical channel number which will be used by the new connection. The implementation would select the desired application on the newly allocated logical channel. If the selection is successful, the implementation returns the newly created connection object to the J2ME application which can then use it for communicating with the card application. If application selection fails or the J2ME application calls close() method to close the connection with the card application, the implementation will send a MANAGE CHANNEL command to the card to close the channel. The channel will then be available for use by other applications.

In the case when there are no logical channels available or the card does not support logical channels, the card will return an error. An IOException will be thrown and no connection object will be returned to the J2ME application.

Invoking Methods on Remote Objects in Java Card

Once the Java Card RMI connection is created, the J2ME application can obtain an initial remote reference object using {@link #getInitialReference() getInitialReference}. Using this reference, the application can invoke methods of an initial remote object on the card and obtain other references to remote objects.

Communicating With Multiple Smart Card Applications

A J2ME application may connect and communicate with multiple smart card applications interchangeably. To achieve this the J2ME application can repeat the procedure mentioned above to create corresponding connection objects.

Closing a JavaCardRMIConnection

A J2ME application can call javax.microedition.io.Connection.close() on the connection object to terminate the connection and release the logical channel. The logical channel is free to be used by other applications. If an application terminates without closing an open connection, the implementation SHOULD perform the close operation automatically.

Exceptions that can be Thrown During Connection Establishment

If the card slot does not exist, or if the card is not inserted or powered on, or if application selection is failed a ConnectionNotFoundException must be thrown.

If the J2ME application is not allowed to access the application with the specified application identifier a SecurityException is thrown.

If there is no logical channel available to establish a connection, an IOException must be thrown.

If initial remote reference object can not be created a RemoteException must be thrown.

If a card is removed after the connection is established and then re-inserted, the J2ME application must re-establish the connection and get a new connection object. Any attempts to invoke remote method using the connection object created before removal of the card will result in RemoteException being thrown.

BNF Format for Connector.open() string

The URI MUST conform to the BNF syntax specified below. If the URI does not conform to this syntax, an IllegalArgumentException is thrown.

Smart Card Slot Discovery Mechanism

J2ME devices may support a variable number of security elements (usually smart card slots). Some security elements are permanently attached to the device (e.g. a soldered chip), others are removable. The removable security elements may be cold-swappable, requiring the battery to be removed before the security element can be exchanged (e.g. a MiniSIM slot hidden behind the battery). Other removable security elements can be inserted and removed while the system is running. (e.g. a hot-swappable smart card reader).

A system property is defined to indicate the names of the smart card slots. The property can be queried through the System.getProperty() method using the key microedition.smartcardslots. The value returned is a comma-separated list of the smart card slots which can be used in the Connector.open() string to identify the specific smart card slot.

If the platform includes a (U)SIM card, it MUST be in slot 0.

The logical slot names include the slot number and a descriptor indicating the type of the slot. For cold-swappable slots the letter 'C' is appended to the slot number. For hot-swappable slots the letter 'H' is appended to the slot number. The slot descriptors (the letter 'C' and 'H' appended to the slot number) cannot be passed as part of the URI to open a connection to the smart card application. The J2ME application MUST remove the descriptor from the logical slot name and only use the slot number in URI to identify the specific smart card slot.

A typical configuration for a cold-swappable SIM card and a hot-swappable removable card would be:

 
 microedition.smartcardslots: 0C,1H

Example

The following example shows how a JavaCardRMIConnection can be used to access a smart card application.

try {
JavaCardRMIConnection connection = (JavaCardRMIConnection)
Connector.open("jcrmi:0;AID=A0.0.0.67.4.7.1F.3.2C.3");

Counter counter = (Counter) connection.getInitialReference();
...
currentValue = counter.add(50);
...
connection.close();
} catch (Exception e) {
...
}

Note regarding PIN-related methods

A platform should implement the PIN entry UI in such a way that:

• the UI is distinguishable from a UI generated by external sources (for example J2ME applications)
• external sources are not able to retrieve or insert PIN data
• If the static access control mechanism is implemented, the PIN related methods MUST be implemented as specified in the static access control mechanism. For further details see Appendix A (Recommended Security Element Access Control).