C H A P T E R 2 - Working with Logical Channels

C H A P T E R 2

Working with Logical Channels

Version 2.2.2 of the Java Card platform has the ability to support up to twenty logical channels per active interface. This gives an ISO-7816-4:2005-compliant terminal the ability to open as many as twenty sessions into the smart card, one session per logical channel. Logical channels allow the concurrent execution of multiple applications on the card, allowing a terminal to handle different tasks at the same time.

Applets written for version 2.1 of the Java Card platform still work correctly, but they are unaware of logical channel support. In contrast, applets written for version 2.2.2 can take advantage of this feature.

For example, you can write an applet for version 2.2.2 of the Java Card platform that is capable of handling security on one channel, while another applet attempts to access user personal information on another channel, using security information on the first. By following this design, it is possible to access information owned by a different applet without having to deselect the currently selected applet that is handling session information. Thus, you avoid losing your session-specific security data, which is usually stored in CLEAR_ON_DESELECT RAM memory.

On dual interface cards, each interface itself can handle up to twenty independent logical channels. Each interface has its separate pool of logical channels: channels sharing the same number on two distinct interfaces will be treated as two independent, separate logical channels. Therefore, a dual concurrent interface card could, in theory, support up to forty concurrent logical channels, twenty per each interface. Channel management commands can only affect the operation logical channels in the interface where these commands were issued.

For more information on logical channels, their implementation and logical channel terminology, see the Runtime Environment Specification for the Java Card Platform, Version 2.2.2.

Applets and Logical Channels

In version 2.2.2 of the Java Card platform, you can work with applets that are aware of multiple channels and applets that are not aware of multiple channels.

The logical channel implementation in version 2.2.2 of the Java Card platform preserves backward compatibility with applets written for the Java Card platform version 2.1. It also allows you the option of writing your applets to use the logical channel feature or of writing the applets to work independently on any channel without using the logical channels at all.

Non-MultiSelectable Applets

In version 2.2.2 of the Java Card platform, you have the option of writing applets that can operate in a multiple channel environment, or you can write applets that do not take advantage of this feature. Applets written for the Java Card platform that do not take advantage of the multiple channel environment are similar to applets written for the version 2.1 Java Card specification. An applet written for the Java Card platform that is not designed to be aware of multiple channels cannot be selected more than once nor can any other applet inside the package be selected concurrently on a different channel.

You can have several non-multiselectable applets operating simultaneously on different channels, as long as they do not interfere with each other's data while they are active. For example, you can open up to 4 channels and run a distinct applet on each as long as they do not inter-operate. You can control their operation by multiplexing commands into the APDU communications channel. If the applets are independent of each other, then the results will be the same as if each of these applets were running one at a time, each in a separate session.

Interoperability

If you design your applets to take advantage of multi-session functionality, they can inter-operate from different channels and can be selected multiple times in different channels. For example, the card might handle security information on one channel, while data is accessed on a second channel, while the third channel takes care of data encoding operations.

Understanding the MultiSelectable Interface

For an applet to be selectable on multiple channels at the same time, or to have another applet belonging to the same package selected simultaneously, it must implement the javacard.framework.MultiSelectable interface. Implementing this interface allows the applet to be informed when it has been selected more than once or when applets in the same package are already selected during applet activation.

If an applet that does not implement MultiSelectable is selected more than once on different channels, or selected concurrently with applets in the same package, an error is returned to the terminal.

Note - If an applet in any package implements the MultiSelectable interface, then all applets in the package must also implement the MultiSelectable interface. It is not possible to have multiselectable and non-multiselectable applets in the same package.

The MultiSelectable interface contains a select and a deselect method to manage multiselectable applets.

Selection for MultiSelectable Applets

The MultiSelectable interface defines one method to be invoked instead of Applet.select() when the applet being selected, or any other applet in its package, is already selected on another logical channel.

public boolean MultiSelectable.select(boolean appInstAlreadySelected)

