Java Card TechnologyCh08: Working with APDUs

Instructors: Instructors:

Fu-Chiung Cheng Fu-Chiung Cheng

((鄭福炯鄭福炯 ))

Associate Professor Associate Professor

Computer Science & EngineeringComputer Science & Engineering

Tatung UniversityTatung University

APDU revisit APDU – application protocol data units.APDU – application protocol data units. APDUs APDUs

data packets; data packets; application-level communication protapplication-level communication prot

ocol between the application on card ocol between the application on card and host.and host.

APDU Class

The APDU class in the java card APIs provideThe APDU class in the java card APIs provides a powerful interface for handling APDUs whs a powerful interface for handling APDUs whose command and response structures confoose command and response structures conform to ISO 7816-4 specification.rm to ISO 7816-4 specification.

Two transport protocol are in primary use:Two transport protocol are in primary use: T=0:byte-oriented;T=0:byte-oriented; T=1:block-orientedT=1:block-oriented

APDUs Class(Cont.)

The T=0 and T=1 protocols are hidden fThe T=0 and T=1 protocols are hidden from applet developers with APDUs clasrom applet developers with APDUs class.s.

APDUs class provides an object-orienteAPDUs class provides an object-oriented way of handling APDUs d way of handling APDUs receiveing and sending APDUs by invreceiveing and sending APDUs by inv

oking methods defined in the APDUs oking methods defined in the APDUs class.class.

APDU object

APDU buffer: JCRE creates an APDU APDU buffer: JCRE creates an APDU object that encapsulates APDU object that encapsulates APDU message in an internal byte array, message in an internal byte array, called APDU buffer.called APDU buffer.

The APDU object can be viewed as a The APDU object can be viewed as a communication object.communication object.

APDU object (Cont.)

When receiving an APDU command, JCREWhen receiving an APDU command, JCRE writes the APDU header in the APDU writes the APDU header in the APDU

buffer and then buffer and then invokes process method of the current invokes process method of the current

select applet.select applet. delivers the APDU object as method delivers the APDU object as method

parameters parameters When sending data to host, JCRE also writes When sending data to host, JCRE also writes

the response data into APDU buffer and send the response data into APDU buffer and send to host.to host.

APDU Buffer size

ADPU buffer is required to be at least ADPU buffer is required to be at least 37 bytes37 bytes 5 bytes of header plus the default 5 bytes of header plus the default

information field size on card (IFSC).information field size on card (IFSC). IFSC is defied in ISO 7816-3 for the IFSC is defied in ISO 7816-3 for the

T=1 protocol.T=1 protocol.

Working with APDUs in Applet

Command APDUCommand APDU Response APDU

case1

case2

case3

case4

header

header Le

header Lc data

header Lc data Le

SW

DATA SW

SW

DATA SW

Interface ISO7816

Define constants that are used to index into Define constants that are used to index into APDU buffer:APDU buffer: OFFSET_CLA: CLA byte in APUD bufferOFFSET_CLA: CLA byte in APUD buffer OFFSET_ INS, OFFSET_P1, OFFSET_P2OFFSET_ INS, OFFSET_P1, OFFSET_P2

Define response status words: e.g. 0x9000Define response status words: e.g. 0x9000 CLA and INS constants of Select and external CLA and INS constants of Select and external

authenticate APUD commandsauthenticate APUD commands

Working with APDUs in Applet

Applet handles APDU commands in Applet handles APDU commands in proprocess cess method.method.

An applet retrieves An applet retrieves a reference to APDU buffer by invokina reference to APDU buffer by invokin

g the getBuffer method and g the getBuffer method and the length by using apdu_buffer.lengtthe length by using apdu_buffer.lengt

hh

Retrieve the APDU buffer

SAMPLE :SAMPLE :

Public void process(APDU apdu) {// retrieve the APDU bufferbyte[] apdu_buffer = apdu.getBuffer();

}

Examine the Command APDU Header

When an applet’s process method is When an applet’s process method is invoked, only the first 5 bytes are invoked, only the first 5 bytes are available in the APDU bufferavailable in the APDU buffer

