Java Card Reminder

1
Java Card Reminder

• C. Boursier and P. Girard

2
Outline

• Java Card vs. Java
• Java Card Runtime Environment ?
• What is an applet ?
• How an applet is loaded onto a card ?
• How code of an applet is interpreted ?
• How do applets communicate to each other ?
• How does an applet communicate to the external
  world ?
• Exceptions

3
Java Card vs Java
4
Unsupported features (1/4)Type

• char
• double
• float
• long
• String
• multi-dimensional arraysbut array elements can
  be references to other arrays

5
Unsupported features (2/4)Dynamic class loading

• Classes are statically linked before being
  downloaded
• No way to download classes on the fly as
  needed...
• Applets only refer to classes which already exist
  on the card

Classes
Methods( )
Applet 1
6
Unsupported features (3/4)

• Security manager
• Garbage collection
• Multi-threading

Garbage collector will be supported in future
versions
7
Unsupported features (4/4)Cloning
Executing b clone(a) gives
Executing b a gives

• No clone() method in class ObjectUse
  Util.arrayCopy() instead
• Clonable interface not provided
• Creating copies of objects is critical

8
Java Card Runtime Environment
9
Java Card architecture
Java Card - OP Applet
Pure Java Card Applet 1
Pure Java Card Applet 2
Card Manager
OP/VOP 2.1.1 API
Java Card 2.1 API
Java Card 2.1 VM
Native layer
Microprocessor Memory I/O
10
Java Card Runtime Environment

• JCVM - Java Card Virtual Machine
• Byte code execution (interpretation)
• Java language support
• API - Application Programming Interface
• Framework
• Set of classes that implement the API
• Core classes
• Add-on classes
• Native methods
• I/O, cryptography, memory allocation, loader

11
Java Card Runtime Environment

• Application management
• Applet registration
• Applet selection
• Object and class management
• I/O management
• APDU dispatching
• Security enforcement
• Atomicity management

12
JCRE
13
Command dispatching

• JCREs task
• Route the incoming commands to the selected
  applet
• Applet designers task
• Implement the applets command dispatcher
  (extraction of the header information and call of
  the associated method)

14
What is an applet ?
15
Java Card applet

• javacard.framework.Applet
• Super class of all Java Card applets
• abstract class
• an applet
• a class
• extends javacard.framework.Applet
• Must implement process()(abstract method)
• Shall implement install() to allow multiple
  instances
• May override the select() and deselect() methods

16
JCVM architecture
.class
.jar
17
Applet Structure
18
1. Preparation(import tools, define constructor)

• package com.gemplus.training.code
• import javacard.framework.
• public class Counter extends javacard.framework.Ap
  plet
• private final static byte CLA_COUNTER
  (byte)0x25
• private final static byte INS_INC
  (byte)0x01
• private final static byte INS_DEC
  (byte)0x02
• private final static short MAX_COUNTER
  (short)500
• private byte counterValue
• protected Counter()
• register()
• counterValue 0

19
2. Initialization(define install and select
methods)

• public static void install(byte bArray, short
  bOffset, byte bLength) throws ISOException
• new Counter ()
• public boolean select()
• return true
• public void deselect()
• return

20
3. Command Dispatching(define process method)

• public void process(APDU apdu) throws
  ISOException
• byte apduBuffer apdu.getBuffer()
• if (selectingApplet())
• return
• switch ( apduBufferISO7816.OFFSET_INS
  )
• case INS_INC
• if(apduBufferISO7816.OFFSET_CLA
  CLA_COUNTER)
• increment(apdu)
• break
• case INS_DEC
• if(apduBufferISO7816.OFFSET_CLA
  CLA_COUNTER)
• decrease(apdu)
• break
• default

21
4. Methods(define applicative methods)

• private void increment (APDU apdu)
• byte apduBuffer apdu.getBuffer()
• byte value apduBufferISO7816.OFFSET_P1
• addCounter(value)
• private void decrease (APDU apdu)
• byte apduBuffer apdu.getBuffer()
• byte value (byte)(apduBufferISO7816.OFFSE
  T_P1 -1)
• addCounter(value)
• private void addCounter(byte value)
• counterValue value