The MultiSelectable.select(boolean) method informs the applet instance if it is selected more than once on different channels, or if another applet in the same package is selected on another channel on any interface. The parameter appInstAlreadySelected is true if the applet is selected on a different channel. It is false if it is not selected. The method can return either true or false to accept or reject applet selection.

This method can be called as a result of issuing a SELECT FILE or MANAGE CHANNEL OPEN APDU command to select an applet. If the applet is not selected, then the appInstAlreadySelected parameter is passed as false to signal an applet activation event. If the applet is subsequently selected on another channel, MultiSelectable.select(boolean) is called again, but this time, the appInstAlreadySelected parameter is passed as true, to indicate that the applet is already active.

Deselection for MultiSelectable Applets

The MultiSelectable interface defines one method to be invoked instead of Applet.select() when the applet being deselected, or any other applet in its package, is already selected on another logical channel.

public void MultiSelectable.deselect(boolean appInstStillSelected)

The MultiSelectable.deselect(boolean) method informs the applet instance if it is being deselected on the logical channel while the same applet instance or another applet in the same package is still active on another channel on any interface. The parameter appInstStillSelected is true if the applet remains active on a different channel. It is false if it is not active on another channel. A value of false indicates that this is the last remaining active instance of the applet.

This method can be called as the result of a MANAGE CHANNEL CLOSE or SELECT FILE APDU command. If the applet still remains active on a different channel, the appInstStillSelected parameter is passed as true. Note that if the MultiSelectable.deselect(boolean) method is called, it means that either an instance of this applet or another applet from the same package remains active on another channel, so CLEAR_ON_DESELECT transients are not cleared. Only when the last applet instance from the entire package is deselected does a call to Applet.deselect() result, resulting in the erasure of CLEAR_ON_DESELECT transients.

Writing Applets For Concurrent Logical Channels

This section describes how to write a multiselectable applet that will perform various tasks based on whether it is selected. The code samples in this section show how to extend the applet to implement the MultiSelectable interface and how to implement the MultiSelectable.select(boolean) and deselect(boolean) methods. The code samples also show how to use the Applet.select() and deselect() methods to work with multiselectable applets.

To take advantage of multiple channel operation, an applet must implement the javacard.framework.MultiSelectable interface. For example:

public class SampleApplet extends Applet

implements MultiSelectable {

...

}

The new applet needs to provide implementation for the MultiSelectable.select(boolean) and MultiSelectable.deselect(boolean) methods. These methods are responsible for encoding the behavior that the applet needs during a selection event if either of the following situations occurs:

The applet is already selected on a different channel.

One or more applets from the same package are also selected on different channels.

The behavior to be encoded might include initializing applet state, accepting or rejecting the selection request, or clearing data structures in case of deselection.

public boolean select(boolean appInstAlreadySelected) {

// Implement the logic to control applet selection

// during a multiselection situation

...

}

public void deselect(boolean appInstStillSelected) {

// Implement the logic to control applet deselection

// during a multiselection situation

...

}

Note that the applet is still required to implement the Applet.select() and Applet.deselect() methods in addition to the MultiSelectable interface. These methods handle applet selection and deselection behavior when a multiselection situation does not happen.

MultiSelectable Applet Example

In this example, assume that the multiselectable applet, SampleApplet, must initialize the following two arrays of data when it is selected:

An array of package data to be initialized when the first applet in the package becomes active

An array of private applet data to be initialized upon applet instance activation

You can make these distinctions in your code because the MultiSelectable interface allows the applet to recognize the circumstances under which it is selected.

Also, assume that the applet has the following requirements:

Clear the package data once no applet in the package is active

Clear the applet private data when the applet instance is deselected

Assume that the following methods are responsible for clearing and setting the data:

// dataType parameter as above

final static byte DATA_PRIVATE = (byte)01;

final static byte DATA_PACKAGE = (byte)02;

...

public void initData(byte[] dataArray, byte dataType) {

...

}

public void clearData(byte[] dataArray) {

...

}

To achieve the behavior specified above, you must modify the selection and deselection methods in your sample applet.

