Application Protocol Data Unit - TML

Application Protocol Data Unit

T-110.497 Smart Card Application Development Markku Sievänen

Contents




Smart Card communications basics APDU protocol Programming with APDUs

2

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 Command APDU

INACTIVE

ACTIVE

PROCESS COMMANDS

Response APDU

3

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 4

APDU - Command COMMAND APDU: Mandatory header

CLA




INS

P1

Optional body

P2

Lc

DATA

Le

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 5

Example of C-APDU


SELECT FILE




CLA = ’0X’; INS = ’A4’; P1 =











’00’ ’04’ ’08’ ’09’

– – – –

select select select select

MF

EF

DF

EF

DF EF

EF

DF

EF

EF, DF, or MF by file identifier DF by Application Identifier file by absolute path from MF 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 6

APDU - Response RESPONSE APDU: Optional Body

DATA




Mandatory Trailer

SW1

SW2

Response Bytes



Response Data SW1,SW2 = Status Word 1 and 2

7

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 8

APDU – four cases (1) CASE 1: C-APDU: R-APDU:

CLA SW1

INS

P1

P2

SW2

CASE 2: C-APDU: R-APDU:

CLA

INS DATA

P1

P2 SW1

Le SW2

9

APDU – four cases (2) CASE 3: C-APDU: R-APDU:

CLA SW1

INS

P1

P2

Lc

DATA

SW2

CASE 4: C-APDU: R-APDU:

CLA DATA

INS

P1

P2 SW1

Lc

DATA

Le

SW2

10

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

11

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 12

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

13

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 stored in class variables, instance variables or array components, only in local variables and method parameters

14

APDU buffer size





For interoperability: required to be at least 37 bytes Normally bigger (255 bytes)

15

Interface ISO7816


provides set of contants related to ISO 78163 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

16

Step 1 in process() method: examine the Command 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); }

17

Step 2 in process() method: receive the Command 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); 18

APDU Buffer After calling setIncomingAndReceive: APDU Buffer header (5 bytes)

data bytes

After calling receiveBytes(offset): APDU Buffer Command APDU data bytes read

remaining bytes 19

Step 3 in process() method: generate response data


Case 2 and 4: set the transfer mode







set the length of the response (not including SW)





public short setOutgoing() throws APDUException; no data is send, only the tranfer mode is set returns the number of expected response data bytes (Le) 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 20

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 21

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

Protocol-Specific APDU Processing


public static byte getProtocol();





public byte waitExtension();









result: APDU.PROTOCOL_T0 or APDU.PROTOCOL_T1

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

23

Case 1 – No command data, no response data


Inside process() method 1.

2. 3.

Examine the first 4 bytes of the APDU buffer. The field P3 is 0. Do the job requested. return from the process() method.

24

Case 2 – No command data, send response data


Inside process() method: 1.

2. 3.

Examine the first 4 bytes of the APDU buffer. The field P3 is interpreted as the Le field Do the job requested. 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();

25

Case 3 – Receive command data, no response data


Inside process() method: 1.

2. 3.

Examine the first 4 bytes of the APDU buffer. The field P3 is interpreted as the Lc field. set receive mode: setIncomingAndReceive(); receive command data: receiveBytes();

26

Case 4 – Receive command data, send response data


combination of cases 3 and 2.



receive the command data. send the response data.

27