javax.microedition.apdu
Interface APDUConnection

All Superinterfaces:

Connection

public interface APDUConnection
extends Connection

This interface defines the APDU (Application Protocol Data Unit) connection. J2ME applications can use this connection to communicate with applications on a smart card using APDU protocol. ISO 7816-4 defines the APDU protocol as an application-level protocol between a smart card and an application on the device. There are two types of APDU messages: command APDUs and response APDUs. Command APDUs are sent to the smart card by J2ME applications. Response APDUs are the messages received from the smart cards. For more information on APDU protocol see the ISO 7816-4 specifications.

Also J2ME applications can use getATR method in this interface to obtain information regarding an Answer To Reset (ATR) returned by the smart card on card reset and use the enterPin method to ask the user to enter PIN which is sent to the smart card for verification.

The methods of APDUConnection are not synchronized. The only method that can be called safely in another thread is close. When close is invoked on a connection that is executing in another thread, any pending I/O method MUST throw an InterruptedIOException. If an application terminates without calling close on the open connection, the implementation SHOULD perform the close operation automatically in order to recover resources, such as the logical channel.

Creating an APDU Connection

An APDU connection is created by passing a generic connection URI string with a card application identifier (AID) and optionally the slot in which the card is inserted, to the Connector.open method. For example, the connection string:apdu:0;target=A0.0.0.67.4.7.1F.3.2C.3 indicates that the connection is to be established with a target application having AID A0.0.0.67.4.7.1F.3.2C.3, which resides in the smart card inserted in the default slot; that is, slot number 0. If the slot number is not specified, then the default slot is assumed.

Communicating With Smart Card Applications

Once an APDU connection is created, the J2ME application can use the exchangeAPDU method to send command APDUs and receive response APDUs to and from the card. J2ME applications cannot use exchangeAPDU to send card application selection APDUs or channel management APDUs. Card application selection is allowed only by calling Connector.open method with the URI string described above and logical channels management is defined by API functionality

Closing an APDUConnection

J2ME application can call javax.microedition.io.Connection.close() on an APDU connection to close the connection. If the connection was established on a channel other than channel 0, this action closes the channel consequently deselecting the card application and making the channel available for use by other APDUConnection applications. In case of channel 0, the channel is marked as available for use by other applications. The application selected on channel 0 is not deselected at the time the connection is closed but remains selected until a new connection is established on channel 0.

BNF Format for Connector.open() string

The URI must conform to the BNF syntax specified below. If the URI does not conform to this syntax, an IllegalArgumentException is thrown.

<APDU_connection_string>	::= "apdu://"<targetAddress>
<targetAddress>	::= [slot]";"target
<slot>	::= smart card slot number (optional. Hxadecimal number identifying the smart card slot. Default slot assumed if left empty)
<target>	::= "target="<target>|"SAT"
<AID>	::= <5 - 16 bytes> An AID (Application Identifier) uniquely identifies a smart card application. It is represented by 5 to 16 hexadecimal bytes where each byte value is separated by a ".".

APDUConnection Example

The following example shows how an APDUConnection can be used to access a smart card application..

  APDUConnection acn = null;
  try{
   //Create an APDUConnection object
   acn = (APDUConnection)
   Connector.open(“apdu:0;target=A0.0.0.67.4.7.1F.3.2C.3”);
   // Send a command APDU and receive response APDU
   responseAPDU = acn.exchangeAPDU(commandAPDU);
   ...
  } catch (IOException e) {
   ...
  } finally {
   ...
   if(acn != null) {
    // Close connection
    acn.close();
   }
   ...
  }
 ...
 

Since:

BlackBerry API 4.2.1

