Shareable Interfaces

Shareable interfaces are a feature in the Java Card API to enable applet interaction. A

shareable interface defines a set of shared interface methods. These interface methods can be invoked from one context even if the object implementing them is owned by an applet in another context.

In this specification, an object instance of a class implementing a shareable interface is called a Shareable Interface Object (SIO).

To the owning context, the SIO is a normal object whose fields and methods can be accessed. To any other context, the SIO is an instance of the shareable interface, and only the methods defined in the shareable interface are accessible. All other fields and methods of the SIO are protected by the firewall.

Shareable interfaces provide a secure mechanism for inter-applet communication, as described in the following sections.

6.2.4.1

Server Applet A Builds a Shareable Interface Object

1. To make an object available for sharing with another applet in a different context, applet A first defines a shareable interface, SI. A shareable interface extends the interface javacard.framework.Shareable. The methods defined in the shareable interface, SI, represent the services that applet A makes accessible to other applets.

2. Applet A then defines a class C that implements the shareable interface SI. C implements the methods defined in SI. C may also define other methods and fields, but these are protected by the applet firewall. Only the methods defined in SI are accessible to other applets.

3. Applet A creates an object instance O of class C. O belongs to applet A, and the firewall allows A to access any of the fields and methods of O.

6.2.4.2

Client Applet B Obtains the Shareable Interface Object

1. To access applet A’s object O, applet B creates an object reference SIO of type SI. 2. Applet B invokes a special method

(JCSystem.getAppletShareableInterfaceObject, described in

Section 6.2.7.2, “JCSystem.getAppletShareableInterfaceObject Method” on page 6-15) to request a shared interface object reference from applet A.

3. Applet A receives the request and the AID of the requester (B) via

Applet.getShareableInterfaceObject, and determines whether it will share object O with applet B. A’s implementation of the

getShareableInterfaceObject method executes in A’s context. 4. If applet A agrees to share with applet B, A responds to the request with a

reference to O. As this reference is returned as type Shareable, none of the fields or methods of O are visible.

5. Applet B receives the object reference from applet A, casts it to the interface type SI, and stores it in object reference variable SIO. Even though SIO actually refers to A’s object O, SIO is an interface of type SI. Only the shareable interface methods defined in SI are visible to B. The firewall prevents the other fields and methods of O from being accessed by B.

In this sequence, applet B initiates communication with applet A using the special system method in the JCSystem class to request a Shareable Interface Object from applet A. Once this communication is established, applet B can obtain other Shareable Interface Objects from applet A using normal parameter passing and return mechanisms. It can also continue to use the special JCSystem method described above to obtain other Shareable Interface Objects.

6.2.4.3

Client Applet B Requests Services from Applet A

1. Applet B can request service from applet A by invoking one of the shareable interface methods of SIO. During the invocation the Java Card VM performs a context switch. The original currently active context (B) is saved on a stack and the context of the owner (A) of the actual object (O) becomes the new currently active context. A’s implementation of the shareable interface method (SI method) executes in A’s context.

2. The SI method can determine the AID of its client (B) via the

JCSystem.getPreviousContextAID method. This is described in Section 6.2.5, “Determining the Previous Context” on page 6-13. The method determines whether or not it will perform the service for applet B.

3. Because of the context switch, the firewall allows the SI method to access all the fields and methods of object O and any other object in the context of A. At the same time, the firewall prevents the method from accessing non-shared objects in the context of B.

4. The SI method can access the parameters passed by B and can provide a return value to B.

5. During the return, the Java Card VM performs a restoring context switch. The original currently active context (B) is popped from the stack, and again becomes the currently active context.

6. Because of the context switch, the firewall again allows B to access any of its objects and prevents B from accessing non-shared objects in the context of A.

6.2.5

Determining the Previous Context

When an applet calls JCSystem.getPreviousContextAID, the Java Card RE shall return the instance AID of the applet instance active at the time of the last context switch.

6.2.5.1

Java Card RE Context

The Java Card RE context does not have an AID. If an applet calls the

getPreviousContextAID method when the context of the applet was entered directly from the Java Card RE context, this method returns null.

