1. Java Card Technology Ch08: Working with APDUs
Instructors:
Fu-Chiung Cheng
(鄭福炯)
Associate Professor
Computer Science & Engineering
Tatung University

2. APDU revisit APDU – application protocol data units. APDUs
data packets;
application-level communication protocol between the application on card and host.

3. APDU Class
The APDU class in the java card APIs provides a powerful interface for handling APDUs whose command and response structures conform to ISO specification.
Two transport protocol are in primary use:
T=0:byte-oriented;
T=1:block-oriented

4. APDUs Class(Cont.)
The T=0 and T=1 protocols are hidden from applet developers with APDUs class.
APDUs class provides an object-oriented way of handling APDUs
receiveing and sending APDUs by invoking methods defined in the APDUs class.

5. APDU object
APDU buffer: JCRE creates an APDU object that encapsulates APDU message in an internal byte array, called APDU buffer.
The APDU object can be viewed as a communication object.

6. APDU object (Cont.) When receiving an APDU command, JCRE
writes the APDU header in the APDU buffer and then
invokes process method of the current select applet.
delivers the APDU object as method parameters
When sending data to host, JCRE also writes the response data into APDU buffer and send to host.

7. APDU Buffer size ADPU buffer is required to be at least 37 bytes
5 bytes of header plus the default information field size on card (IFSC).
IFSC is defied in ISO for the T=1 protocol.

8. Working with APDUs in Applet
Command APDU
Response APDU SW
case1
header
DATA SW
case2
header Le
case3 SW
header Lc
data
case4
header Lc
data Le
DATA SW

9. Interface ISO7816
Define constants that are used to index into APDU buffer:
OFFSET_CLA: CLA byte in APUD buffer
OFFSET_ INS, OFFSET_P1, OFFSET_P2
Define response status words: e.g. 0x9000
CLA and INS constants of Select and external authenticate APUD commands

10. Working with APDUs in Applet
Applet handles APDU commands in process method.
An applet retrieves
a reference to APDU buffer by invoking the getBuffer method and
the length by using apdu_buffer.length

11. Retrieve the APDU buffer
SAMPLE :
Public void process(APDU apdu) {
// retrieve the APDU buffer
byte[] apdu_buffer = apdu.getBuffer(); }

12. Examine the Command APDU Header
When an applet’s process method is invoked, only the first 5 bytes are available in the APDU buffer
The fist 4 bytes are APDU header [CLA,INS,P1,P2] and the fifth byte(P3) is an additional length field.

13. Examine the Command APDU Header
The meaning of P3 is implicit determined by the case of command:
Case1: P3 = 0
Case2: P3=Le, the length of outgoing response data.
Case3 and 4: P3=Lc, the length of incoming command data.

14. Examine the Command APDU Header
When applet obtains the APDU buffer, it should first examine the APDU header to determine whether command is well formatted and whether the command can be executed.
Well formatted: the header bytes are encoded correctly.
Can be executed: the command is supported by the applet and the internal and security conditions are met.

15. Examine the Command APDU Header
For example, the following code fragment examines the CLA byte:
If (apdu_buffer[ISO7816.OFFSET_CLA] != EXPECTED_VALUE) {
ISOException.throw(ISO7816.SW_CLA_NOT_SUPPORTED); }

16. Examine the Command APDU Header
The APDU header offset define:
Constant name
Meaning
Value
OFFSET_CLA
Offset to the CLA filed in the APDU buffer
OFFSET_CLA = 0
OFFSET_INS
Offset to the INS filed in the APDU buffer
OFFSET_INS = 1
OFFSET_P1
Offset to the P1 filed in the APDU buffer
OFFSET_P1 = 2
OFFSET_P2
Offset to the P2 filed in the APDU buffer
OFFSET_P2 =3

17. Receive APDU Command Data
In case 3 and 4 type, the command APDU has incoming data as part as instruction.
The applet can find out size from the Lc field (the fifth byte in APDU buffer).
short data_length = (short)
(apdu_buffer[ISO7816.OFFSET_LC] & 0xFF);

