Writing a Java Card Applet, Part 2

This section continues the Processing Requests discussion started in Part 1 of this article.

• Processing Requests, continued
• Java Card Reference
• Java Card Classes Used in the Wallet Applet
• Java Card Methods Used in the Wallet Applet
• Java Card Interfaces Used in the Wallet Applet
• APDU Formats
• More Information

Processing Requests, continued

The last steps to processing the request include:

• Debit an Amount from the Current Balance
• Get the Current Balance
• Validate the PIN

Debit an Amount from the Current Balance

The debit method in the Wallet applet debits an amount from the current balance. As is the case for the credit method, the debit method is called with one parameter: an APDU object. The APDU object encapsulates an APDU buffer that contains the DEBIT command APDU. The amount to be debited from the current balance is in the data field of the APDU.

private void debit(APDU apdu) {

The code in the debit method is similar to that in the credit method. Both methods:

• Check the PIN for validation
• Get a reference to the APDU buffer
• Access the Lc byte in the APDU buffer to determine the number of bytes of incoming data
• Read the incoming data into the APDU buffer
• Check that the number of bytes read into the APDU buffer is the same as the value of the Lc byte
• Get the data from the APDU buffer
• Check that the data amount does not violate the maximum transaction limit specified by the MAX_TRANSACTION_AMOUNT constant, or is less than 0

For more details about these steps, see Credit an Amount to the Current Balance.

Where debit differs from credit is that the data in the APDU reflects the amount to be debited from the current balance (as opposed to credited to the balance). After the debit method performs the steps above, it subtracts the debit amount from the current balance and checks to ensure that the new balance isn't less than 0. Here is body of the debit method:

// access authentication

if ( ! pin.isValidated() )
ISOException.throwIt
(SW_PIN_VERIFICATION_REQUIRED);

byte[] buffer = apdu.getBuffer();

byte numBytes =
(byte)(buffer[ISO7816.OFFSET_LC]);

byte byteRead =
(byte)(apdu.setIncomingAndReceive());

if ( ( numBytes != 1 ) || (byteRead != 1) )
ISOException.throwIt
(ISO7816.SW_WRONG_LENGTH);

// get debit amount
byte debitAmount =
buffer[ISO7816.OFFSET_CDATA];

// check debit amount
if ( ( debitAmount > MAX_TRANSACTION_AMOUNT)
||  ( debitAmount < 0 ) )
isoexception.throwit
(sw_invalid_transaction_amount);

// check the new balance
if ( (short)( balance - debitamount ) < (short)0 )
isoexception.throwit(sw_negative_balance);

balance = (short) (balance - debitamount);

} // end of debit method

As is the case for credit method, the JCRE indicates successful processing of the command APDU by sending a response APDU to the host application that contains the status word value 0x9000.

Get the Current Balance

The getBalance method in the Wallet applet returns the value of the current balance. The method is called with one parameter: an APDU object. The APDU object encapsulates an APDU buffer that contains the GET BALANCE command APDU. The value of the current balance is returned in the data field of the GET BALANCE response APDU.

