Chapter   8

Remote Method Invocation Service

Java Card platform Remote Method Invocation (“Java Card RMI”) is a subset of the Java Remote Method Invocation (RMI) system. It provides a mechanism for a client application running on the CAD platform to invoke a method on a remote object on the card. The on-card transport layer for Java Card RMI is provided in the package javacard.framework.service by the class RMIService. It is designed as a service requested by the Java Card RMI-based applet when it is the currently selected applet.

The Java Card RMI message is encapsulated within the APDU object passed into the RMIService methods.

8.1 Java Card RMI

This section defines the subset of the RMI system that is supported by Java Card RMI.

8.1.1 Remote Objects

A remote object is one whose remote methods can be invoked remotely from the CAD client. A remote object is described by one or more remote interfaces. A remote interface is an interface which extends, directly or indirectly, the interface java.rmi.Remote. The methods of a remote interface are referred to as remote methods. A remote method declaration includes the exception java.rmi.RemoteException (or one of its superclasses such as java.io.IOException or java.lang.Exception) in its throws clause. Additionally, in the remote method declaration, a remote object declared as the return value must be declared as the remote interface, not the implementation class of that interface.

Java Card RMI imposes additional constraints on the definition of remote methods. These constraints are a result of the Java Card platform language subset and other feature limitations.

8.1.1.1 Parameters and Return Values

The parameters of a remote method must only include parameters of the following types:

any supported primitive data types.
any single-dimension array of a supported primitive data type.

The return value of a remote method must only be one of the following types:

any supported primitive data type.
any single-dimension array type of a supported primitive data type.
any remote interface type
a void return

All parameters including array parameters are always transmitted by value during the remote method invocation. The return values from a remote method are transmitted by value for primitive types and arrays; return values that are remote object references are transmitted by reference using a remote object reference descriptor.

8.1.1.2 Exceptions

Java Card RMI uses the following simplified model for returning exceptions thrown by remote methods:

When an exception defined in the Java Card API is thrown by a remote method the exact exception type and the embedded reason code is transmitted back to the client application. In essence, the exception object is transmitted by value.
When an exception not defined in the Java Card API is thrown by a remote method, the “closest” superclass exception type from the API and the embedded reason code is transmitted back to the client application. In this case, the “closest” API defined superclass exception object is transmitted by value. The client application can distinguish an inexact exception from an exact one.

8.1.1.3 Functional Limitations

The definition of the supported subset of Java Card RMI for Java Card platform version 2.2.1 implies functional limitations during the execution of Java Card API remote methods:

CAD client application remote objects cannot be passed as arguments to remote methods.
Card remote objects cannot be passed as arguments to remote methods.
Applets on the card cannot invoke remote methods on the CAD client.
Method argument data and return values, along with the Java Card RMI protocol overhead must fit within the size constraints of an APDU command and APDU response respectively.

8.2 The RMI Messages

The Java Card RMI message protocol consists of two commands that are used to:

get the initial remote object reference for the Java Card RMI based applet. The initial remote object reference is the seed remote object which the CAD client application needs to begin remote method invocations.
send a remote method invocation request to the card.

To ensure that the protocol is compatible with all applications, the SELECT FILE command is used for getting the initial reference. The response to the SELECT FILE command allows the remote method invocation command itself to be customized by the applet.

8.2.1 Applet Selection

The selection command used to retrieve the initial reference is the ISO7816-4 Select File command, with the following options in the header:

Direct selection by DF Name: that is, selection by AID—This is the normal option used to select all applet instances in the Java Card platform.
Return FCI (File Control Information - ISO7816-4), optional template—This is an additional option that indicates that the applet is expected to return FCI information.