Method Summary
byte[]	changePin(int pinID) This is a high-level method that lets the J2ME application ask the user for PIN values for changing the PIN and sending these values to the card.
byte[]	disablePin(int pinID) This is a high-level method that lets the J2ME application ask for the user PIN value for the PIN that is to be disabled and send it to the card.
byte[]	enablePin(int pinID) This is a high-level method that lets the J2ME application ask for the user to enter the value for the PIN that is to be enabled and send it to the card.
byte[]	enterPin(int pinID) This is a high-level method that lets the J2ME application ask for the user PIN value for PIN verification purposes and send it to the card.
byte[]	exchangeAPDU(byte[] commandAPDU) Exchanges an APDU command with a smart card application.
byte[]	getATR() Returns the Answer To Reset (ATR) message sent by the smart card in response to the reset operation.
byte[]	unblockPin(int blockedPinID, int UnblockingPinID) This is a high-level method that lets the J2ME application ask the user to enter the value for an unblocking PIN, and the new value for the blocked PIN and send these to the card.

Methods inherited from interface javax.microedition.io.Connection

close

Method Detail

exchangeAPDU

byte[] exchangeAPDU(byte[] commandAPDU)
                    throws IOException

Exchanges an APDU command with a smart card application. This method will put the channel number of the associated channel in the CLA byte of the command APDU. Communication with a smart card device is synchronous. This method blocks until the response has been received from the smart card application, or is interrupted. The interruption could be due to the card being removed from the slot or operation timeout.

Parameters:

commandAPDU - - a byte encoded command for the smart card application

Returns:

- a byte encoded command for the smart card application

Throws:

IllegalArgumentException - - if: • commandAPDU parameter is null • commandAPDU contains a card application selection APDU • commandAPDU contains a MANAGE CHANNEL command APDU • if the channel associated with the connection object is non-zero and the CLA byte has a value other than 0x0X, 0x8X, 0x9X or 0xAX • commandAPDU parameter contains a malformed APDU

InterruptedIOException - - can be thrown in any of these situations: • if this Connection object is closed during the exchange operation • if the card is removed after connection is established and then reinserted, and attempt is made to change PIN without re-establishing the connection

SecurityException - - is thrown if the J2ME application does not have appropriate rights to ask for changing the PIN value.

IOException - - is thrown if the PIN could not be communicated with the card because the connection was closed before this method was called or because of communication problems.

Since:

BlackBerry API 4.2.1

getATR

byte[] getATR()

Returns the Answer To Reset (ATR) message sent by the smart card in response to the reset operation. ATR is received from the card when the card is powered up or when it is reset. The implementation MUST detect the presence of the card when this method is called and return the value of ATR if the card is present and null if the card has been removed.

Returns:

the ATR message if the card is inserted, or null if the card has been removed or the connection has been closed.

Since:

BlackBerry API 4.2.1

changePin

byte[] changePin(int pinID)
                 throws IOException

This is a high-level method that lets the J2ME application ask the user for PIN values for changing the PIN and sending these values to the card. A call to changePin method pops up a UI that requests the user for an old or existing PIN value and the new PIN value to change the value of the PIN. The pinID field indicates which PIN is to be changed.

Parameters:

pinID - - the type of PIN the implementation is supposed to prompt the user to change.

Returns:

result of changing the PIN value which is the status word received from the smart card in the form of a byte array. This method would return null if the user cancels the request.

Throws:

IOException - - is thrown if the PIN could not be communicated with the card because the connection was closed before this method was called or because of communication problems.

InterruptedIOException - - can be thrown in any of these situations: • if this Connection object is closed during the exchange operation • if the card is removed after connection is established and then reinserted, and attempt is made to change PIN without re-establishing the connection

SecurityException - - is thrown if the J2ME application does not have appropriate rights to ask for changing the PIN value.

UnsupportedOperationException - - is thrown if the implementation does not support this method.

Since:

BlackBerry API 4.2.1

disablePin

byte[] disablePin(int pinID)
                  throws IOException

This is a high-level method that lets the J2ME application ask for the user PIN value for the PIN that is to be disabled and send it to the card. A call to disablePin method pops up a UI that requests the user to enter the value for the PIN that is to be disabled. The pinID field indicates which PIN is to be disabled.

Parameters:

pinID - - the type of PIN the implementation is required to prompt the user to enter.

Returns:

