8 Remote Method Invocation Service

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 that 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.2.1 Applet Selection

The selection command used to retrieve the initial reference is the ISO 7816-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

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. This designator uniquely identifies 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. This is thrown by the remote method.

8.3.1 Remote Object Identifier

A remote object identifier is a 16-bit unsigned number that 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 following items are in the remote_ref_descriptor structure:

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 identifiers 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 (or superclass) of the remote object in UTF-8 string notation. The class referenced in the remote object reference descriptor must directly implement a remote interface. If the implementation class of the remote object does not directly implement a remote interface, the class name of the "closest" superclass of the implementation class which directly implements a remote interface must be used.

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 identifiers 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 is always 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 by 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 has the following generic format:

param {
      u1 value[]
    }

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

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.

normal_param_response {
      u1 normal_tag = 0x81
      param normal_value
    }

normal_null_response {
      u1 normal_tag = 0x81
      ref_null null_array_or_ref
    }

normal_ref_response {
      u1 normal_tag = 0x81
      remote_ref_descriptor remote_ref
    }

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

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
javacardx.biometry.BioException = 0x50
javacardx.external.ExternalException = 0x60
javacardx.framework.tlv.TLVException = 0x70
javacardx.framework.util.UtilException = 0x80

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

error_response {
      u1 error_tag = 0x99
      s2 error_detail
    }

8.4.1 SELECT FILE Command

Table 8-1 lists the formats required for the Select command for an RMI-based applet.

Following is the format of the response. 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 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, "Normal Response Encoding" or a null representation using a normal_null_response item described in that same section, 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 of using the error_response item format described in Section 8.3.5.3, "Error Response Encoding".

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

Table 8-2 lists the format required for the Invoke command for a remote method invocation request.

Following is the structure of the data part of the request command:

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

8.5.1 setInvokeInstructionByte Method

This method sets the value of invoke_ins described in Section 8.4.1, "SELECT FILE Command", 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, "SELECT FILE Command", 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, "INVOKE Command", 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, "INVOKE Command".

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, "Error Response Encoding":

• The remote object identifier is not valid.

• The remote object identifier was not 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 eight 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, "Error Response Encoding":

• 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 was not 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 eight remote object identifiers during a selection session.

In addition, the object access firewall rules must be enforced in a manner similar to that of the invokevirtual instruction (Section 6.2.8.4, "Accessing Class Instance Object Methods") 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.