org.simalliance.openmobileapi
Interface Session

public interface Session

Instances of this class represent a connection session to one of the secure elements available on the device. These objects can be used to get a communication channel with an application in the secure element. This channel can be the basic channel or a logical channel.

getReader

Reader getReader()

Get the reader that provides this session

Returns:

the Reader object

getATR

byte[] getATR()

Get the Answer to Reset of this Secure Element. The returned byte array can be null if the ATR for this Secure Element is not available.

Returns:

the ATR as a byte array

close

void close()

Close the connection with the secure element. This will close any channels opened by this application with this secure element.

isClosed

boolean isClosed()

Tells if this session is closed

Returns:

true if the session is closed

closeChannels

void closeChannels()

Close any channel opened on this session

openBasicChannel

Channel openBasicChannel(byte[] aid)
                         throws IOException,
                                IllegalStateException,
                                IllegalArgumentException,
                                SecurityException

Get an access to the basic channel, as defined in the ISO7816-4 specification (the one that has number 0). The obtained object is an instance of the Channel class. If the AID is null, which means no SE application is to be selected on this channel, the default SE application is used else the corresponding SE application is selected. Once this channel has been opened by a device application, it is considered as "locked" by this device application, and other calls to this method will return null, until the channel is closed. Some secure elements (like the UICC) might always keep the basic channel locked (i.e. return null to applications), to prevent access to the basic channel, while some other might return a channel object implementing some kind of filtering on the commands, restricting the set of accepted command to a smaller set. It is recommended for the UICC to reject the opening of the basic channel to a specific applet, by always answering null to such a request. For other secure elements, the recommendation is to accept opening the basic channel on the default applet until another applet is selected on the basic channel. As there is no other way than a reset to select again the default applet, the implementation of the transport API should guarantee that the openBasicChannel(null) command will return null until a reset occurs. If such a restriction is not possible, then openBasicChannel(null) should always return null and therefore prevent access to the default applet on the basic channel. There is no way for the application to retrieve the select response. Recommendation for an implementation: Any select response has to be fetched but should be discarded internally.

Parameters:

aid - the AID of the application to be selected on this channel, as a byte array, or null if no application is to be selected

Returns:

an instance of channel if available or null

Throws:

IOException - if there is a communication problem to the reader or the secure element (e.g. if the AID is not available).

IllegalStateException - if the secure element session is used after being closed.

IllegalArgumentException - if the AID's length is not within 5 to 16(inclusive).

SecurityException - if the calling application cannot be granted access to this AID or the default application on this session.

openLogicalChannel

Channel openLogicalChannel(byte[] aid)
                           throws IOException,
                                  IllegalStateException,
                                  IllegalArgumentException,
                                  SecurityException

Open a logical channel with the secure element, selecting the application represented by the given AID. If the AID is null, which means no application is to be selected on this channel, the default application is used. It's up to the secure element to choose which logical channel will be used. There is no way for the application to retrieve the select response. Recommendation for an implementation: Any select response has to be fetched but should be discarded internally.

Parameters:

aid - the AID of the application to be selected on this channel, as a byte array.

Returns:

an instance of channel. Null if the secure element is unable to provide a new logical channel

Throws:

IOException - if there is a communication problem to the reader or the secure element (e.g. if the AID is not available).

IllegalStateException - if the secure element session is used after being closed.

IllegalArgumentException - if the AID's length is not within 5 to 16(inclusive).

SecurityException - if the calling application cannot be granted access to this AID or the default application on this session.