22
How is an applet loaded onto a card ?
23
JCVM architecture
.class
.jar
24
JCVM architecture
.class
.jar
25
CAP dump
com/gemplus/training/code/javacard/Method.cap
07 00 94 00 02 10 18 8c 00 02 18 8b 00 01 18 03
88 00 7a 02 30 8f 00 03 3d 8c 00 04 3b 7a 01 10
04 78 00 10 7a 02 21 19 8b 00 05 2d 18 8b 00 06
60 03 7a 1a 04 25 75 00 29 00 02 00 01 00 0d 00
02 00 1b 1a 03 25 10 25 6b 1d 18 19 8c 00 07 70
16 1a 03 25 10 25 6b 0f 18 19 8c 00 08 70 08 11
6d 00 8d 00 09 7a 02 22 19 8b 00 05 2d 1a 05 25
32 18 1f 8c 00 0a 7a 02 22 19 8b 00 05 2d 1a 05
25 02 45 5b 32 18 1f 8c 00 0a 7a 03 20 18 3d 84
00 1d 41 5b 88 00 7a com/gemplus/training/code/jav
acard/StaticField.cap 08 00 0a 00 00 00 00 00
00 00 00 00 00 com/gemplus/training/code/javacard/
RefLocation.cap 09 00 14 00 03 0e 7f 05 00 0d
05 04 0a 04 0f 05 1f 0e 08 07 0a 07
0d com/gemplus/training/code/javacard/Descriptor.c
ap 0b 00 9e 01 00 01 00 00 00 00 01 00 08 00
02 00 00 00 80 03 00 84 00 01 00 1a 00 0d 00 00
00 00 01 09 00 10 00 28 00 09 00 00 00 00 06 01
00 1b 00 1e 00 02 00 00 00 00 04 01 00 1f 00 1a
00 01 00 00 00 00 07 01 00 22 00 20 00 3f 00 00
00 00 ff 02 00 63 00 20 00 0f 00 00 00 00 ff 02
00 74 00 20 00 12 00 00 00 00 ff 02 00 88 00 26
00 0a 00 00 00 00 00 0b 00 18 00 1a 00 1a ff ff
00 1a 00 1c 00 1e 00 20 00 20 00 24 00 26 01 30
01 10 01 b0 01 20 06 68 00 a1 02 41 02 31 04 b4
31 01 40

• com/gemplus/training/code/javacard/Header.cap
• 01 00 13 de ca ff ed 01 02 04 00 01 09 6d 79 70
• 61 63 6b 61 67 31
• com/gemplus/training/code/javacard/Directory.cap
  
• 02 00 1f 00 13 00 1f 00 0d 00 0b 00 2e 00 12 00
• 94 00 0a 00 14 00 00 00 9e 00 00 00 00 00 00 01
• 01 00
• com/gemplus/training/code/javacard/Applet.cap
• 03 00 0d 01 09 6d 79 70 61 63 30 30 30 31 00 10
• com/gemplus/training/code/javacard/Import.cap
• 04 00 0b 01 00 01 07 a0 00 00 00 62 01 01
• com/gemplus/training/code/javacard/ConstantPool.ca
  p
• 05 00 2e 00 0b 02 00 00 00 03 80 03 01 06 80 03
• 00 01 00 00 00 06 00 00 01 03 80 0a 01 03 80 03
• 03 06 00 00 63 06 00 00 74 06 80 07 01 06 00 00
• 88
• com/gemplus/training/code/javacard/Class.cap
• 06 00 12 00 80 03 01 ff 00 04 04 00 00 00 1f ff
• ff 00 1b 00 22

26
JC 2.1.1 JCRE specifications

• Applet component in the cap file
• com/gemplus/training/code/javacard/Applet.cap
• 03 00 0d 01 09 6d 79 70 61 63 30 30 30 31 00 10

• In JC 2.1.1 JCVM paragraph 6.5
• The Applet Component is described by the
  following variable-length structure
• applet_component
• u1 tag
• u2 size
• u1 count
• u1 AID_length
• u1 AIDAID_length
• u2 install_method_offset
• appletscount
• The items in the applet_component structure are
  as follows
• tag
• The tag item has the value COMPONENT_Applet (3).

27
Jca file

• .method private increment(Ljavacard/framework/APDU
  )V
• .stack 2
• .locals 2
• .descriptor Ljavacard/framework/APDU 0.10
• L0 aload_1
• invokevirtual 5 astore_2
• aload_2
• sconst_2
• baload
• sstore_3
• aload_0
• sload_3
• invokespecial 10
• return

28
Jar file for the CAP files

• M Filemode Length Date Time
  File