The fist 4 bytes are APDU header The fist 4 bytes are APDU header [CLA,INS,P1,P2] and the fifth byte(P3) [CLA,INS,P1,P2] and the fifth byte(P3) is an additional length field.is an additional length field.

Examine the Command APDU Header

The meaning of P3 is implicit determineThe meaning of P3 is implicit determined by the case of command:d by the case of command: Case1: P3 = 0Case1: P3 = 0 Case2: P3=Le, the length of outgoing Case2: P3=Le, the length of outgoing

response data.response data. Case3 and 4: P3=Lc, the length of incCase3 and 4: P3=Lc, the length of inc

oming command data.oming command data.

Examine the Command APDU Header When applet obtains the APDU buffer, it When applet obtains the APDU buffer, it

should first examine the APDU header to should first examine the APDU header to determine whether command is well determine whether command is well formatted and whether the command can be formatted and whether the command can be executed.executed. Well formatted: the header bytes are Well formatted: the header bytes are

encoded correctly.encoded correctly. Can be executed: the command is Can be executed: the command is

supported by the applet and the internal supported by the applet and the internal and security conditions are met.and security conditions are met.

Examine the Command APDU Header

For example, the following code For example, the following code fragment examines the CLA byte: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:The APDU header offset define:

Constant nameConstant name Meaning Meaning ValueValue

OFFSET_CLAOFFSET_CLA Offset to the CLA filed in the Offset to the CLA filed in the APDU bufferAPDU buffer

OFFSET_CLA = 0OFFSET_CLA = 0

OFFSET_INSOFFSET_INS Offset to the INS filed in the Offset to the INS filed in the APDU bufferAPDU buffer

OFFSET_INS = 1OFFSET_INS = 1

OFFSET_P1OFFSET_P1 Offset to the P1 filed in the Offset to the P1 filed in the APDU bufferAPDU buffer

OFFSET_P1 = 2OFFSET_P1 = 2

OFFSET_P2OFFSET_P2 Offset to the P2 filed in the Offset to the P2 filed in the APDU bufferAPDU buffer

OFFSET_P2 =3OFFSET_P2 =3

Receive APDU Command Data In case 3 and 4 type, the command APIn case 3 and 4 type, the command AP

DU has incoming data as part as instrucDU has incoming data as part as instruction. tion.

The applet can find out size from the Lc The applet can find out size from the Lc field (the fifth byte in APDU buffer).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 To read data into the APDU buffer, the applet

invokes the setIncomingAndReceive method.invokes the setIncomingAndReceive method. The method has two tasks. The method has two tasks.

First, it sets JCRE into First, it sets JCRE into data-receivingdata-receiving mod mode.e.

Next it requests JCRE to receive the incomNext it requests JCRE to receive the incoming command data bytes, starting at offset Iing command data bytes, starting at offset ISO7816.OFFSET_DATA(=5) in APDU buffSO7816.OFFSET_DATA(=5) in APDU buffer.er.

Receive Long Command Data

For a command APDU that has more daFor a command APDU that has more data bytes that can fit into the APDU buffer,ta bytes that can fit into the APDU buffer, we must receive long data by using rec we must receive long data by using receiveBytes method.eiveBytes method.

See Fig 8.2 on page 91 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] The APDU header [CLA, INS, P1, P2] identifies an instruction that applet should identifies an instruction that applet should perform.perform.

The applet should process the command data The applet should process the command data in APDU buffer if command is case 3 or 4 in APDU buffer if command is case 3 or 4 type and generate the response data if type and generate the response data if command is case 2 or 4 type.command is case 2 or 4 type.

To reduce memory usage, APDU buffer is To reduce memory usage, APDU buffer is used as a scratch pad for holding the used as a scratch pad for holding the intermediate result or response data. intermediate result or response data.

Return APDU Response Data

After completing the instruction specified in thAfter completing the instruction specified in the command APDU, the applet can return data e command APDU, the applet can return data to host.to host.

The applet calls the setOutgoing method to sThe applet calls the setOutgoing method to set the half-duplexed channel.et the half-duplexed channel.

The setOutgoing method sets the JCRE to thThe setOutgoing method sets the JCRE to the data-send mode by resetting the data transfe data-send mode by resetting the data transfer direction to outbound.er direction to outbound.