If the applet calls getPreviousContextAID from a method that may be accessed either from within the applet itself or when accessed via a shareable interface from an external applet, it shall check for null return before performing caller AID authentication.

6.2.6

Shareable Interface Details

A shareable interface is simply one that extends (either directly or indirectly) the

tagging interface javacard.framework.Shareable. This Shareable interface is

similar in concept to the Remote interface used by the RMI facility, in which calls to the interface methods take place across a local/remote boundary.

6.2.6.1

Java Card API Shareable Interface

Interfaces extending the Shareable tagging interface have this special property: Calls to the interface methods take place across Java Card platform’s applet firewall boundary by means of a context switch.

The Shareable interface serves to identify all shared objects. Any object that needs to be shared through the applet firewall shall directly or indirectly implement this interface. Only those methods specified in a shareable interface are available through the firewall.

Implementation classes can implement any number of shareable interfaces and can extend other shareable implementation classes.

Like any Java platform interface, a shareable interface simply defines a set of service methods. A service provider class declares that it “implements” the shareable interface and provides implementations for each of the service methods of the interface. A service client class accesses the services by obtaining an object reference, casting it to the shareable interface type, and invoking the service methods of the interface.

The shareable interfaces within the Java Card technology shall have the following properties:

■ When a method in a shareable interface is invoked, a context switch occurs to the context of the object’s owner.

■ When the method exits, the context of the caller is restored.

■ Exception handling is enhanced so that the currently active context is correctly restored during the stack frame unwinding that occurs as an exception is thrown.

6.2.7

Obtaining Shareable Interface Objects

Inter-applet communication is accomplished when a client applet invokes a shareable interface method of a SIO belonging to a server applet. For this to work, there must be a way for the client applet to obtain the SIO from the server applet in the first place. The Java Card RE provides a mechanism to make this possible. The Applet class and the JCSystem class provide methods to enable a client to request services from the server.

6.2.7.1

Applet.getShareableInterfaceObject(AID, byte)

Method

This method is implemented by the server applet instance. It shall be called by the Java Card RE to mediate between a client applet that requests to use an object belonging to another applet, and the server applet that makes its objects available for sharing.

The default behavior shall return null, which indicates that an applet does not participate in inter-applet communication.

A server applet that is intended to be invoked from another applet needs to override this method. This method should examine the clientAID and the parameter. If the clientAID is not one of the expected AIDs, the method should return null. Similarly, if the parameter is not recognized or if it is not allowed for the clientAID, the method also should return null. Otherwise, the applet should return an SIO of the shareable interface type that the client has requested.

The server applet need not respond with the same SIO to all clients. The server can support multiple types of shared interfaces for different purposes and use

clientAID and parameter to determine which kind of SIO to return to the client.

6.2.7.2

JCSystem.getAppletShareableInterfaceObject

Method

The JCSystem class contains the method

getAppletShareableInterfaceObject, which is invoked by a client applet to communicate with a server applet.

The Java Card RE shall implement this method to behave as follows:

1. The Java Card RE searches its internal applet table which lists all successfully installed applets on the card for one with serverAID. If not found, null is returned.

2. If the server applet instance is not a multiselectable applet instance and is currently active on another logical channel, a SecurityException is thrown. See Section 4.2, “Multiselectable Applets” on page 4-7.

3. The Java Card RE invokes this applet’s getShareableInterfaceObject method, passing the clientAID of the caller and the parameter.

4. A context switch occurs to the server applet, and its implementation of

getShareableInterfaceObject proceeds as described in the previous section. The server applet returns a SIO (or null).

5. getAppletShareableInterfaceObject returns the same SIO (or null) to its caller.

For enhanced security, the implementation shall make it impossible for the client to tell which of the following conditions caused a null value to be returned:

■ The serverAID was not found.

■ The server applet does not participate in inter-applet communication. ■ The server applet does not recognize the clientAID or the parameter. ■ The server applet does not communicate with this client.

■ The server applet does not communicate with this client as specified by the parameter.

■ The applet’s getShareableInterfaceObject method throws an uncaught exception.