javax.microedition.jcrmi
Interface JavaCardRMIConnection

All Superinterfaces:

Connection

public interface JavaCardRMIConnection

extends Connection

This interface defines the Java Card RMI connection which can be used by J2ME applications to communicate with applications on a smart card using Java Card RMI protocol.

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 Connector.open method. For example, the connection string:

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

indicates that the connection is to be established with an application having the AID A0.0.0.67.4.7.1F.3.2C.3 and which resides in the smart card inserted in the default slot; that is, slot number 0. If the slot number is not specified, then the default slot is assumed.

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 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.

<JCRMI_connection_string>	::= "jcrmi:"< cardApplicationAddress>
<cardApplicationAddress>	::= [slot];<AID_string>
<slot>	::= smart card slot. (optional. Hexadecimal number identifying the smart card slot. Default slot assumed if left empty)
<AID_string>	::= "AID="<AID>
<AID>	::= <5 - 16 bytes> An AID (Application Identifier) uniquely identifies a smart card application. It is represented by 5 to 16 hexadecimal bytes where each byte value is seperated by a ".".

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).

Field Summary

static short

PINENTRY_CANCELLED This status is returned to the calling J2ME application if the operation for PIN verification/change/disable/ enable/unblock was not successful because the user cancelled the PIN entry request.

Method Summary

short	changePin(int pinID) A call to changePin method pops up a UI that requests the user for an old or existing PIN value and the new PIN value to change the value of the PIN.
short	disablePin(int pinID) A call to disablePin method pops up a UI that requests the user to enter the value for the PIN that is to be disabled.
short	enablePin(int pinID) A call to enablePin method pops up a UI that requests the user to enter the value for the PIN that is to be enabled.
short	enterPin(int pinID) A call to enterPin method pops up a UI that requests the PIN from the user.
Remote	getInitialReference() Returns the stub object for an initial remote reference.
short	unblockPin(int blockedPinID, int unblockingPinID) This is a high-level method that lets the J2ME application ask the user to enter the value for an unblocking PIN, and the new value for the blocked PIN and send these to the card.

Methods inherited from interface javax.microedition.io.Connection

close

Field Detail

PINENTRY_CANCELLED

public static final short PINENTRY_CANCELLED

This status is returned to the calling J2ME application if the operation for PIN verification/change/disable/ enable/unblock was not successful because the user cancelled the PIN entry request.

See Also:

Constant Field Values

Method Detail

getInitialReference

public Remote getInitialReference()

Returns the stub object for an initial remote reference.

Returns:

the initial remote reference

enterPin

public short enterPin(int pinID)
               throws RemoteException

A call to enterPin method pops up a UI that requests the PIN from the user. The pinID field indicates which PIN must be requested from the user. The user can either cancel the request or continue. If the user enters the PIN and chooses to continue, The implementation is responsible for presenting the PIN entered by the user to the card for verification. If padding is required for the PIN, the implementation is responsible for providing appropriate padding.

Parameters:

pinID - the type of PIN the implementation is suppose to prompt the user to enter.

Returns:

PINENTRY_CANCELLED if the user cancelled the PIN entry request or the value returned by the remote method.

Throws:

RemoteException - is thrown if the PIN could not be communicated to the card or an exception is thrown by the card in response to the PIN entry.

SecurityException - is thrown if the J2ME application does not have appropriate rights to ask for PIN verification.

UnsupportedOperationException - is thrown if the implementation does not support this method.

changePin

public short changePin(int pinID)
                throws RemoteException

A call to changePin method pops up a UI that requests the user for an old or existing PIN value and the new PIN value to change the value of the PIN. The pinID field indicates which PIN is to be changed. The user can either cancel the request or continue. If the user enters the PIN values and chooses to continue the implementation is responsible for presenting the old and new values of the PIN to the card. If padding is required for the PIN, the implementation is responsible for providing appropriate padding.

Parameters:

pinID - the type of PIN the implementation is suppose to prompt the user to change.

Returns:

PINENTRY_CANCELLED if the user cancelled the PIN entry request or the value returned by the remote method.

Throws:

RemoteException - is thrown if the PIN could not be communicated to the card or an exception is thrown by the card in response to the PIN entry.

SecurityException - is thrown if the J2ME application does not have appropriate rights to ask for changing the PIN value.

UnsupportedOperationException - is thrown if the implementation does not support this method.

disablePin

public short disablePin(int pinID)
                 throws RemoteException

A call to disablePin method pops up a UI that requests the user to enter the value for the PIN that is to be disabled. The pinID field indicates which PIN is to be disabled. The user can either cancel the request or continue. If the user enters the PIN and chooses to continue the implementation is responsible for presenting the PIN value to the card to disable PIN. If padding is required for the PIN, the implementation is responsible for providing appropriate padding.

Parameters:

pinID - the type of PIN the implementation is required to prompt the user to enter.

Returns:

PINENTRY_CANCELLED if the user cancelled the PIN entry request or the value returned by the remote method.

Throws:

RemoteException - is thrown if the PIN could not be communicated to the card or an exception is thrown by the card in response to the PIN entry.

SecurityException - is thrown if the J2ME application does not have appropriate rights to ask for disabling the PIN.

UnsupportedOperationException - is thrown if the implementation does not support this method.

enablePin

public short enablePin(int pinID)
                throws RemoteException

A call to enablePin method pops up a UI that requests the user to enter the value for the PIN that is to be enabled. The pinID field indicates which PIN is to be enabled. The user can either cancel the request or continue. If the user enters the PIN and chooses to continue the implementation is responsible for presenting the PIN value to the card for enabling the PIN. If padding is required for the PIN, the implementation is responsible for providing appropriate padding.

Parameters:

pinID - the type of PIN the implementation is required to prompt the user to enter.

Returns:

PINENTRY_CANCELLED if the user cancelled the PIN entry request or the value returned by the remote method.

Throws:

RemoteException - is thrown if the PIN could not be communicated to the card or an exception is thrown by the card in response to the PIN entry.

SecurityException - is thrown if the J2ME application does not have appropriate rights to ask for enabling the PIN.

UnsupportedOperationException - is thrown if the implementation does not support this method.

unblockPin

public short unblockPin(int blockedPinID,
                        int unblockingPinID)
                 throws RemoteException

This is a high-level method that lets the J2ME application ask the user to enter the value for an unblocking PIN, and the new value for the blocked PIN and send these to the card. A call to unblockPin method pops up a UI that requests the user to enter the value for the unblocking PIN and the new value for the blocked PIN. The unblockingPinID field indicates which unblocking PIN is to be used to unblock the blocked PIN which is indicated by the field blockedPinID. The user can either cancel the request or continue. If the user enters the PIN values and chooses to continue, the implementation is responsible for presenting the PIN values to the card for unblocking the blocked PIN. If padding is required for either of the PIN values, the implementation is responsible for providing appropriate padding.

Parameters:

blockedPinID - the ID of PIN that is to be unblocked.

unblockingPinID - the ID of unblocking PIN.

Returns:

PINENTRY_CANCELLED if the user cancelled the PIN entry request or the value returned by the remote method.

Throws:

RemoteException - is thrown if the PIN could not be communicated to the card or an exception is thrown by the card in response to the PIN entry.

SecurityException - is thrown if the J2ME application does not have appropriate rights to ask for unblocking the PIN.

UnsupportedOperationException - is thrown if the implementation does not support this method.