18. Receive APDU Command Data
To read data into the APDU buffer, the applet invokes the setIncomingAndReceive method.
The method has two tasks.
First, it sets JCRE into data-receiving mode.
Next it requests JCRE to receive the incoming command data bytes, starting at offset ISO7816.OFFSET_DATA(=5) in APDU buffer.

19. Receive Long Command Data
For a command APDU that has more data bytes that can fit into the APDU buffer, we must receive long data by using receiveBytes method.
See Fig 8.2 on page 91
APDU buffer
Command Data
public short reciveBytes(short boff)
throws APDUException

20. Process the APDU Command and Generate the Response Data
The APDU header [CLA, INS, P1, P2] identifies an instruction that applet should perform.
The applet should process the command data in APDU buffer if command is case 3 or 4 type and generate the response data if command is case 2 or 4 type.
To reduce memory usage, APDU buffer is used as a scratch pad for holding the intermediate result or response data.

21. Return APDU Response Data
After completing the instruction specified in the command APDU, the applet can return data to host.
The applet calls the setOutgoing method to set the half-duplexed channel.
The setOutgoing method sets the JCRE to the data-send mode by resetting the data transfer direction to outbound.
public short setOutgoing() throws APDUException

22. Return APDU Response Data
Unlike setIncomingAndReceive method for reading data, the setOutgoing method doesn’t send any byte; it just set transfer mode.
Once setOutgoing method is called, any remaining incoming data will be discarded.

23. Return APDU Response Data
After invoke the setOutgoing method, the Applet must call the setOutgoingLength to indicate to the host how many total response data byte(Not including SW) it will be send.
To actually send out response data, the sendBytes method will be called.
public void sendByte(short b0ff, short len)
throws APDUException

24. Return APDU Response Data
The sendBytes method send the len bytes of data from the APDU buffer at specified offset b0ff.
public void sendByte(short b0ff, short len)
throws APDUException

25. Return APDU Response Data
The methods setOutgoin, setOutgoingLength, and sendByte must be invoked in the correct order.
To reduce overhead, the APDU class provide the convenient method setOutgoingAndSend for sending out data.
public void setOutgoingAndSend(short b0ff,short len)
throws APDUException

26. Return APDU Response Data
setOutgoingAndSend method implements following tasks:
Sets the transfer mode to send
Sets the response data length to len
Sends the response data bytes from the APDU buffer at the offset b0ff
public void sendByte(short b0ff, short len)
throws APDUException

27. Sending Data from Other Location
The methods sendBytes and setOutgoingAndSend both send data from the APDU buffer.
If data is stored in the applet’s local buffer or in file, the applet must copy the data into APDU buffer or using sendBytesLong method.
public void sendBytesLong(byte[] outData,short b0ff,
short len) throws APDUException

28. Example
Page 95 & 96

29. Return the Status Word
One invocation to an applet’s process method involves exchanging a C-APDU and a R-APDU between the host and the applet.
In the process method, the applet first reads the command APDU received, then write response data to be sent out.
The “end” state is reached by setting the response APDU status word.
One of three may occur at this step.

30. Return the Status Word
On normal return, JCRE automatically sends completion bytes (0x9000) to the host.
At any point during the command processing, if an error occurs, the applet terminates the operation and throws an ISOException by invoking the static method ISOException.throwIt(reason).

31. Return the Status Word
If an error is detected by underlying JAVA CARD system, the behavior of JCRE is undefined. For example, the JCRE may not implement the handler for each type of exception, it will return ISO7816.SW_UNKNOWN(0x6F00)

32. Protocol-Specific APDU Processing
public static byte getProtocol()
public static short getInBlockSize()
public static short getOutBlockSize()
public short setOutgoingNoChaining() throws APDUException
public byte getNAD()
public byte waitExtension()