The code for Applet.select(), which is invoked when this applet is the first to become active in the package, can be implemented like this:

public boolean select() {

// First applet to be selected in package, so

// initialize package data and applet data

initData(packageData, DATA_PACKAGE);

initData(privateData, DATA_PRIVATE);

return true;

}

Likewise, the implementation of the method MultiSelectable.select(boolean) must determine whether the applet is already active. According to its definition, this method is called when another applet within this package is active. MultiSelectable.select(boolean) can be implemented such that if appInstAlreadySelected is false, then the applet private data can be initialized. For example:

public boolean select(boolean appInstAlreadySelected) {

// If boolean parameter is false,

// then we have applet activation

// Otherwise, no applet activation occurs.

if (appInstAlreadySelected == false) {

// Initialize applet private data, upon activation

initData(privateData, DATA_PRIVATE);

}

return true;

}

In the case of deselection, the applet data must be cleared. The method MultiSelectable.deselect(boolean) can be implemented so that it clears applet data only if the applet is no longer active. For example:

public void deselect(boolean appInstStillSelected) {

// If boolean parameter is false, then applet is no longer

// active. It is O.K. to clear applet private data.

if (appInstStillSelected == false) {

clearData(privateData);

}

If this applet is the last one to be deactivated from the package, it also must clear package data. This situation results in a call to Applet.deselect(). This method can be implemented like this:

public void deselect() {

// This call means that the applet is no longer active and

// that no other applet in the package is. Data for both

// applet and package must be cleared.

clearData(packageData);

clearData(privateData);

}

Handling Channel Information on APDU Commands

APDU commands follow the ISO 7816-4:2005 specifications to encode logical channel information. The CLA byte encodes logical channel information. The CLA byte encoding is divided into two spaces: interindustry, used by all ISO 7816-4:2005- defined commands, and the proprietary space, used by Java Card technology to encode application- specific commands.

The CLA byte encoding is divided into two classes: Type 4 commands, which encode legacy ISO 7816-4 logical channel information; and Type 16 commands, which are defined by the ISO 7816-4:2005 specification to encode information for additional 16 logical channels in the card. Type 4 logical channels occupy the range of [0..3], while Type 16 logical channels go in the range of [4..19], that is, the value encoded in the CLA byte plus four, as it is used in SELECT, MANAGE CHANNEL and other proprietary or ISO commands.

However, a note of caution: while MANAGE CHANNEL command CLA byte follows the encoding as described below, its P2 parameter does not. The logical channel numbers in its P2 parameter are correctly encoded in the range of [0..19].

The CLA byte encoding follows the following rules.

Interindustry Space

CLA Remarks

0x0X Type 4, last or only command in chain

0x1X Type 4, not last command in chain (paired with 0x0X)

0x2X RFU (will throw exception)

0x3X RFU (will throw exception)

0x4X Type 16, no SM, last or only command in chain

0x5X Type 16, no SM, not last command in chain (paired with 0x4X)

0x6X Type 16, SM, last or only command in chain

0x7X Type 16, SM, not last command in chain (paired with 0x07X)

The encoding details are as follows.

Type 4:

b8 b7 b6 b5 b4 b3 b2 b1

0  0  0  x  y  y  z  z

Type 16:

b8 b7 b6 b5 b4 b3 b2 b1

0  1  y  x  z  z  z  z

Notation:

x = Command Chaining bit

0 = last or only command

1 = command chaining

y = Secure Messaging indicator, see ISO7816-4:2003 section 6 for further information.

z = Logical channel indicator

Type 4 supports logical channels [0..3]

Type 16 supports logical channels [0..15], which are mapped to logical channels [4..19]

Proprietary Java Card Technology Space

CLA Remarks

0x8X Type 4, last or only command in chain

0x9X Type 4, not last command in chain (paired with 0x8X)

0xAX Type 4, last or only command in chain

0xBX Type 4, not last command in chain (paired with 0xAX)

0xCX Type 16, no SM, last or only command in chain

0xDX Type 16, no SM, not last command in chain (paired with 0xCX)

0xEX Type 16, SM, last or only command in chain

0xFX Type 16, SM, not last command in chain (paired with 0xEX)

The encoding details are as follows.

Type 4:

b8    b7    b6    b5    b4    b3    b2    b1

1     0     N/A   x     y     y     z     z

Type 16:

b8    b7    b6    b5    b4    b3    b2    b1

1      1    y     x     z     z     z     z

All applets willing to use the logical channel capabilities must comply with the ISO 7816-4:2005 CLA byte encoding specification, and choose APDU commands as defined in the proprietary space.

The X nibble is responsible for logical channels and secure message encoding. Only the two least significant bits of the nibble are used for channel encoding, which ranges from 0 to 3. When an APDU command is received, the card processes it and determines whether the command has logical channel information encoding. If logical channel information is encoded, then the card sends the APDU command to the respective channel. All other APDU commands are forwarded to the card's basic channel (0). For example, the command 0xB1 forwards the command to the card's basic channel (0), because the CLA byte with the nibble 0xBX does not contain logical channel information.

This also means that all applets willing to use the logical channel capabilities must comply with the ISO 7816-4 CLA byte encoding specification, and choose APDU commands accordingly.

Just as the deselection and selection mechanisms must be written to take into consideration a multiple-channel environment, it is important to write the Applet.process() method so that it handles channel information correctly. Due to the fact that some APDUs can be digitally signed, the APDU command is passed to the applet's process method as it is sent by the terminal. That means any logical channel information is not cleared and is passed intact to the applet. The applet must deal with this situation.

To assist applet developers in correctly identifying proprietary and interindustry commands, the following API call can be used. This call returns true if the CLA byte encoding corresponds to the interindustry space, or false if it corresponds to the proprietary space.

...

// Applet's process method

public void process(APDU apdu) {

byte[] buffer = apdu.getBuffer();

// check SELECT APDU command

if (apdu.isISOInterindustryCLA()) {

if (Applet.selectingApplet()) {

return;

} else {

ISOException.throwIt (ISO7816.SW_CLA_NOT_SUPPORTED);

}

...

Writing ISO 7816-4:2005 Compliant Applets

If your applets must be compliant with the ISO 7816-4:2005 specification, then you must track the applet security state on each channel where it is active. Additionally, in the case of multiselectable applets, you must copy the state (including its security configuration) when you perform MANAGE CHANNEL commands from a channel other than the basic channel.

For example, applets might need to perform some sort of initialization upon activation, as well as cleanup procedures during deactivation. To do these tasks, a multiselectable applet might need to keep track of the channels on which it is being selected during a card session.

To track this information, you need to know the channel on which the task is being performed. Tracking is done by two methods in the Java Card API:

APDU class: public static byte getCLAChannel();

This method returns the origin channel where the command was issued. In case of MANAGE CHANNEL or SELECT FILE commands, if this method is called within the Applet.select(), MultiSelectable.select(boolean), Applet.deselect(), or MultiSelectable.deselect(boolean) method, it returns the APDU command logical channel as specified in the CLA byte.

JCSystem class: public static byte getAssignedChannel();

This method returns the channel of the currently selected applet. In case of a MANAGE CHANNEL command, if this method is invoked inside the Applet.select(), MultiSelectable.select(boolean), Applet.deselect(), or MultiSelectable.deselect(boolean) method, it returns the channel where the applet to be selected or deselected is assigned to run.

ISO 7816-4:2005 Compliant Applet Example

In case of a MANAGE CHANNEL command from a non-zero channel to another non-zero channel, the ISO 7816-4 specification requires that the security state from the applet selected in the origin channel be copied into the new channel. In the example presented in this section, assume that the state information is stored in the array appState inside the applet:

StateObj appState[MAX_CHANNELS];    // Holds the security state

                                    // for each logical channel

You can use the APDU.getCLAChannel() and JCSystem.getAssignedChannel() methods to identify if the applet selection case corresponds to an ISO 7816-4 case where the security state needs to be copied. Note that if such an event occurs, it will also be a multiselection situation, where the applet is also selected on the newly opened channel.

In this example, the code to identify the applet selection case is included in the implementation of the MultiSelectable.select(boolean) method:

public boolean select(boolean appInstAlreadySelected) {

...

// Obtain logical channels information

// This call returns the channel where

// the command was issued

byte origChannel = APDU.getCLAChannel();

// This call returns the channel where the applet is being

// selected

byte targetChannel = JCSystem.getAssignedChannel();

if (origChannel == targetChannel) {

// This is a SELECT FILE command.

// Do processing here.

...

}

if (origChannel == 0) {

// This is a MANAGE CHANNEL command from channel 0.

// ISO 7816-4 state sharing case does not

// apply here.

// Do processing here.

...

} else {

// Since origChannel != 0, the special

// ISO 7816-4 case applies.

// Copy security state from origin channel

// to assigned logical channel.

appState[targetChannel] = appState[origChannel];

// Do further processing here

...

}

...

}

Please refer to the Application Programming Interface for the Java Card Platform, Version 2.2.2 for more information about the API methods described above.

Applet Firewall Operation Requirements

To ensure proper operation and protection, a number of applet firewall checks have been added to the virtual machine for the Java Card virtual machine (Java Card VM) regarding security checks on method invocations.

Applets that implement MultiSelectable are designed to handle calls to Shareable objects across packages when several applets are active on different logical channels. In contrast, an applet written for version 2.1 of the Java Card platform, or an applet written for version 2.2.2 that does not implement MultiSelectable, has exclusive control over any changes to its internal objects or data when it is selected. Only when the non-multiselectable applet is in a deselected state can other applets modify its internal data structures. Therefore, if an applet is non-multiselectable, no calls to its Shareable objects can be made when it is selected.

Working with Non-MultiSelectable Applets

Applets written for version 2.2.2 of the Java Card platform do not have to implement the MultiSelectable interface. In this case, the applet assumes that it is uniquely selected and its owned objects will not be modified via Shareable interface objects while it is selected. The limitations are imposed when you interact with applets that do not implement MultiSelectable:

It is not possible to select more than one applet simultaneously from a package if any of the applets you want to select does not implement the MultiSelectable interface.

It is not possible to invoke methods of a Shareable object belonging to a non-multiselectable applet when an applet, belonging to the same group context, is active.

ISO 7816-4:2005 Specific `APDU` Commands for Logical Channel Management

There are two ISO-specific APDU commands that you can use to work with logical channels in a smart card:

SELECT FILE - This command selects the specified applet on the specified channel number. The channel number can be from 0 to 3 and is specified in the lower two bits of the CLA byte. If the channel is closed, it is opened and the specified applet is selected on the channel. SELECT FILE commands are forwarded to the newly selected applet.

MANAGE CHANNEL - This command can be used to open a new channel from another channel or close it. It allows you to specify the channel to be used or to allow the smart card to select the channel. Like SELECT FILE, this command uses the lower two bits of the CLA byte to specify the channel number. MANAGE CHANNEL commands are not forwarded to the applet.

When you work with these commands, keep the following guidelines in mind:

Origin logical channel values are encoded in the two least significant bits of the CLA byte.

Logical channel values have a valid range of [0..19] only.

Logical channel 0 is known as the basic channel, and it cannot be closed.

At card reset, the basic channel (channel 0) is open. All other channels (1, 2, ...19) are closed.

The MANAGE CHANNEL and SELECT FILE commands are read by the Java Card RE dispatcher, which performs the functions specified by the commands, including the following:

Managing logical channels

Deselecting applets

Selecting applets

`MANAGE CHANNEL OPEN`

In response to the MANAGE CHANNEL OPEN command, the dispatcher follows this procedure:

1. If the origin channel is not open, an error is returned.

2. Determines whether the channel is open or closed. If the channel is open, an error is returned.

3. Opens the channel.

4. If the origin channel is 0, the default applet (if there is one) is selected in the new channel.

5. If the origin channel is not 0, the selected applet on the origin channel becomes the selected applet in new channel.

This MANAGE CHANNEL OPEN command opens a new channel from channel encoded in Q.:


CLA	INS	P1	P2	Lc	Data	Le	Data	SW1	SW2
0xQ	0x70	00	00	0	-	1	0x0R	0x90	00


CLA	INS	P1	P2	Lc	Data	Le	SW1	SW2
0xQ	0x70	00	0xR	0	-	0	0x90	00

This command produces the following results:

If channel encoded in Q is the basic channel (channel 0), the card's default applet is selected on channel encoded in R. No applet is selected if no default applet is defined.

If channel encoded in Q is other than the basic channel (channels 1, 2, ...19), the selected applet on channel encoded in Q becomes the current applet selected on channel R.

The applet on channel encoded in R can either accept or reject selection.

This command returns an error under the following circumstances:

The applet does not implement the javacard.framework.MultiSelectable interface, when an attempt to select the applet in more than one channel takes place.

The applet rejects selection or throws exception.

No channel is available.

Channel encoded in Q is not open.

`MANAGE CHANNEL CLOSE`

In response to the MANAGE CHANNEL CLOSE command, the dispatcher follows this procedure:

1. If the origin channel is not open, an error is returned.

2. If the channel to be closed is 0, an error is returned.

3. If the channel to be closed is not open or not available, a warning is thrown.

4. Deselects the applet in the channel to be closed.

5. Closes the logical channel.

This MANAGE CHANNEL CLOSE command closes channel R from channel Q:


CLA	INS	P1	P2	Lc	Data	Le	SW1	SW2
0xQ	0x70	0x80	0xR	0	-	0	0x90	00

This command closes channel R. Channel R must not be the basic channel (it can be channel 1, 2, ...19 only).

This command returns an error in the following circumstances:

Channel encoded in R is the basic channel.

Channel encoded in Q is not open.

It returns a warning if channel R is not open.

`SELECT FILE`

In response to the SELECT FILE command, the dispatcher follows this procedure:

1. If the specified channel is closed, open the channel.

2. Deselect currently selected applet in channel if needed.

3. Select specified applet in the channel.

This SELECT FILE command selects an applet on channel R:


CLA	INS	P1	P2	Lc	Data	Le	SW1	SW2
0x0R	0xA4	0x04	0x00	(AID len)	(AID)	0	0x90	00

This command produces the following results:

Channel encoded in R can be any channel (opened or unopened), including the basic channel.

The applet identified in the Data section becomes the selected applet on channel R.

If channel encoded in R is not open, this command opens channel R.

If channel encoded in R is open, this command changes the selected applet in the channel to the one specified.

This command returns an error in the following circumstances:

The applet cannot be found or is not available. The current applet is left selected and an error is returned.

An active applet belonging to the same package does not implement the javacard.framework.MultiSelectable interface, or if the applet to be selected does not implement this interface.

Channel encoded in R is not available.

Applets and Logical Channels

Non-MultiSelectable Applets

Interoperability

Understanding the MultiSelectable Interface

Selection for MultiSelectable Applets

Deselection for MultiSelectable Applets

Writing Applets For Concurrent Logical Channels

MultiSelectable Applet Example

Handling Channel Information on APDU Commands

Interindustry Space

Proprietary Java Card Technology Space

Writing ISO 7816-4:2005 Compliant Applets

ISO 7816-4:2005 Compliant Applet Example

Applet Firewall Operation Requirements

Working with Non-MultiSelectable Applets

ISO 7816-4:2005 Specific APDU Commands for Logical Channel Management

MANAGE CHANNEL OPEN

MANAGE CHANNEL CLOSE

SELECT FILE

ISO 7816-4:2005 Specific `APDU` Commands for Logical Channel Management

`MANAGE CHANNEL OPEN`

`MANAGE CHANNEL CLOSE`

`SELECT FILE`