Application Protocol Data Unit

T-110.497 Smart Card Application Development

Markku Sievänen

2

Contents

� Smart Card communications basics� APDU protocol� Programming with APDUs

3

Smart Card Communication

� Card Acceptance Device (CAD)� supply the cards with power

� half-duplexed communcation model� master-slave model

� CAD is the master, Card is the slave

INACTIVE ACTIVE

Command APDU

Response APDU

PROCESS COMMANDS

4

APDU Protocol � APDU = Application Protocol Data Unit� Spedified in ISO 7816-4� Command APDU (C-APDU)

� From CAD to Card� Response APDU (R-APDU)

� From Card to CAD

C-APDU

R-APDU

5

APDU - Command

� Command Bytes� CLA = Class of Instruction

� Category, SM, Channel

� INS = Instruction� P1, P2 = Parameters 1 and 2� Lc = Lenght of the Command data� Command data� Le = Length of the Expected response

CLA INS P1 P2 Lc DATA Le

COMMAND APDU:Mandatory header Optional body

6

Example of C-APDU

� SELECT FILE� CLA = ’0X’;� INS = ’A4’;� P1 =

� ’00’ – select EF, DF, or MF by file identifier� ’04’ – select DF by Application Identifier� ’08’ – select file by absolute path from MF� ’09’ – select file by relative path fromcurrent DF

� P2 = ’00’ – FCI returned in response� Lc = Empty or length of the subsequent data field� Data = according the P1 field� Le =empty or maximum length of data expected in response

MF

DF

EF EFDF

EF EF DF

EF

7

APDU - Response

� Response Bytes� Response Data� SW1,SW2 = Status Word 1 and 2

RESPONSE APDU:

DATA SW1 SW2

Optional Body Mandatory Trailer

8

Example of R-APDU

� SELECT FILE� Data – FCI (File Control Information)� SW1-SW2

� ’9000’ – OK � ’6283’ – Warning, selected file is deactivated� ’6400’ – Execution error� ’6A81’ – Function not supported� ’6A82’ – File not found� ’6A86’ – Incorrect parametrs P1-P2� ’6A87’ – Lc inconsistent with P1-P2

9

APDU – four cases (1)

CLA INS P1 P2 Le

DATA SW1 SW2

C-APDU:

R-APDU:

CASE 2:

CLA INS P1 P2

SW1 SW2

C-APDU:

R-APDU:

CASE 1:

10

APDU – four cases (2)

CLA INS P1 P2 Lc DATA Le

DATA SW1 SW2

C-APDU:

R-APDU:

CASE 4:

CLA INS P1 P2 Lc DATA

SW1 SW2

C-APDU:

R-APDU:

CASE 3:

11

TPDU

� TPDU = Transmission Protocol Data Unit� APDUs are transmitted by TPDUs� Defined in 7816-3� The most used protocols today

� T = 0, byte-oriented� T = 1, block-oriented� T = CL, contactless protocol

12

ATR

� ATR = Answer To Reset� After smard card is powered up, it sends ATR

message to the host� Up to 33 bytes� Contains transmission parameters:

� supported transport protocol� data transmission rate� card hardware parameters

13

Programming wih APDUs (1)

� class javacard.framework.APDU� interface for handling ISO 7816-4 based APDUs� hides the underlying transport protocol� When receiving command message from CAD JCRE:

� Creates an instance of APDU class with internal APDU buffer containing the command header

� Invokes the process method of the currently selected applet� If applet contains data, the applet can call methods on the

APDU to receive data� After processing the command, applet call the methods on the

APDU to send the response

14

Programming wih APDUs (2)

� Retrieve the APDU buffer� public void process(APDU apdu)

byte[] apdu_buffer = apdu.getBuffer();// Determine the length.length = apdu_buffer.length

� the reference to the APDU buffer cannot be storedin class variables, instance variables or array components, only in local variables and method parameters

15

APDU buffer size

� For interoperability: required to be at least 37bytes

� Normally bigger (255 bytes)

16

Interface ISO7816

� provides set of contants related to ISO 7816-3 and 7816-4� Constants that are used to index into APDU buffer

