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

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

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 7816-4 specification. Two transport protocol are in primary use: T=0:byte-oriented; T=1:block-oriented

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.

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.

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.

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 7816-3 for the T=1 protocol.

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

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

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

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

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.

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.

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.

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); }

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

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);

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.

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

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.

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

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.

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

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

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

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

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

Example Page 95 & 96

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.

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).

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)

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()