public short setOutgoing() throws APDUException

Return APDU Response Data

Unlike setIncomingAndReceive method Unlike setIncomingAndReceive method for reading data, the setOutgoing methofor reading data, the setOutgoing method doesn’t send any byte; it just set transfd doesn’t send any byte; it just set transfer mode.er mode.

Once setOutgoing method is called, any Once setOutgoing method is called, any remaining incoming data will be discardremaining incoming data will be discarded.ed.

Return APDU Response Data

After invoke the setOutgoing method, thAfter invoke the setOutgoing method, the Applet must call the setOutgoingLengte Applet must call the setOutgoingLength to indicate to the host how many total h to indicate to the host how many total response data byte(Not including SW) it response data byte(Not including SW) it will be send.will be send.

To actually send out response data, the To actually send out response data, the sendBytes method will be called.sendBytes method will be called.

public void sendByte(short b0ff, short len)throws APDUException

Return APDU Response Data

The sendBytes method send the len bytThe sendBytes method send the len bytes of data from the APDU buffer at speces of data from the APDU buffer at specified offset b0ff.ified offset b0ff.

public void sendByte(short b0ff, short len)throws APDUException

Return APDU Response Data

The methods setOutgoin, setOutgoingLThe methods setOutgoin, setOutgoingLength, and sendByte must be invoked in ength, and sendByte must be invoked in the correct order.the correct order.

To reduce overhead, the APDU class prTo reduce overhead, the APDU class provide the convenient method setOutgoiovide the convenient method setOutgoingAndSend for sending out data.ngAndSend for sending out data.

public void setOutgoingAndSend(short b0ff,short len)throws APDUException

Return APDU Response Data

setOutgoingAndSend method implemensetOutgoingAndSend method implements following tasks:ts following tasks: Sets the transfer mode to sendSets the transfer mode to send Sets the response data length to lenSets the response data length to len Sends the response data bytes from tSends the response data bytes from t

he APDU buffer at the offset b0ffhe APDU buffer at the offset b0ff

public void sendByte(short b0ff, short len)throws APDUException

Sending Data from Other Location The methods sendBytes and setOutgoinThe methods sendBytes and setOutgoin

gAndSend both send data from the APDgAndSend both send data from the APDU buffer. U buffer.

If data is stored in the applet’s local buffIf data is stored in the applet’s local buffer or in file, the applet must copy the dater or in file, the applet must copy the data into APDU buffer or using sendBytesLa into APDU buffer or using sendBytesLong method.ong method.

public void sendBytesLong(byte[] outData,short b0ff,short len) throws APDUException

Example

Page 95 & 96Page 95 & 96

Return the Status Word

One invocation to an applet’s process method One invocation to an applet’s process method involves exchanging a C-APDU and a R-involves exchanging a C-APDU and a R-APDU between the host and the applet.APDU between the host and the applet.

In the process method, the applet first reads In the process method, the applet first reads the command APDU received, then write the command APDU received, then write response data to be sent out. response data to be sent out.

The “end” state is reached by setting the The “end” state is reached by setting the response APDU status word.response APDU status word.

One of three may occur at this step.One of three may occur at this step.

Return the Status Word

1.1. On normal return, JCRE automatically sendOn normal return, JCRE automatically sends completion bytes (0x9000) to the host.s completion bytes (0x9000) to the host.

2.2. At any point during the command processinAt any point during the command processing, if an error occurs, the applet terminates tg, if an error occurs, the applet terminates the operation and throws an ISOException bhe operation and throws an ISOException by invoking the static method ISOException.ty invoking the static method ISOException.throwIt(reason).hrowIt(reason).

Return the Status Word

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

Protocol-Specific APDU Processing1.1. public static byte getProtocol()public static byte getProtocol()2.2. public static short getInBlockSize()public static short getInBlockSize()3.3. public static short getOutBlockSize()public static short getOutBlockSize()4.4. public short setOutgoingNoChaining() public short setOutgoingNoChaining()

throws APDUExceptionthrows APDUException5.5. public byte getNAD()public byte getNAD()6.6. public byte waitExtension()public byte waitExtension()