• - ---------- -------- ----------- --------
  --------------------------------------------------
  -
• -rw-rw-rw- 22 20-Feb-2002 133702
  com/gemplus/training/code/javacard/Header.cap
• -rw-rw-rw- 34 20-Feb-2002 133702
  com/gemplus/training/code/javacard/Directory.cap
• -rw-rw-rw- 16 20-Feb-2002 133702
  com/gemplus/training/code/javacard/Applet.cap
• -rw-rw-rw- 14 20-Feb-2002 133702
  com/gemplus/training/code/javacard/Import.cap
• -rw-rw-rw- 49 20-Feb-2002 133702
  com/gemplus/training/code/javacard/ConstantPool.ca
  p
• -rw-rw-rw- 21 20-Feb-2002 133702
  com/gemplus/training/code/javacard/Class.cap
• -rw-rw-rw- 151 20-Feb-2002 133702
  com/gemplus/training/code/javacard/Method.cap
• -rw-rw-rw- 13 20-Feb-2002 133702
  com/gemplus/training/code/javacard/StaticField.cap
  
• -rw-rw-rw- 23 20-Feb-2002 133702
  com/gemplus/training/code/javacard/RefLocation.cap
  
• -rw-rw-rw- 161 20-Feb-2002 133702
  com/gemplus/training/code/javacard/Descriptor.cap
• - ---------- -------- ----------- --------
  --------------------------------------------------
  -
• 504 10
  files

29
How is the code of an applet interpreted ?
30
A reminder on the JVM stack
Bytecode ... aload_1 invokevirtual
5 astore_2 aload_2 sconst_2 ...
31
Example

• Java source of the method increment(APDU apdu)
• byte apduBuffer apdu.getBuffer()
• byte value apduBufferISO7816.OFFSET_P1
• addCounter(value)
• Bytecode of the method increment()
• aload_1
• invokevirtual 5
• astore_2
• aload_2
• sconst_2
• baload
• sstore_3
• aload_0
• sload_3
• invokespecial 10
• return

2
Operand stack
Ref. buff
Ref. buff
Local variables
Ref. APDU
this
32
How do applets communicate to each other ?
33
By invoking methodson other applets

• On other applets in the same package
• On some specific JCRE objects
• On shareable objects of applets in the others
  packages

34
How does an applet communicate to the external
world ?
35
Selection Mechanism
Select ( CM )
Card Manager deselect()
OS cmd ( Install )
C A D
J C R E
a
JC Applet select() process()
Select ( AID )
b
c
Applicative cmd (debit )
36
Execution of an applicative command
37
APDU object and APDU buffer

• APDU object
• owned by the JCRE
• encapsulates a byte array buffer used to
• APDU header and data bytes
• response data
• APDU buffer
• length 5 bytes of header and 32 bytes of data
• JCRE must zero out the APDU buffer before each
  new message

38
APDU class receiving data

• getBuffer()
• returns the APDU buffer byte array, filled
  withAPDU header
• setIncomingAndReceive()
• sets the transfer direction to inbound
• receives the incoming data in the APDU buffer at
  offset 4
• receiveBytes(short offset)
• sets the transfer direction to inbound
• receives the incoming data in the APDU buffer at
  user offset

39
APDU class sending back data

• setOutgoing()
• Sets the transfer direction to outbound
• Obtains the expected length
• setOutgoingLength(short length)
• Sets the expected length
• sendBytes(short offset, short length)
• Sends length bytes from the APDU buffer starting
  at offset
• sendBytesLong(byte array, short offset, short
  length)
• Sends length bytes from another byte array
  starting at offset
• setOutgoingAndSend(short offset, short length)
• setOutgoing() setOutgoingLength() sendBytes

40
Exceptions
41
Exception Handling
try Normal flow catch (MyException me)
if error 1 catch (Exception2 e2) if error
2 finally whatever happens
Method A
I can handle such an exception with my try/catch
part
JCVM
A
Exception ! eException
B
methodB(.) throws eException ...
Method B
42
java.lang Exceptions
43
javacard.framework Exceptions
Throwable
Exception
RunTimeException
CardRuntimeException
CardException
Unchecked
ISOException
APDUException
UserException
Checked
PINException
TransactionException
throws try catch
SystemException
44
Pre-created exception objects

• JCRE pre-creates an instance of each kind of
  CardRuntimeException and CardException
• ? use the static method xxxException.throwIt()rat
  her than throw new xxxException