(OFFSET_CLA)� ISO 7816-4 defined response status words� CLA and INS constants

17

Step 1 in process() method: examine theCommand APDU Header

� 5 bytes available� [CLA, INS, P1, P2] and P3� Depending of the APDU case

� case 1: P3 = 0� case 2: P3= Le� case 3 and 4: P3=Lc

� Check that bytes are coded correctly, values are supported by applet and security conditions are met

� if (apdu_buffer[ISO7816.OFFSET_INS] != SUPPORTED_VALUE) {ISOException.throwIt(ISO7816.SW_INS_NOT_SUPPORTED);

}

18

Step 2 in process() method: receive theCommand APDU data

� Case 3 and 4� short total_bytes = (short) (apdu_buffer

[ISO7816.OFFSET_LC] & 0xFF);� NOTICE: the integer data types are signed, the most

significant bit determines whether it is a positive or negative number!

� To read data into the APDU buffer:� public short setIncomingAndReceive() throws APDUException;� short read_count = apdu.setIncomingAndReceive();

� If all data doesn’t fit into the APDU buffer� public short receiceBytes(short bOff) throws APDUException� if (read_count < total_bytes)

short read_more = apdu.receiveBytes((short)0);

19

APDU Buffer

APDU Buffer

header (5 bytes) data bytes

After calling setIncomingAndReceive:

Command APDU data

bytes read remaining bytes

After calling receiveBytes(offset):

APDU Buffer

20

Step 3 in process() method: generate response data

� Case 2 and 4: set the transfer mode� public short setOutgoing() throws APDUException;� no data is send, only the tranfer mode is set� returns the number of expected response data bytes (Le)

� set the length of the response (not including SW)� public void setOutgoingLength(short length) throws

APDUException;� send the response

� copy the response to the APDU buffer� public void sendBytes(short boff, short len) throws

APDUException;� If response doesn’t fit to the APDU buffer, update the APDU

buffer with new data and call sendBytes() again

21

Step 3 ...

� public void setOutgoingAndSend(short boff, short len) throws APDUException;� set the tranfers mode� set the response data length to len� send the response data bytes from APDU buffer at the offset

boff� response must fit completely in the APDU buffer

� sending data from other locations:� public void sendBytesLong(byte[] outData, short boff, short

len) throws APDUException;� can be called repeatedly

22

Return the Status Word

� on normal return from the process() method, the JCRE automatically send the ”OK” response bytes(0x9000) to the host

� if an error/warning occurs during process, call� ISOException.throwIt(reason);� If this exception is not handled by applet, it is caught by the

JCRE, which send the ”reason” to the host� Use ISO7816 interface for Status Word values� on errors/abnormal situations detected by JCRE, it

normally sends reason code ISO7816.SW_UNKNOWN(0x6F00);

23

Protocol-Specific APDU Processing

� public static byte getProtocol();� result: APDU.PROTOCOL_T0 or APDU.PROTOCOL_T1

� public byte waitExtension();� When the host does not receive any response for an ISO

7816-3 specified maximum time, it considers the card to be unresponsive and times out

� applet can request more processing time� not needed if the card has automatic hardware timer

� more ...

24

Case 1 – No command data, no responsedata

� Inside process() method1. Examine the first 4 bytes of the APDU buffer. The

field P3 is 0.2. Do the job requested.3. return from the process() method.

25

Case 2 – No command data, send response data

� Inside process() method:1. Examine the first 4 bytes of the APDU buffer. The field P3 is

interpreted as the Le field2. Do the job requested.3. Send the response data

� short response:� setOutGoingAndSend();

� long response� Obtain Le field: setOutGoing();� inform the host of the actual length of the response data:

setOutgoingLength();� send the response data: sendBytes() or sendBytesLong();

26

Case 3 – Receive command data, noresponse data

� Inside process() method:1. Examine the first 4 bytes of the APDU buffer. The

field P3 is interpreted as the Lc field.2. set receive mode: setIncomingAndReceive();3. receive command data: receiveBytes();

27

Case 4 – Receive command data, send response data

� combination of cases 3 and 2.� receive the command data.� send the response data.