Development Kit User’s Guide Table Of ContentsPrevious ChapterNext ChapterBook Index

C H A P T E R  9
Using the Reference Implementation

This chapter describes how to execute the commands to run the Java Card 3 Platform, Classic Edition Reference Implementation (RI), Version 3.0.2. The RI provides a Java Card runtime environment (RE) executable for the Microsoft Windows XP platform, as well as Java Card RE packages and an installer applet.

The RI is a simulator that can be built with a ROM mask, much like a Java Card technology-based implementation for actual field use. It has the ability to simulate persistent memory (EEPROM), and to save and restore the contents of EEPROM to and from disk files. Applets can be installed in the RI, and it performs I/O via a socket interface, simulating the interaction with a card reader implementing the protocols T=1, T=CL, or T=0 for communications with the card reader (CAD).

The Java Card RI supports the following:

In version 3.0.2 of the development kit, the RI is available as a 32-bit implementation that supports the ability to go beyond the 64KB memory access. The official RI supports the protocols T=1 and T=CL in dual concurrent interface mode. This development kit also support the two protocols T=0 and T=1, both in single interface mode. TABLE 9-28 lists the Java Card RE executables by protocol.

Running the RI

The binary versions of the REs available in this development kit are provided in the JC_CLASSIC_HOME\bin directory as the executables cref_t0.exe, cref_t1.exe, and cref_tdual.exe. Each binary corresponds to the supported protocols as shown in TABLE 9-28.


TABLE 9-28 Protocols Supported by RE Executables

RE Executable

Supported Protocol

cref_t0.exe

T=0 protocol (single port), as defined in ISO 7816.

cref_t1.exe

T=1 protocol (single port), as defined in ISO 7816.

cref_tdual.exe

T=1 and T=CL (each on separate port). Uses T=1 for the contact protocol, and the T=CL for the contactless version, as defined in ISO 14473. This is the default executable for cref.bat.



Note - The descriptions, command-line syntax, and options in this chapter for running the formal RI (cref_tdual.exe) also apply to the additional supplied Java Card REs, cref_t0.exe and cref_t1.exe. The difference is solely in the supported protocols.

The development kit also includes the executable cref.bat file whose default is to run the RI with T=1/T=CL, but it can also run using the other supported protocols according to arguments shown in TABLE 9-29 Case Sensitive Command Line Options for cref.bat.

You run cref from the bin directory as the working directory to execute the RI as follows (TABLE 9-29 lists the command-line options.): 

cref.bat [options]

Note - The file to invoke cref is a batch file (cref.bat) that must be run from a working directory of JC_CLASSIC_HOME\bin in order for the code to execute properly.

The output of the simulation is logged to standard output, which can be redirected to any desired file. The output stream can range from nothing to very verbose, depending on the command line options selected.


TABLE 9-29 Case Sensitive Command Line Options for cref.bat

Option

Description

[-t0 | -t1 | -tdual]

Specifies the RE version to run according to the desired protocol (see TABLE 9-28). Defaults to -tdual to call cref_tdual.exe if not specified.

-b

Dumps a bytecode histogram at the end of the execution.

-e

Displays the program counter and stack when an exception occurs.

-h, -help

Prints a help screen.

-i input-file-name

Specifies a file to initialize EEPROM. There can be no spaces in the file name argument.

-n

Performs a trace display of the native methods that are invoked.

-nobanner

Suppresses the printing of a program banner.

-nomeminfo

Suppresses the printing of memory statistics when execution starts.

-o output-filename

Saves the EEPROM contents to the named file.

-e2p file-name

Specifies the EEPROM file. If the file exists it is read to initialize the EEPROM image. All e2p images are written to this file. This option is the same as combining -i and -o into one.

-p port-number

Connects to a TCP/IP port using the specified port-number.

-contactedport port-number

Connects to a TCP/IP port using the specified port-number.

-s

Suppresses output. Does not create any output unless followed by other flag options.

-t

Performs a line-by-line trace display of the mask’s execution.

-version

Prints only the program’s version number. Do not execute.

-z

Prints the resource consumption statistics.


Installer Mask

The development kit installer, the Java Card virtual machine interpreter, and the Java Card platform framework are built into the Installer mask. It can be used as-is to load and run applets. Other than the installer, it does not contain any applets.

The RI requires no other files to start proper interpretation and execution of the mask image’s Java Card technology-based bytecode.

Obtaining Resource Consumption Statistics