result of disabling the PIN value which is the status word received from the smart card in the form of a byte array. This method would return null if the user cancels the request.

Throws:

IOException - - is thrown if the PIN could not be communicated with the card because the connection was closed before this method was called or because of communication problems.

InterruptedIOException - - can be thrown in any of these situations: • if this Connection object is closed during the exchange operation • if the card is removed after connection is established and then reinserted, and attempt is made to change PIN without re-establishing the connection

SecurityException - - is thrown if the J2ME application does not have appropriate rights to ask for changing the PIN value.

UnsupportedOperationException - - is thrown if the implementation does not support this method.

Since:

BlackBerry API 4.2.1

enablePin

byte[] enablePin(int pinID)
                 throws IOException

This is a high-level method that lets the J2ME application ask for the user to enter the value for the PIN that is to be enabled and send it to the card. A call to enablePin method pops up a UI that requests the user to enter the value for the PIN that is to be enabled. The pinID field indicates which PIN is to be enabled.

Parameters:

pinID - - the type of PIN the implementation is required to prompt the user to enter.

Returns:

result of enabling the PIN value which is the status word received from the smart card in the form of a byte array. This method would return null if the user cancels the request.

Throws:

IOException - - is thrown if the PIN could not be communicated with the card because the connection was closed before this method was called or because of communication problems.

InterruptedIOException - - can be thrown in any of these situations: • if this Connection object is closed during the exchange operation • if the card is removed after connection is established and then reinserted, and attempt is made to change PIN without re-establishing the connection

SecurityException - - is thrown if the J2ME application does not have appropriate rights to ask for changing the PIN value.

UnsupportedOperationException - - is thrown if the implementation does not support this method.

Since:

BlackBerry API 4.2.1

enterPin

byte[] enterPin(int pinID)
                throws IOException

This is a high-level method that lets the J2ME application ask for the user PIN value for PIN verification purposes and send it to the card. A call to enterPin method pops up a UI that requests the PIN from the user. The pinID field indicates which PIN must be requested from the user.

Parameters:

pinID - - the type of PIN the implementation is supposed to prompt the user to enter.

Returns:

result of PIN verification which is the status word received from the smart card in the form of a byte array. This method would return null if the user cancels the request.

Throws:

IOException - - is thrown if the PIN could not be communicated with the card because the connection was closed before this method was called or because of communication problems.

InterruptedIOException - - can be thrown in any of these situations: • if this Connection object is closed during the exchange operation • if the card is removed after connection is established and then reinserted, and attempt is made to change PIN without re-establishing the connection

SecurityException - - is thrown if the J2ME application does not have appropriate rights to ask for changing the PIN value.

UnsupportedOperationException - - is thrown if the implementation does not support this method.

Since:

BlackBerry API 4.2.1

unblockPin

byte[] unblockPin(int blockedPinID,
                  int UnblockingPinID)
                  throws IOException

This is a high-level method that lets the J2ME application ask the user to enter the value for an unblocking PIN, and the new value for the blocked PIN and send these to the card. A call to unblockPin method pops up a UI that requests the user to enter the value for the unblocking PIN and the new value for the blocked PIN. The unblockingPinID field indicates which unblocking PIN is to be used to unblock the blocked PIN which is indicated by the field blockedPinID.

Parameters:

blockedPinID - - the ID of PIN that is to be unblocked.

UnblockingPinID - - the ID of unblocking PIN.

Returns:

result of unblocking the PIN value which is the status word received from the smart card in the form of a byte array. This method would return null if the user cancels the request.

Throws:

IOException - - is thrown if the PIN could not be communicated with the card because the connection was closed before this method was called or because of communication problems.

InterruptedIOException - - can be thrown in any of these situations: • if this Connection object is closed during the exchange operation • if the card is removed after connection is established and then reinserted, and attempt is made to change PIN without re-establishing the connection

SecurityException - - is thrown if the J2ME application does not have appropriate rights to ask for changing the PIN value.

UnsupportedOperationException - - is thrown if the implementation does not support this method.

Since:

BlackBerry API 4.2.1