private void getBalance(APDU apdu) {

The getBalance method first gets a reference to the APDU buffer (for more details, see Get a Reference to the APDU buffer):

byte buffer[] = apdu.getBuffer();

Unlike the credit and debit methods that read incoming data in a command APDU and then process it, the getBalance method does its processing (that is, gets the current balance) and then writes data for inclusion in a response APDU. It does this by first calling the APDU method setOutgoing. This tells the JCRE that the Java Card applet wants to send a response. The setOutgoing method doesn't send any data. It sets the JCRE to data-send mode. It also accesses and returns the value in the Le byte of the command APDU. As illustrated in APDU Formats, the Le byte indicates the maximum number of bytes expected in response to the command. Notice that the Le byte value for the GET BALANCE command should be 2. The getBalance method checks the Le value; if the value is not 2, the method throws an exception with a constant that is returned in the status word of the response APDU:

// inform system that the applet has finished

// processing the command and the system should
// now prepare to construct a response APDU
// which contains data field
short le = apdu.setOutgoing();

if ( le < 2 )
isoexception.throwit
(iso7816.sw_wrong_length);

getbalance then calls the APDU method setOutgoingLength to specifiy how many bytes of data are actually in the response -- here it's two bytes. The length is specified as a parameter to setOutgoingLength:

//informs the CAD the actual number of bytes

//returned
apdu.setOutgoingLength((byte)2);

Then getBalance moves the balance amount into the first two bytes of the APDU buffer. Notice the shift and bitwise "and" operations performed on the balance value before it is moved into the buffer; these operations correctly produce the values for the two bytes.

// move the balance data into the APDU buffer

// starting at the offset 0
buffer[0] = (byte)(balance >> 8);
buffer[1] = (byte)(balance & 0xFF);

An alternative technique for moving the balance data into the APDU buffer is to use the following method call:

Util.setShort(buffer, (short)0, balance);

setShort is a method defined in the javacard.framework.Util class. It moves a short value (here, the balance) as two successive bytes at the specified offset (offset 0), into a byte array (the APDU buffer).

The last step in the process is to send the data by calling the APDU method sendBytes. The sendBytes method accepts two parameters: the offset into the APDU buffer where the data begins, and the length of the data. Here, the getBalance method sends the two bytes in the APDU buffer starting at offset 0:

// send the 2-byte balance at the offset

// 0 in the apdu buffer
apdu.sendBytes((short)0, (short)2);

} // end of getBalance method

As is the case for the credit and debit methods, the JCRE indicates successful processing of the command APDU by sending a status word value of 0x9000 in the response APDU to the host application.

Validate the PIN

The verify method in the Wallet applet validates the PIN. The method is called with one parameter: an APDU object. The APDU object encapsulates an APDU buffer that contains the VERIFY command APDU. The PIN to be validated is in the data field of the APDU.

private void verify(APDU apdu) {

The verify method first gets a reference to the APDU buffer (for more details, see Get a Reference to the APDU buffer):

byte buffer[] = apdu.getBuffer();

verify then calls the APDU method setIncomingAndReceive to get the PIN to be validated from the command APDU and put it in the APDU buffer:

// retrieve the PIN data for validation.

byte byteRead =
(byte)(apdu.setIncomingAndReceive());

verify then checks the PIN by calling the OwnerPIN method check:

// check pin

// the PIN data is read into the APDU buffer
// at the offset ISO7816.OFFSET_CDATA
// the PIN data length = byteRead
if ( pin.check(buffer, ISO7816.OFFSET_CDATA,
byteRead) == false )
ISOException.throwIt
(SW_VERIFICATION_FAILED);

} // end of validate method
} // end of class Wallet

Notice that the check method is called with three parameters:

• A byte array that contains the PIN to be validated
• The offset into the array for the PIN -- the ISO7816 interface constant OFFSET_CDATA is used as the index
• The length of the PIN

The check method checks the PIN in the APDU buffer against a PIN established when the applet was installed. If the values match, the check method returns a true value. It also sets a flag to indicate that the PIN is validated, and resets a try counter to the maximum value for the applet. Recall that for the Wallet applet the maximum number of tries as set by PIN_TRY_LIMIT is 3. If the values do not match, check returns a false value. In that case, it throws an exception with a constant that is returned in the status word of the response APDU. It also decrements the try counter. If the value of the try counter is 0, check blocks the PIN; this means that no further processing can be performed by the applet for this user.

Java Card Reference

Java Card Classes Used in the Wallet Applet

Java Card Methods Used in the Wallet Applet

The following Java Card methods are used in the Wallet applet.

javacard.framework.APDU Methods Used in the Wallet Applet

javacard.framework.Applet Methods Used in the Wallet Applet

javacard.framework.OwnerPIN Methods Used in the Wallet Applet

Java Card Interfaces Used in the Wallet Applet

APDU Formats

The following is the format of a command APDU. The SELECT APDU command is the only APDU command that is standardized on the Java Card platform. The values in the header of a SELECT APDU command must be as indicated below. The header values for all other command APDU's are applet specific.

The following is the format of a response APDU:

More Information

Java Card 2.1.1 Specifications

Java Card Technology Questions and Answers with Zhiqun Chen

About the Author: Ed Ort is a staff member of the Java Developer Connection. He has written extensively about relational database technology and programming languages.