The Java Card RI provides the -z command line option for printing resource consumption statistics. This option enables it to print statistics regarding memory usage once at startup and once at shutdown. Although memory usage statistics will vary among Java Card RE implementations, this option provides the applet developer with a general idea of the amount of memory needed to install and execute an applet.


Note - In addition to the command line option, the Java Card API provides programmatic mechanisms for determining resource usage. For more information on these mechanisms, see the javacard.framework.JCSystem.getAvailableMemory() method in the Application Programming Interface, Java Card Platform, Version 3.0.1,Classic Edition.

Getting Resource Statistics With the PhotoCard Sample

This section uses the PhotoCard sample program to download and install an applet to illustrate using the large address space available in the 32-bit version of the RI (see PhotoCard Sample). The sample uses the large address space of the smart card’s EEPROM memory to store up to four GIF images. Statistics are provided regarding the following resources: EEPROM, transaction buffer, stack usage, clear-on-reset RAM, and clear-on-deselect RAM. The statistics are printed twice, once at RI start up and once when it shuts down.

CODE EXAMPLE 9-1 shows the output obtained by running the PhotoCard sample program from the bin directory with the following command line including the -z option: 

JC_CLASSIC_HOME\bin> cref_tdual -z -o e2p

This particular example shows the resources used to download and execute a single application. These statistics can also be used to install a set of applications and execute several transactions.

 


CODE EXAMPLE 9-1 PhotoCard Sample Showing Resource Statistic Output 
Java Card 3.0.2 C Reference Implementation Simulator (version 0.41)
32-bit Address Space implementation - with cryptography support
T=1 / T=CL Dual interface APDU protocol (ISO 7816-3)
Copyright 2009 Sun Microsystems, Inc. All rights reserved.
 
Memory configuration
        Type    Base    Size    Max Addr
        RAM     0x0     0x1000  0xfff
        ROM     0x2000  0xe000  0xffff
        E2P     0x10020 0xffe0  0x1ffff
 
        ROM Mask size =                 0xcec9 =        52937 bytes
        Highest ROM address in mask =   0xeec8 =        61128 bytes
        Space available in ROM =        0x1137 =        4407 bytes
EEPROM will be saved in file "e2p"
Mask has now been initialized for use
        0 bytecodes executed.
        Stack size: 00384 (0x0180) bytes,          00000 (0x0000) maximum used
        EEPROM use: 06994 (0x1b52) bytes consumed, 58510 (0xe48e) available
Transaction buffer: 00000 (0x0000) bytes consumed, 03560 (0x0de8) available
Clear-On-Reset RAM: 00000 (0x0000) bytes consumed, 00576 (0x0240) available
Clear-On-Dsel. RAM: 00000 (0x0000) bytes consumed, 00256 (0x0100) available
CREF was powered down.
   132232 bytecodes executed.
        Stack size: 00384 (0x0180) bytes,          00252 (0x00fc) maximum used
        EEPROM use: 09558 (0x2556) bytes consumed, 55946 (0xda8a) available
Transaction buffer: 00000 (0x0000) bytes consumed, 03560 (0x0de8) available
Clear-On-Reset RAM: 00198 (0x00c6) bytes consumed, 00378 (0x017a) available
Clear-On-Dsel. RAM: 00025 (0x0019) bytes consumed, 00231 (0x00e7) available
Temporary memory usage:
    Java stack: 0 bytes
    Clear on Deselect, channel space 0 : 0 bytes
    Clear on Deselect, channel space 1 : 0 bytes
    Clear on Deselect, channel space 2 : 0 bytes
    Clear on Deselect, channel space 3 : 0 bytes
    Clear on Deselect, channel space 4 : 0 bytes
    Clear on Deselect, channel space 5 : 0 bytes
    Clear on Deselect, channel space 6 : 0 bytes
    Clear on Deselect, channel space 7 : 0 bytes
    Clear on Reset: 0 bytes
 
C:\JCDK3.0.2\bin>cref_tdual -z -i e2p
Java Card 3.0.2 C Reference Implementation Simulator (version 0.41)
32-bit Address Space implementation - with cryptography support
T=1 / T=CL Dual interface APDU protocol (ISO 7816-3)
Copyright 2009 Sun Microsystems, Inc. All rights reserved.
 
Memory configuration
        Type    Base    Size    Max Addr
        RAM     0x0     0x1000  0xfff
        ROM     0x2000  0xe000  0xffff
        E2P     0x10020 0xffe0  0x1ffff
 
        ROM Mask size =                 0xcec9 =        52937 bytes
        Highest ROM address in mask =   0xeec8 =        61128 bytes
        Space available in ROM =        0x1137 =        4407 bytes