In addition, an alternate RFU variant of the Return FCI option is required to configure the RMIService for an alternate Java Card RMI protocol format. (For more details see Section 8.4.1 "SELECT FILE Command.”)

The answer to this command is a constructed TLV(tag-length-value) data structure (ISO 7816-6) that includes the following information:

The byte to be used as instruction byte (INS) for subsequent invocation commands.
The initial remote object reference descriptor. The descriptor includes the remote object identifier and information to identify the associated class.

8.2.2 Method Invocation

In order to request a method invocation, the CAD client provides the following information:

The remote object identifier—This identifier is used to uniquely identify the object on the card.
The invoked method identifier—A designator to uniquely identify the remote method within the remote object class or superclass.
The values of the arguments—These values are raw values for primitive data types, and for arrays, a length followed by the values.

The response to the invocation request may include one of the following items:

A primitive return value—This is a raw primitive data type value.
An array of primitive components—This is a length followed by the raw primitive data type values.
A remote object reference descriptor—The descriptor includes the remote object identifier and information to instantiate a proxy instance of the remote card object.
An exception thrown by the remote method.

8.3 Data Formats

This section describes the formats used to encapsulate the following:

A remote object identifier which identifies the remote object on the card.
A remote object reference descriptor which describes the remote object on the card for the CAD client.
A method identifier which identifies the remote method on the card.
The method parameters and return values.

This section uses a C-like structure notation similar to that used in the Virtual Machine Specification for the Java Card™ Platform, Version 2.2.1.

8.3.1 Remote Object Identifier

A remote object identifier is a 16-bit unsigned number which uniquely identifies a remote object on the card.

8.3.2 Remote Object Reference Descriptor

The remote object reference descriptor includes the remote object identifier, as well as information to instantiate the proxy class on the CAD client. The remote object reference descriptor uses one of two alternate formats. The representation based on the name of the class uses the remote_ref_with_class format. The representation based on the names of the implemented remote interfaces uses the remote_ref_with_interfaces format.

A remote object reference descriptor is therefore defined as follows:

remote_ref_descriptor { 
    union { 
        ref_null remote_ref_null 
        remote_ref_with_class remote_ref_c 
        remote_ref_with_interfaces remote_ref_i 
        } 
} 

The items in the remote_ref_descriptor structure are:

ref_null is the representation of a null reference using the following format:

ref_null { 
   u2 remote_ref_id = 0xFFFF 
} 

The remote_ref_id item must be the reserved value 0xFFFF.

remote_ref_with_class is the definition of a remote object reference using the class name and uses the following format:

    remote_ref_with_class { 
      u2 remote_ref_id != 0xFFFF 
      u1 hash_modifier_length 
      u1 hash_modifier[ hash_modifier_length ] 
      u1 pkg_name_length 
      u1 package_name[ pkg_name_length ] 
      u1 class_name_length 
      u1 class_name[ class_name_length ] 
    } 

The remote_ref_id item represents the remote reference identifier. The value of this field must not be 0xFFFF which denotes the null reference.

The hash_modifier item is an UTF-8 string of length specified in the hash_modifier_length item and is used to ensure that method identifier hash codes are unique.

The pkg_name_length item is the number of bytes in the package_name item to represent the name of the package in UTF-8 string notation. The value of this item must be non-zero.

The package_name item is the variable length representation of the fully qualified name of the package which contains the remote class in UTF-8 string notation. The fully qualified name of the package represented here uses the internal form wherein the ASCII periods (‘.’) that normally separate the indentifiers that make up the fully qualified name are replaced by ASCII forward slashes (‘/’). For example, the internal form of the normally fully qualified package name of the package java.rmi is java/rmi.

The class_name_length item is the number of bytes in the class_name item to represent the name of the remote class in UTF-8 string notation. The value of this item must be non-zero.

The class_name item is the variable length representation of the name of the implementation class of the remote object in UTF-8 string notation.

remote_ref_with_interfaces item is the definition of a remote object reference using the names of the interfaces and uses the following format:

remote_ref_with_interfaces { 
      u2 remote_ref_id != 0xFFFF 
      u1 hash_modifier_length 
      u1 hash_modifier[ hash_modifier_length ] 
      u1 remote_interface_count 
      rem_interface_def remote_interfaces[remote_interface_count] 
   } 

The definition of the remote_ref_id, the hash_modifier_length and the hash_modifier item are the same as that described earlier in the remote_ref_with_class structure.

The remote_interface_count item indicates the number of rem_interface_def format entries in the remote_interfaces item. This number must be less than 16.

The remote_interfaces item comprises a sufficient list of rem_interface_def format entries containing the names of remote interfaces implemented. This list is such that when combined with their remote superinterfaces, the complete set of remote interfaces implemented by the remote object can be enumerated. The rem_interface_def item uses the following format:

  rem_interface_def { 
      u1 pkg_name_length 
      u1 package_name[ pkg_name_length ] 
      u1 interface_name_length 
      u1 interface_name[ interface_name_length ] 
      } 

The items in the rem_interface_def structure are as follows:

The pkg_name_length item is the number of bytes used in the package_name item to represent the name of the package in UTF-8 string notation. If the value of this item is 0, it indicates that the package name of the previous remote_interfaces item must be used instead. The value of this item in remote_interfaces[0] must not be 0.

The package_name item is the pkg_name_length byte length representation of the fully qualified name of the package which contains the remote interface in UTF-8 string notation. The fully qualified name of the package represented here uses the internal form wherein the ASCII periods (‘.’) that normally separate the indentifiers that make up the fully qualified name are replaced by ASCII forward slashes (‘/’). For example, the internal form of the normally fully qualified package name of the package java.rmi is java/rmi.

The interface_name_length item is the number of bytes in the interface_name item to represent the name of the remote interface in UTF-8 string notation.

The interface_name item is the variable length representation of the name of the remote interface implemented by the remote object in UTF-8 string notation.

8.3.3 Method Identifier

A method identifier will always be used in association with a remote object reference. A method identifier is defined as follows:

u2 method_id 

The method_id is a unique 16-bit hashcode identifier of the remote method within the remote class. This 16-bit hashcode consists of the first two bytes of the SHA-1 message digest function performed on a class specific hash modifier string followed the name of the method followed by the method descriptor representation in UTF-8 format. Representation of a method descriptor is the same as that described in The Java Virtual Machine Specification (Section 4.3.3)

8.3.4 Parameter Encoding

Every parameter will have the following generic format:

param { 
      u1 value[] 
    } 

8.3.4.1 Primitive Data Type Parameter Encoding

Primitive data types void, boolean, byte, short and int will respectively be encoded as follows:

void_param { 
    } 
boolean_param { 
      u1 boolean_value 
    } 
byte_param { 
      s1 byte_value 
    } 
short_param { 
      s2 short_value 
    } 
int_param { 
      s4 int_value 
    } 

The boolean_value field may only take the values 0 (for false) and 1 (for true). All the other fields can take any value in their range.

8.3.4.2 Array Parameter Encoding

The representation of the null array parameter and arrays of the boolean, byte, short and int component types include the length information and will respectively be encoded as follows:

null_array_param { 
      u1 length = 0xFF 
    } 
boolean_array_param { 
      u1 length != 0xFF 
      u1 boolean_value[length] 
    } 
byte_array_param { 
      u1 length != 0xFF 
      s1 byte_value[length] 
    } 
short_array_param { 
      u1 length != 0xFF 
      s2 short_value[length] 
    } 
int_array_param { 
      u1 length != 0xFF 
      s4 int_value[length] 
    } 

8.3.5 Return Value Encoding

A return value may be any of the parameter types described in the previous section encapsulated within a normal response format. In addition, the return value may represent a remote object reference type, a null return type, various exceptions and the error type.

The generic structure of a return value is as follows:

return_response { 
      u1 tag 
      u1[] value 
    } 

The return value using the return_response encoding is always followed by a good completion status code of 0x9000 in the response APDU.

8.3.5.1 Normal Response Encoding

A normal response encapsulates primitive return types, arrays of primitive data types using the same format for the param item as described in Section 8.3.4 "Parameter Encoding” using the following format:

normal_param_response { 
      u1 normal_tag = 0x81 
      param normal_value 
    } 

The null_array_param format described in the Parameter Encoding Section 8.3.4 is not used to represent a null array reference. Instead, a null object reference as well as a null array reference share the following common format:

normal_null_response { 
      u1 normal_tag = 0x81 
      ref_null null_array_or_ref 
    } 

In addition, a remote object reference descriptor type is also encapsulated using the normal response format as follows:

normal_ref_response { 
      u1 normal_tag = 0x81 
      remote_ref_descriptor remote_ref 
    } 

8.3.5.2 Exception Response Encoding

The following is the encoding when an API defined exception is thrown by the remote method. It may be returned during any remote method invocation. The reason item is the Java Card platform exception reason code, or 0 for a java.lang, java.rmi or java.io exceptions:

exception_response { 
      u1 exception_tag = 0x82 
      u1 exception_type 
      s2 reason 
    } 

The values for the exception_type item are shown below:

java.lang.Throwable = 0x00 
java.lang.ArithmeticException = 0x01 
java.lang.ArrayIndexOutOfBoundsException = 0x02 
java.lang.ArrayStoreException = 0x03 
java.lang.ClassCastException = 0x04 
java.lang.Exception = 0x05 
java.lang.IndexOutOfBoundsException = 0x06 
java.lang.NegativeArraySizeException = 0x07 
java.lang.NullPointerException = 0x08 
java.lang.RuntimeException = 0x09 
java.lang.SecurityException = 0x0A 
java.io.IOException = 0x0B 
java.rmi.RemoteException = 0x0C 
javacard.framework.APDUException = 0x20 
javacard.framework.CardException = 0x21 
javacard.framework.CardRuntimeException = 0x22 
javacard.framework.ISOException = 0x23 
javacard.framework.PINException = 0x24 
javacard.framework.SystemException = 0x25 
javacard.framework.TransactionException = 0x26 
javacard.framework.UserException = 0x27 
javacard.security.CryptoException = 0x30 
javacard.framework.service.ServiceException = 0x40 

The following is the encoding when a user defined exception is thrown by the remote method. The exception_type item represents the closest API defined exception type. It may be returned during any remote method invocation. The reason item is the Java Card platform exception reason code, or 0 for the subclasses of java.lang, java.rmi or java.io exceptions:

exception_subclass_response { 
      u1 exception_subclass_tag = 0x83 
      u1 exception_type 
      s2 reason 
    } 

8.3.5.3 Error Response Encoding

The following encoding represents an error condition on the card. The error may occur due to marshalling, unmarshalling or resource related problems.

error_response { 
      u1 error_tag = 0x99 
      s2 error_detail 
    } 

The values of the error_detail item are enumerated below:

The Remote Object Identifier is invalid or ineligible for Java Card RMI = 0x0001
The Remote Method could not be identified = 0x0002
The Remote Method signature did not match the parameter format = 0x0003
Insufficient resources available to unmarshall parameters = 0x0004
Insufficient resources available to marshall response = 0x0005
Java Card Remote Method Invocation protocol error = 0x0006
Internal Error occurred = 0xFFFF

8.4 APDU Command Formats

Section 8.3 "Data Formats” described the various elements included in the data portion of the Java Card RMI messages. This section describes the complete format of the APDU commands - the header as well as the data portion containing the message elements described earlier.

8.4.1 SELECT FILE Command

The Select command for an RMI based applet must have the following format:

The bits (b2,b1*) are used for partial selection if supported. If bit b5* is 1, the remote reference descriptor uses the remote_ref_with_interfaces format, otherwise it uses the alternate remote_ref_with_class format.

The format of the response is defined as shown below. Note that the applet may extend the format to include additional information, if necessary before sending the response back to the CAD. The additional information must retain the TLV format and must not introduce any additional information under the jc_rmi_data_tag.

select_response { 
    u1 fci_tag = 0x6F 
    u1 fci_length 
        u1 application_data_tag = 0x6E 
        u1 application_data_length 
            u1 jc_rmi_data_tag = 0x5E 
            u1 jc_rmi_data_length 
            u2 version = 0x0202 
            u1 invoke_ins 
            union { 
                normal_ref_response normal_initial_ref 
                normal_null_response null_initial_ref  
                error_response initial_ref_error 
                } initial_ref 
    } 

The jc_rmi_data_length item above is the combined length in bytes of the version item, invoke_ins item and the initial_ref item. The application_data_length item is jc_rmi_data_length + 2. The fci_length item is application_data_length + 2.

The response data includes invoke_ins, the instruction byte to use in the method invocation command. It also includes initial_ref, the initial remote object reference descriptor. The initial_ref item corresponds to the remote object designated as the initial reference to the RMIService instance during construction. The initial_ref item can be a normal_ref_response item described in Section 8.3.5.1 or a null representation using a normal_null_response item described in Section 8.3.5.1, if the initial remote reference object is not enabled for remote access. Also, note that if an error occurs during the marshalling of the initial remote reference descriptor, an error response is returned in initial_ref instead using the error_response item format described in Section 8.3.5.3 .

The format of the remote_ref_descriptor to be used in this response as well as all subsequent responses - remote_ref_with_class or remote_ref_with_interfaces - is determined by the value of the P2 byte of the SELECT FILE command.

8.4.2 INVOKE Command

The Invoke command for a remote method invocation request must have the following format:

The data part of the request command is structured as:

invoke_data { 
     u2 object_id 
     u2 method_id 
     param parameters[] 
   } 

The object_id is the remote object identifier of the object whose remote method is to be invoked. The method to be invoked is specified by the method_id item, and each parameter is specified by a param structure.

The response format uses the return_response structure as described in Section 8.3.5 "Return Value Encoding” above.

8.5 The RMIService Class

The RMIService class implements the Java Card RMI protocol and processes the RMI access commands described earlier: SELECT FILE and INVOKE. It performs the function of the transport layer for Java Card RMI commands on the card.

The RMIService object maintains a list of remote objects which have been returned during the current applet selection session. It enforces the following rules for the lifetime of the remote object references:

A remote reference is valid only when the INVOKE command is processed by the RMIService instance which returned the reference.
A remote reference is valid with any applet instance in the package of the applet instance which returned it.
A remote reference is valid as long as at least one applet instance within the same package has been active at all times since the point in time when the remote reference was returned.
A valid remote object cannot be garbage collected during the lifetime of the remote reference.

In addition, a remote object reference descriptor of an object must only be returned from the card if it is exported (See the class javacard.framework.service.CardRemoteObject.) Otherwise, an exception is thrown (See the class javacard.framework.service.RMIService.)

8.5.1 setInvokeInstructionByte Method

This method sets the value of invoke_ins described in Section 8.4.1, which is returned in the response to the SELECT FILE command. The change in the Java Card RMI protocol only goes into effect the next time this RMIService instance processes the SELECT FILE command. If this method is not called, the default instruction byte value (DEFAULT_RMI_INVOKE_INSTRUCTION) is used.

8.5.2 processCommand Method

The processCommand method of the RMIService class is invoked by the applet to process an incoming RMI message. RMIService collaborates with other services by using the common service format (CSF) in the APDU buffer. It processes only the incoming Java Card RMI APDU commands and produces output as described in the previous sections.

When called with a SELECT FILE command with format described in Section 8.4.1, this method builds a response APDU as described in that section.

When called with an INVOKE command with the format described in Section 8.4.2, this method must call the specified remote method of the identified remote object with the specified parameters. It must catch all exceptions thrown by the remote method. When an exception is caught or the remote method returns, this method must build a response APDU in the format described in Section 8.4.2.

Prior to invoking the remote method the following errors must be detected and must result in an error response in the format described in Section 8.3.5.3:

The remote object identifier is not valid.
The remote object identifier has not been returned during the current selection session.
The method identifier does not match any remote methods in the remote class associated with the identified remote object.
The length of the INVOKE message is inconsistent with the signature of the remote method.
There is insufficient space to allocate array parameters for the remote method. The implementation must support at least 8 input parameters of type array.

In addition, upon return from the remote method, the following errors must be detected and must result in an error response in the format described in Section 8.3.5.3:

There is insufficient space to allocate the array response from the remote method. The implementation must support an APDU buffer of at least 133 bytes.
A remote object is being returned, and its associated remote object identifier has not been previously returned during the current selection session and there is insufficient space to add the remote object identifier to the session remote object identifier list. The implementation must support at least 8 remote object identifiers during a selection session.

In addition to the above, the object access firewall rules must be enforced in a manner similar to that of the invokevirtual instruction (Section 6.2.8.4) by this method when a remote method is invoked. Only methods of a remote object owned by the context of the currently selected applet may be invoked.

Allocation of Incoming Objects

Since array parameters to remote methods are transmitted by value, array objects need to be allocated on the card when a remote method with array arguments is invoked via the INVOKE command. Global array objects (Section 6.2.2) must be used for incoming remote method arguments. Global arrays have the following properties:

They are owned by the Java Card RE, but they can be freely accessed from all contexts.
They are temporary objects and cannot be stored in any object.
They are not subject to transactions

The implementation may choose to maintain the data portion of these global array objects used for remote method parameters in the APDU buffer itself.

Runtime Environment Specification for the Java Card Platform Specification, 2.2.1

Copyright © 2003 Sun Microsystems, Inc. All rights reserved.