EEPROM (0xffe0 bytes) restored from file "e2p"
Using a pre-initialized Mask
        0 bytecodes executed.
        Stack size: 00384 (0x0180) bytes,          00000 (0x0000) maximum used
        EEPROM use: 09558 (0x2556) bytes consumed, 55946 (0xda8a) available
Transaction buffer: 00000 (0x0000) bytes consumed, 03560 (0x0de8) available
Clear-On-Reset RAM: 00198 (0x00c6) bytes consumed, 00378 (0x017a) available
Clear-On-Dsel. RAM: 00025 (0x0019) bytes consumed, 00231 (0x00e7) available
CREF was powered down.
  4624835 bytecodes executed.
        Stack size: 00384 (0x0180) bytes,          00250 (0x00fa) maximum used
        EEPROM use: 56993 (0xdea1) bytes consumed, 08511 (0x213f) available
Transaction buffer: 00000 (0x0000) bytes consumed, 03560 (0x0de8) available
Clear-On-Reset RAM: 00198 (0x00c6) bytes consumed, 00378 (0x017a) available
Clear-On-Dsel. RAM: 00125 (0x007d) bytes consumed, 00131 (0x0083) available
Temporary memory usage:
    Java stack: 0 bytes
    Clear on Deselect, channel space 0 : 0 bytes
    Clear on Deselect, channel space 1 : 0 bytes
    Clear on Deselect, channel space 2 : 0 bytes
    Clear on Deselect, channel space 3 : 0 bytes
    Clear on Deselect, channel space 4 : 0 bytes
    Clear on Deselect, channel space 5 : 0 bytes
    Clear on Deselect, channel space 6 : 0 bytes
    Clear on Deselect, channel space 7 : 0 bytes
    Clear on Reset: 0 bytes

RI Limits

Input and Output

The RI performs I/O via a socket interface, simulating the interaction with a card reader implementing T=1, T=CL, or T=0 communications with the card reader.

Use apdutool to read script files and send APDUs via a socket to the RI. See apdutool Examples for details. Note that you can have the Java Card RI running on one workstation and run apdutool on another workstation.

Working With EEPROM Image Files

You can save the state of EEPROM contents, then load it in a later invocation of the RI. To do this, specify an EEPROM image or “store” file to save the EEPROM contents.

Use the -i and -o flags to manipulate EEPROM image files at the cref command line:

The -i and -o flags do not conflict with the performance of other option flags.

The commit of EEPROM memory changes during the execution of the Java Card RI is not affected by the -o flag. Neither standard nor error output is written to the output file named with the -o option.

Input EEPROM Image File

The following example shows how the -i flag can be used in a useful execution scenario. 

cref -i e2save

The RI attempts to initialize simulated EEPROM from the EEPROM image file named e2save. No output file will be created.

Output EEPROM Image File

The following example shows how the -o flag can be used in a useful execution scenario. 

cref -o e2save

The Java Card RI writes EEPROM data to the file e2save. The file will be created if it does not currently exist. Any existing EEPROM image file named e2save is overwritten.

Same Input and Output EEPROM Image File

The following example shows how the -o and -i flag can be used in a useful execution scenario 

cref -i e2save -o e2save

The Java Card RI attempts to initialize simulated EEPROM from the EEPROM image file named e2save, and during processing, saves the contents of EEPROM to e2save, overwriting the contents. This behavior is much like a real Java Card technology-compliant smart card in that the contents of EEPROM are persistent.

Different Input and Output EEPROM Image Files

The following example shows how the -o and -i flag can be used in a useful execution scenario 

cref -i e2save_in -o e2save_out

The RI attempts to initialize simulated EEPROM from the EEPROM image file named e2save_in, and during processing, writes EEPROM updates to a EEPROM image file named e2save_out. The output file will be created if it does not exist. Using different names for input and output EEPROM image files eliminates much potential confusion. This command line can be executed multiple times with the same results.


Note - Be careful when naming your EEPROM image files. The Java Card RI will overwrite an existing file specified as an output EEPROM image file. This can, of course, cause a problem if there is already an identically named file with a different purpose in the same directory.

The Default ROM Mask

The Default ROM Mask Version 3.0.2 of the RI provides protocol-related versions of a 32-bit Java Card RE executable (cref_tdual.exe) for the Microsoft Windows XP platform, as well as Java Card RE packages and an installer applet.



Development Kit User’s Guide December-2009 Table Of ContentsPrevious ChapterNext ChapterBook Index

Copyright © 2009 Sun Microsystems, Inc. All rights reserved.